Autenticar usuários e adquirir tokens para agentes interativos

Agentes interativos tomam ações em nome dos usuários. Para agir em nome dos usuários com segurança, o agente autentica o usuário, obtém consentimento para as permissões necessárias e adquire tokens de acesso para APIs downstream. Este artigo orienta você pelo fluxo de autenticação de ponta a ponta e aquisição de token para seu agente interativo:

  1. Conceda permissões por meio de permissões herdáveis ou consentimento.
  2. Autentique o usuário e obtenha um token de acesso.
  3. Valide o token e extraia declarações de usuário.
  4. Adquira tokens para APIs de downstream usando o fluxo On-Behalf-Of (OBO).

Observação

Este artigo aborda agentes interativos que atuam em nome de usuários conectados usando o fluxo OBO. Se o agente precisar de sua própria identidade semelhante ao usuário (um cenário de trabalho digital), consulte as contas de usuário do Agente e o fluxo OAuth da conta de usuário do Agente.

Pré-requisitos

Antes de começar, verifique se você tem:

Para autorização de administrador, você também precisa:

Antes que o agente possa agir em nome de um usuário, o usuário ou um administrador deve consentir com as permissões necessárias. Há duas abordagens para conceder permissões:

  • Permissões herdáveis: pré-autenticar permissões no blueprint para que as identidades do agente as herdem automaticamente.
  • Solicitar consentimento: registre um URI de redirecionamento e solicite aos usuários ou administradores que concedam consentimento por meio de uma solicitação OAuth ou usem o ponto de extremidade de consentimento do administrador.

Usar permissões herdáveis

Configure permissões herdáveis no blueprint de identidade do agente para pré-autorizar um conjunto base de escopos delegados e funções de aplicativo. As identidades do agente criadas a partir do blueprint herdam automaticamente essas permissões sem avisos de consentimento interativos. Para obter mais informações, consulte Configurar permissões herdáveis para blueprints de identidade do agente.

Para solicitar consentimento usando um fluxo OAuth, o blueprint de identidade do agente deve primeiro ser configurado com um URI de redirecionamento. Para modelos, o URI de redirecionamento deve ser do tipo aplicativo da Web. Diferente de URIs de redirecionamento em registros de aplicativos, um URI de redirecionamento em um blueprint não pode ser usado para obter tokens de permissões delegadas. Só response_type=none há suporte na solicitação OAuth2, o que significa que a solicitação registra apenas o consentimento e nenhum token é retornado.

Registrar um URI de redirecionamento

Para atualizar o URI de redirecionamento no blueprint de identidade do agente, primeiro você precisa obter um token de acesso com a permissão delegada AgentIdentityBlueprint.ReadWrite.All. Envie uma solicitação PATCH para o objeto de aplicativo para o blueprint de identidade do 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"
    ]
  }
}

Antes que o agente possa agir em nome de um usuário, o usuário deve consentir com as permissões necessárias. A solicitação de consentimento do usuário não retorna um token. Em vez disso, ele registra que o usuário concedeu permissão ao agente para agir em seu nome. A aquisição de token acontece na Autenticação do usuário e solicita um token.

Importante

Use o ID de cliente de identidade do agente no parâmetro client_id, não o ID do blueprint de identidade do agente.

Para solicitar consentimento a um usuário, construa uma URL de autorização e redirecione o usuário para ela. O agente pode apresentar essa URL de maneiras diferentes, por exemplo, como um link em uma mensagem 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 abre essa URL, Microsoft Entra ID solicita que ele entre e conceda consentimento. Após o consentimento, o usuário é enviado de volta para o URI de redirecionamento.

Os principais parâmetros na URL de autorização de consentimento do usuário são:

  • client_id: O ID do cliente da identidade do agente (não o ID do cliente do blueprint de identidade do agente).
  • response_type: definido como none porque essa solicitação registra apenas o consentimento. A aquisição de token usa response_type=code em Autenticar o usuário e solicitar um token.
  • redirect_uri: Deve corresponder exatamente ao URI de redirecionamento configurado no blueprint de identidade do agente.
  • scope: especifique as permissões delegadas necessárias (por exemplo, User.Read).
  • state: parâmetro opcional para manter o estado entre a solicitação e o retorno de chamada.

Para obter mais informações sobre os conceitos de autorização do OAuth, consulte Permissões e consentimento no plataforma de identidade da Microsoft.

Os agentes também podem solicitar autorização de um administrador do Microsoft Entra ID, que pode conceder consentimento ao agente para todos os usuários em seu locatário. O consentimento do administrador pode ser necessário dependendo das configurações de consentimento configuradas no locatário.

Para conceder consentimento de administrador para todo o locatário, direcione um administrador para a URL a seguir. Use a ID de identidade do agente no client_id parâmetro.

https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/adminconsent
?client_id=<agent-identity-id>
&scope=User.Read
&redirect_uri=<redirect-uri>
&state=xyz123

Depois que o administrador concede consentimento, as permissões se aplicam a todo o locatário. Os usuários não precisam consentir novamente.

Observação

Configure um URI de redirecionamento em seu blueprint e inclua um state parâmetro na solicitação de consentimento. Quando o consentimento é concedido, o usuário é enviado para o URI de redirecionamento, onde você pode exibir a confirmação. Seu endpoint pode usar o parâmetro state para rastrear que a permissão foi concedida. Para agentes de locatário único, você também pode repetir as solicitações de token até que o consentimento seja concedido porque a ID do locatário já é conhecida.

Autenticar o usuário e solicitar um token

Depois que o consentimento é concedido, a aplicação cliente (como uma aplicação de front-end ou um aplicativo móvel) inicia uma solicitação de autorização com código de autorização do OAuth 2.0 para obter um token cujo público-alvo é o blueprint de identidade do agente. Nesta etapa, client_id se refere à ID de aplicativo registrada do próprio aplicativo cliente, e não à identidade do agente ou à ID do blueprint de identidade do agente.

Observação

O redirect_uri nesta solicitação pertence ao registro do aplicativo cliente, não ao URI de redirecionamento do blueprint configurado na etapa anterior de consentimento.

  1. Redirecione o usuário para o endpoint de autorização do Microsoft Entra ID com os seguintes parâmetros:

    GET https://login.microsoftonline.com/<your-tenant-id>/oauth2/v2.0/authorize?client_id=<client-app-id>
&response_type=code
&redirect_uri=<redirect_uri>
&response_mode=query
&scope=api://<agent-blueprint-id>/access_agent
&state=abc123

  2. Depois que o usuário entra, seu aplicativo recebe um código de autorização no URI de redirecionamento. Troque o código de autorização por um token de acesso:

    POST https://login.microsoftonline.com/<your-tenant-id>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<client-app-id>
&grant_type=authorization_code
&code=<authorization_code>
&redirect_uri=<redirect_uri>
&scope=api://<agent-blueprint-id>/access_agent
&client_secret=<client-secret>

    Inclua o client_secret parâmetro somente se estiver usando um cliente confidencial.

    A resposta JSON contém um token de acesso que pode ser usado para acessar a API do agente.

Validar o token de acesso

A API Web deve validar o token de acesso de entrada antes que o agente possa agir. Sempre use uma biblioteca aprovada para validar tokens. Não escreva seu próprio código de validação de token.

  1. Instale o pacote NuGet Microsoft.Identity.Web:

    dotnet add package Microsoft.Identity.Web

  2. Em seu projeto de API Web ASP.NET Core, implemente a autenticação Microsoft Entra ID:

    // Program.cs
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

  3. Configure as credenciais de autenticação no arquivo appsettings.json.

    Aviso

    Segredos do cliente não devem ser usados como credenciais de cliente em ambientes de produção para esquemas de identidade de agente devido a riscos de segurança. Em vez disso, use métodos de autenticação mais seguros, como fic (credenciais de identidade federadas) com identidades gerenciadas ou certificados de cliente. Esses métodos fornecem segurança aprimorada eliminando a necessidade de armazenar segredos confidenciais diretamente na configuração do aplicativo.

    "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<your-tenant-id>",
    "ClientId": "<agent-blueprint-id>",
    "Audience": "<agent-blueprint-id>",
    "ClientCredentials": [
        {
            "SourceType": "ClientSecret",
            "ClientSecret": "your-client-secret"
        }
    ]
}

Para obter mais informações sobre Microsoft. Identity.Web, consulte Microsoft. Documentação do Identity.Web.

Validar declarações de usuário

Após a validação do token de acesso, o agente pode identificar o usuário e executar verificações de autorização. A rota de API de exemplo a seguir extrai as declarações do usuário do token de acesso e as retorna na resposta da API:

app.MapGet("/hello-agent", (HttpContext httpContext) =>
{   
    var claims = httpContext.User.Claims.Select(c => new
    {
        Type = c.Type,
        Value = c.Value
    });

    return Results.Ok(claims);
})
.RequireAuthorization();

Adquirir tokens para APIs de fluxo descendente

Depois que um agente interativo valida o token do usuário, ele pode solicitar tokens de acesso para chamar APIs downstream em nome do usuário. O fluxo OBO (On-Behalf-Of) permite que o agente:

  • Receber um token de acesso de um cliente.
  • Troque-o por um novo token de acesso para uma API downstream, como o Microsoft Graph.
  • Use esse novo token para acessar recursos protegidos em nome do usuário original.

A biblioteca Microsoft.Identity.Web simplifica a implementação do OBO manipulando a troca de tokens automaticamente, para que você não precise implementar manualmente o fluxo seguindo o protocolo.

  1. Instale os pacotes NuGet necessários:

    dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.AgentIdentities

  2. Em seu projeto de API da Web no ASP.NET Core, implemente a atualização da autenticação Microsoft Entra ID:

    // Program.cs
using Microsoft.AspNetCore.Authorization;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.Resource;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi();
builder.Services.AddAgentIdentities();
builder.Services.AddInMemoryTokenCaches();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.Run();

  3. Na API do agente, troque o token de acesso do usuário de entrada por um novo token de acesso para a identidade do agente. Microsoft.Identity.Web valida o token de acesso recebido e gerencia a troca de tokens em nome de terceiros:

    app.MapGet("/agent-obo-user", async (HttpContext httpContext) =>
{
    string agentIdentity = "<your-agent-identity>";
    IAuthorizationHeaderProvider authorizationHeaderProvider = httpContext.RequestServices.GetService<IAuthorizationHeaderProvider>()!;
    AuthorizationHeaderProviderOptions options = new AuthorizationHeaderProviderOptions().WithAgentIdentity(agentIdentity);

    string authorizationHeaderWithUserToken = await authorizationHeaderProvider.CreateAuthorizationHeaderForUserAsync(["https://graph.microsoft.com/.default"], options);

    var response = new { header = authorizationHeaderWithUserToken };
    return Results.Json(response);
})
.RequireAuthorization();

Nos bastidores, o fluxo OBO envolve duas trocas de tokens: primeiro, o blueprint de identidade do agente obtém um token de troca usando suas credenciais de cliente e, em seguida, o modelo de identidade do agente troca esse token juntamente com o token de acesso do usuário por um token de API subsequente. Para obter uma descrição completa do protocolo, incluindo formatos de requisição HTTP e detalhes de validação de token, consulte Fluxo On-Behalf-Of em agentes.

Conteúdo relacionado

Saiba mais sobre tokens de agente e APIs relacionadas:

  • Last updated on