Autenticar utilizadores e adquirir tokens para agentes interativos

Agentes interativos tomam ações em nome dos utilizadores. Para o fazer de forma segura, o agente deve autenticar o utilizador, obter consentimento para as permissões necessárias e adquirir tokens de acesso para APIs a jusante. Este artigo guia-o como implementar o fluxo de ponta a ponta para o seu agente interativo:

Registe um URI de redirecionamento para o esquema de identidade do seu agente.
Configurar autorização do utilizador ou administrador (consentimento).
Autentique o utilizador e obtenha um token de acesso.
Valida o token e extrai as reivindicações dos utilizadores.
Adquira tokens para APIs a jusante utilizando o fluxo On-Behalf-Of (OBO).

Observação

Este artigo aborda agentes interativos que atuam em nome dos utilizadores iniciados através do fluxo OBO. Se o seu agente precisa de uma identidade semelhante ao utilizador (um cenário de trabalhador digital), veja as contas de utilizador do Agente e o fluxo OAuth da conta de utilizador do Agente.

Pré-requisitos

Antes de começar, certifique-se de que tem:

Um plano de identidade de agente. Regista o ID da aplicação do blueprint da identidade do agente (ID do cliente).
A identidade de um agente.
Uma aplicação cliente registada na Microsoft Entra para tratar da autenticação dos utilizadores.
Familiaridade com o fluxo de código de autorização do OAuth 2.0.

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

Acesso do administrador para conceder consentimento para permissões de aplicação.

Registar um URI de redirecionamento

Para suportar permissões delegadas, o blueprint de identidade do seu agente deve estar configurado com um URI de redirecionamento válido. Este URI é onde o Microsoft Entra ID envia os utilizadores depois de concederem ou negarem consentimento ao seu agente.

Microsoft Graph API
Microsoft Graph PowerShell

Para enviar este pedido, primeiro precisa de 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 autorização do utilizador

Antes de o agente poder agir em nome de um utilizador, este deve consentir as permissões necessárias. Este passo de consentimento não devolve um token. Em vez disso, regista que o utilizador concedeu permissão ao agente para agir em seu nome. A aquisição de tokens ocorre numa etapa posterior.

Para pedir consentimento a um utilizador, constrói uma URL de autorização e redireciona o utilizador para ela. O agente pode apresentar este URL de diferentes formas, por exemplo, como um link numa mensagem de chat.

Importante

Utilize o ID de cliente da identidade do agente no parâmetro client_id, em vez do ID do "blueprint" da 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 utilizador abre este URL, Microsoft Entra ID pede-lhe que inicie sessão e conceda consentimento às permissões especificadas no parâmetro scope. Após o consentimento ser concedido, o utilizador é redirecionado para o URI de redirecionamento especificado.

Os parâmetros-chave na URL de consentimento são:

client_id: O ID de cliente de identidade do agente (não o blueprint de identidade do agente).
response_type: Definir para none porque este pedido regista apenas o consentimento. A aquisição de tokens é usada response_type=code num pedido separado.
redirect_uri: Deve corresponder exatamente ao que configuraste no passo anterior.
scope: Especifique as permissões delegadas de que precisa (por exemplo, User.Read).
state: Parâmetro opcional para manter o estado entre o pedido e o callback.

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

Configurar autorização de administrador

Os agentes também podem solicitar autorização a um administrador do Microsoft Entra ID, que pode conceder autorização ao agente para todos os utilizadores do seu inquilino. As permissões de aplicação requerem autorização de administrador porque os utilizadores individuais não conseguem consentir.

Para conceder consentimento ao administrador, construa a URL de autorização que requer ação do administrador. Use o ID de identidade do agente no pedido seguinte.

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 de o administrador conceder o consentimento, as permissões são aplicadas a todo o tenant e os utilizadores desse tenant não precisam de consentir individualmente essas permissões.

Autentique o utilizador e solicite um token

Após a configuração da autorização, a aplicação cliente (como uma aplicação frontend ou aplicação móvel) inicia um pedido de código de autorização OAuth 2.0 para obter um token cujo destinatário é o blueprint de identidade do agente. Neste passo, client_id refere-se ao ID de aplicação registada da app cliente, não à identidade do agente ou ao ID do modelo de identidade do agente.

Redirecione o utilizador 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 de o utilizador iniciar sessão, a sua aplicação recebe um código de autorização no URI de redirecionamento. Exchange-o 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 apenas se estiver a usar um cliente confidencial.

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

Validar o token de acesso

O agente, normalmente exposto através de uma API web, deve validar o token de acesso. Use sempre uma biblioteca aprovada para realizar a validação de tokens. Nunca implementes o teu próprio código de validação de token.

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

No 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 ficheiro appsettings.json.

Advertência

Os segredos do cliente não devem ser usados como credenciais do cliente em ambientes de produção para modelos de identidade de agentes por motivos de segurança. Em vez disso, utilize métodos de autenticação mais seguros, como credenciais de identidade federada (FIC) com identidades geridas ou certificados de cliente. Estes métodos proporcionam maior segurança ao eliminar a necessidade de armazenar segredos sensíveis diretamente na configuração da sua aplicação.
```
"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 mais informações sobre Microsoft.Identity.Web, consulte documentação do Microsoft.Identity.Web.

Validar as reivindicações dos utilizadores

Depois de validar o token de acesso, o agente pode identificar o utilizador e realizar verificações de autorização. Este exemplo de rota API extrai as reivindicações dos utilizadores do token de acesso e devolve-as 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 a jusante

Depois de um agente de interação validar o token do utilizador, pode solicitar tokens de acesso para chamar APIs subsequentes em nome do utilizador. O fluxo On-Behalf-Of (OBO) permite ao agente:

Receber um token de acesso de um cliente.
Troque-o por um novo token de acesso para uma API a jusante, como Microsoft Graph.
Use esse novo token para aceder a recursos protegidos em nome do utilizador original.

Microsoft Identity Web
Microsoft Graph SDK

A biblioteca Microsoft.Identity.Web simplifica a implementação do OBO ao gerir automaticamente a troca de tokens, por isso não precisa de 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

No seu projeto de API web ASP.NET Core, atualize a implementação de autenticação do 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 recebido por um novo token de acesso para a identidade do agente. Microsoft.Identity.Web valida o token de acesso recebido e gera a troca do token em nome de:

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 estiveres a usar o SDK Microsoft Graph, podes 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

No seu projeto ASP.NET Core Web API, configure a autenticação e adicione suporte para o 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 fornecedor de serviços e chame as APIs Microsoft Graph utilizando 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();

No fundo, o fluxo OBO envolve duas trocas de tokens: primeiro, o blueprint de identidade do agente obtém um token de exchange usando a credencial do cliente, e depois a identidade do agente troca esse token juntamente com o token de acesso do utilizador por um token API a jusante. Para o guia completo do protocolo, incluindo formatos de pedido HTTP e detalhes de validação de tokens, consulte o fluxo On-behalf-of nos agentes.

Comentários

Esta página foi útil?

Last updated on 2026-05-01