Autenticar usuários e adquirir tokens para agentes interativos

Agentes interativos tomam ações em nome dos usuários. Para fazer isso com segurança, o agente deve autenticar o usuário, obter consentimento para as permissões necessárias e adquirir tokens de acesso para APIs downstream. Este artigo explica como implementar o fluxo de ponta a ponta para seu agente interativo:

Registre uma URI de redirecionamento para o modelo de identidade do agente.
Configurar autorização de usuário ou administrador (consentimento).
Autentique o usuário e obtenha um token de acesso.
Valide o token e extraia declarações de usuário.
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:

Um blueprint de identidade do agente. Registre o ID do aplicativo de blueprint de identidade do agente (ID do cliente).
Uma identidade de agente.
Um aplicativo cliente registrado em Microsoft Entra para lidar com a autenticação do usuário.
Familiaridade com o fluxo de código de autorização do OAuth 2.0.

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

Acesso do administrador para conceder consentimento para permissões de aplicativo.

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 Microsoft Entra ID envia usuários depois que eles concedem ou negam consentimento ao seu agente.

Microsoft API do Graph
Microsoft Graph PowerShell

Para enviar essa solicitação, primeiro você precisa obter um token de acesso com a permissão AgentIdentityBlueprint.ReadWrite.Alldelegada.

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)

Configurar a autorização do usuário

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

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.

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.

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 às permissões especificadas no parâmetro scope. Depois que o consentimento for concedido, o usuário será redirecionado para o URI de redirecionamento especificado.

Os principais parâmetros na URL de consentimento 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 uma solicitação separada.
redirect_uri: deve corresponder exatamente ao que você configurou na etapa anterior.
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.

Configurar a autorização do administrador

Os agentes também podem solicitar autorização de um administrador do Microsoft Entra ID, que pode conceder autorização ao agente para todos os usuários em seu locatário. As permissões de aplicativo exigem autorização de administrador porque os usuários individuais não podem consentir com eles.

Para conceder consentimento do administrador, construa a URL de autorização que direciona o administrador. Use a ID de identidade do agente na solicitação a seguir.

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

Depois que o administrador concede consentimento, as permissões são aplicadas em todo o locatário e os usuários nesse locatário não precisam consentir individualmente com essas permissões.

Autenticar o usuário e solicitar um token

Depois que a autorização é configurada, o aplicativo cliente (como um frontend ou aplicativo móvel) inicia uma solicitação de código de autorização OAuth 2.0 para obter um token em que o público é o modelo de identidade do agente. Nesta etapa, client_id se refere ao ID de aplicativo registrado do próprio aplicativo cliente, e não à identidade do agente ou ao ID do blueprint de identidade do agente.

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

GET https://login.microsoftonline.com/<my-test-tenant>/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

Depois que o usuário entra, seu aplicativo recebe um código de autorização no URI de redirecionamento. Troque 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-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

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. Nunca implemente seu próprio código de validação de token.

Instale o pacote NuGet Microsoft.Identity.Web:
```
dotnet add package Microsoft.Identity.Web
```

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

// 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();

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": "<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 Microsoft. Documentação do Identity.Web.

Validar declarações de usuário

Depois de validar o token de acesso, o agente poderá 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();

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.

Microsoft Identity Web
Microsoft Graph SDK

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.

Instale os pacotes NuGet necessários:

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

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();

Na API do agente, troque o token de acesso 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();

Se você estiver usando o SDK do Microsoft Graph, poderá autenticar para Microsoft Graph usando o GraphServiceClient.

Instale os pacotes NuGet necessários:

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

Em seu ASP.NET Core projeto de API Web, configure a autenticação e adicione suporte para Microsoft Graph:

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

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Obtenha um GraphServiceClient do provedor de serviços e chame as APIs do Microsoft Graph com a identidade do agente:

app.MapGet("/agent-obo-user", async (HttpContext httpContext) =>
{
    string agentIdentity = "<your-agent-identity>";

    GraphServiceClient graphServiceClient = httpContext.RequestServices.GetService<GraphServiceClient>()!;
    var me = await graphServiceClient.Me.GetAsync(r => r.Options.WithAuthenticationOptions(
        o =>
        {
            o.WithAgentIdentity(agentIdentity);
        }));
    return me.UserPrincipalName;
})
.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.

Comentários

Esta página foi útil?

Last updated on 2026-05-01