Autenticar usuários em agentes interativos

Os agentes geralmente precisam executar ações em nome dos usuários que usam o agente. A primeira etapa para criar um agente interativo é autenticar o usuário. Este artigo explica o processo de criação de um serviço Web simples que autentica um usuário. O modelo de identidade do agente é usado para proteger o serviço web. As etapas incluem:

1. Um cliente obtém um token de acesso delimitado por o blueprint de identidade do agente.
2. Valide esse token na API do agente.
3. Extraia declarações sobre o usuário que podem ser usadas para autorização.

Pré-requisitos

Blueprints de identidade do agente. Registre o ID do aplicativo de identidade do agente blueprint (ID do cliente).

Solicitar um token para o modelo de identidade do agente

Para autenticar um usuário, o aplicativo cliente (como um front-end ou aplicativo móvel) deve iniciar uma solicitação de autorização do OAuth 2.0 para obter um token em que o público-alvo seja o blueprint de identidade do agente.

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

   GET https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/authorize?client_id=<client-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. Você o troca por um token de acesso:

   POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
   Content-Type: application/x-www-form-urlencoded
   
   client_id=<client-id>
   grant_type=authorization_code
   code=<authorization_code>
   redirect_uri=<redirect_uri>
   scope=api://<agent-blueprint-id>/access_agent
   client_secret=<client-secret>  # Only if using a confidential client
   

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

Validar o token na API do agente

O agente, normalmente exposto por meio de uma API Web, deve validar o token de acesso. Sempre use uma biblioteca aprovada para executar a validação de token e nunca deve implementar seu próprio código de validação de token.

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

   dotnet add package Microsoft.Identity.Web
   

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

   // Program.cs
   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. Configurar credenciais de autenticação no arquivo appsettings.json :

"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"TenantId": "<my-test-tenant>",
"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 documentos oficiais.

Validar declarações de usuário

Depois de validar o token de acesso, o agente agora pode identificar o usuário e executar verificações de autorização. Esta rota de API de exemplo extrai declarações de 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();

Conteúdo relacionado

Declarações de token