Configurar a autorização do usuário para agentes interativos

Os agentes geralmente precisam executar ações em nome dos usuários que usam o agente. Para fazer isso, os agentes interativos precisam solicitar autorização delegada do usuário usando o protocolo OAuth. Este artigo explica o processo de solicitação de consentimento de um usuário usando a identidade do agente. As etapas incluem:

• Atualizando o modelo de identidade do agente com um URI de redirecionamento.
• Construindo uma solicitação de autorização e redirecionando o usuário para a ID do Microsoft Entra.

Pré-requisitos

Antes de solicitar a autorização do usuário, verifique se você tem:

• Uma identidade de agente(create-delete-agent-identities.md)
• Fluxo de código de autorização OAuth 2.0

Registrar um URI de redirecionamento

Para dar suporte a permissões delegadas, o blueprint de identidade do agente deve ser configurado com um URI de redirecionamento válido. Esse URI é onde a ID do Microsoft Entra envia usuários depois que eles concedem ou negam consentimento ao seu 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)

Construir a URL da solicitação de autorização

Agora que o blueprint de identidade do agente tem um URI de redirecionamento válido, você pode construir a URL de autorização usada para solicitar que o usuário conceda permissões delegadas. A URL de autorização segue o padrão de fluxo de código de autorização OAuth 2.0.

Use a ID do cliente de identidade do agente na solicitação a seguir, não a ID do blueprint de identidade do agente. As implementações do agente podem redirecionar o usuário para essa URL de várias maneiras, como incluí-la em uma mensagem enviada ao usuário em uma janela de 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 o usuário é redirecionado para essa URL, ele é solicitado a entrar e conceder consentimento às permissões especificadas no parâmetro de escopo. Depois de conceder consentimento, o usuário será retornado para o URI de redirecionamento especificado.

Os principais parâmetros na URL de autorização são:

• client_id: Use o ID do cliente de identidade do agente (não o ID do cliente da configuração de identidade do agente)
• response_type: definido como none para fluxo de código de autorização
• redirect_uri: deve corresponder exatamente ao que você configurou na etapa anterior
• scope: especifique as permissões delegadas de que você precisa (por exemplo, User.Read)
• state: parâmetro opcional para manter o estado entre a solicitação e o retorno de chamada

Conteúdo relacionado

• Usuários de login para autenticação básica de agente interativo
• Solicitar tokens de usuário para implementar o fluxo on-Behalf-Of
• Permissões e consentimento na plataforma de identidade da Microsoft para conceitos detalhados do OAuth