Configurare l'autorizzazione utente per gli agenti interattivi

Gli agenti spesso devono eseguire azioni per conto degli utenti che usano l'agente. A tale scopo, gli agenti interattivi devono richiedere l'autorizzazione delegata dall'utente usando il protocollo OAuth. Questo articolo illustra il processo di richiesta del consenso da un utente usando l'identità dell'agente. La procedura include i passaggi seguenti:

• Aggiornamento del modello di identità dell'agente con un URI di reindirizzamento.
• Creazione di una richiesta di autorizzazione e reindirizzamento dell'utente all'ID Microsoft Entra.

Prerequisiti

Prima di richiedere l'autorizzazione utente, assicurarsi di disporre di:

• Un'identità di agente (create-delete-agent-identities.md)
• Flusso del codice di autorizzazione OAuth 2.0

Registrare un URI di reindirizzamento

Per supportare le autorizzazioni delegate, il progetto di identità dell'agente deve essere configurato con un URI di reindirizzamento valido. Questo URI è il percorso in cui Microsoft Entra ID invia gli utenti dopo aver concesso o negato il consenso all'agente.

PATCH https://graph.microsoft.com/beta/applications/<agent-blueprint-id>
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "web": {
    "redirectUris": [
      "https://myagentapp.com/authorize"
    ]
  }
}

Connect-MgGraph -Scopes "AgentIdentityBlueprint.ReadWrite.All" -TenantId <your-test-tenant>

$applicationId = "<agent-blueprint-id>"
$web = @{
    redirectUris= @(
        "https://myagentapp.com/authorize"
    )
}

$body = @{
    web   =  $web
}

Invoke-MgGraphRequest -Method PATCH `
        -Uri "https://graph.microsoft.com/beta/applications/$applicationId" `
        -Headers @{ "OData-Version" = "4.0" } `
        -Body ($body | ConvertTo-Json)

Costruire l'URL della richiesta di autorizzazione

Ora che il progetto di identità dell'agente ha un URI di reindirizzamento valido, è possibile costruire l'URL di autorizzazione usato per richiedere all'utente di concedere autorizzazioni delegate. L'URL di autorizzazione segue lo standard del flusso del codice di autorizzazione OAuth 2.0.

Assicurarsi di usare l'ID client di identità dell'agente nella richiesta seguente, non l'ID del progetto di identità dell'agente. Le implementazioni dell'agente potrebbero reindirizzare l'utente a questo URL in diversi modi, ad esempio includerlo in un messaggio inviato all'utente in una finestra di chat.

https://login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/authorize?
  client_id=<agent-identity-id>
  &response_type=none
  &redirect_uri=https%3A%2F%2Fmyagentapp.com%2Fauthorize
  &response_mode=query
  &scope=User.Read
  &state=xyz123

Quando l'utente viene reindirizzato a questo URL, viene chiesto di accedere e concedere il consenso alle autorizzazioni specificate nel parametro di ambito. Dopo aver concesso il consenso, l'utente viene restituito all'URI di reindirizzamento specificato.

I parametri chiave nell'URL di autorizzazione sono:

• client_id: usare l'ID client dell'identità dell'agente (non l'ID client del progetto di identità dell'agente)
• response_type: impostato su none per il flusso del codice di autorizzazione
• redirect_uri: deve corrispondere esattamente a quanto configurato nel passaggio precedente
• scope: specificare le autorizzazioni delegate necessarie (ad esempio, User.Read)
• state: parametro facoltativo per mantenere lo stato tra la richiesta e il callback

Contenuti correlati

• Utenti autenticati per l'autenticazione dell'agente interattivo di base
• Richiedere token utente per l'implementazione del flusso *On-Behalf-Of*
• Autorizzazioni e consenso in Microsoft Identity Platform per concetti dettagliati di OAuth