Autenticar utilizadores e adquirir tokens para agentes interativos

Agentes interativos tomam ações em nome dos utilizadores. Para agir em nome dos utilizadores de forma segura, o agente autentica o utilizador, obtém consentimento para as permissões necessárias e adquire tokens de acesso para APIs a jusante. Este artigo guia-o pelo processo completo de autenticação e aquisição de tokens para o seu agente interativo:

  1. Conceda permissões através de permissões hereditárias ou consentimento.
  2. Autentique o utilizador e obtenha um token de acesso.
  3. Valida o token e extrai as reivindicações dos utilizadores.
  4. 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:

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

Antes de o agente poder agir em nome de um utilizador, o utilizador ou um administrador deve consentir com as permissões necessárias. Existem duas abordagens para conceder permissões:

  • Permissões herdáveis: Pré-autorize permissões no blueprint para que as identidades dos agentes as herdem automaticamente.
  • Solicitar consentimento: Registar um URI de redirecionamento e pedir aos utilizadores ou administradores que concedam consentimento através de um pedido OAuth ou utilizem o endpoint de consentimento de administrador.

Usar permissões herdadas

Configure permissões herdáveis no modelo de identidade do agente para pré-autorizar um conjunto básico de âmbitos delegados e funções da aplicação. As identidades dos agentes criadas a partir do blueprint herdam automaticamente essas permissões sem pedidos interativos de consentimento. Para mais informações, consulte Configurar permissões herdáveis para modelos de identidade do agente.

Para solicitar consentimento por meio de um fluxo OAuth, o modelo de identidade do seu agente tem primeiro de ser configurado com um URI de redirecionamento. Para blueprints, o URI de redirecionamento deve ser um tipo de aplicação web . Ao contrário dos URIs de redirecionamento nos registos de aplicações, um URI de redirecionamento num esquema não pode ser utilizado para obter tokens de permissões delegadas. Só response_type=none é suportado no pedido OAuth2, o que significa que o pedido regista apenas o consentimento e nenhum token é devolvido.

Registar um URI de redirecionamento

Para atualizar o URI de redirecionamento no blueprint de identidade do agente, precisa primeiro de obter um token de acesso com a permissão AgentIdentityBlueprint.ReadWrite.Alldelegada. Depois, envie um pedido PATCH ao objeto de aplicação para obter 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 de o agente poder agir em nome de um utilizador, este deve consentir as permissões necessárias. O pedido de consentimento do utilizador 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 em Autenticar o utilizador e pedir um token.

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.

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.

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 esta URL, o Microsoft Entra ID pede-lhe que inicie sessão e conceda consentimento. Após o consentimento, o utilizador é enviado de volta para o URI de redirecionamento.

Os parâmetros-chave na URL de autorização de consentimento do utilizador 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=codeem Autenticar o utilizador e solicitar um token.
  • redirect_uri: Deve corresponder exatamente ao URI de redirecionamento configurado no modelo de identidade do agente.
  • 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.

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

Para conceder consentimento de administrador a nível de locatário, encaminhe um administrador para o seguinte URL. Use o 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 de o administrador conceder o consentimento, as permissões aplicam-se a todo o inquilino. Os utilizadores não precisam de consentir novamente.

Observação

Configure um URI de redirecionamento no seu blueprint e inclua um state parâmetro no pedido de consentimento. Quando o consentimento é concedido, o utilizador é enviado para o URI de redirecionamento onde pode mostrar a confirmação. O teu endpoint pode usar o state parâmetro para rastrear se essa permissão foi concedida. Para agentes de inquilino único, pode, em alternativa, repetir os pedidos de token até que o consentimento seja dado, porque o ID do inquilino já é conhecido.

Autentique o utilizador e solicite um token

Depois de o consentimento ser concedido, a aplicação cliente (como um frontend ou uma aplicação móvel) inicia um pedido OAuth 2.0 de código de autorização para obter um token cujo público-alvo é o modelo de identidade do agente. Neste passo, client_id refere-se ao ID de aplicação registado da aplicação cliente, não à identidade do agente ou ao blueprint de identidade do agente.

Observação

O redirect_uri no pedido pertence ao registo da aplicação cliente , não ao URI de redirecionamento do blueprint configurado no passo de consentimento anterior.

  1. Redirecione o utilizador 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 de o utilizador iniciar sessão, a sua aplicação 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 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

A API web deve validar o token de acesso recebido antes que o agente possa agir. Use sempre uma biblioteca aprovada para validar os tokens. Não escrevas o teu próprio código de validação de token.

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

    dotnet add package Microsoft.Identity.Web

  2. No 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 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": "<your-tenant-id>",
    "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

Após a validação do token de acesso, o agente pode identificar o utilizador e realizar verificações de autorização. O seguinte 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.

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.

  1. Instale os pacotes NuGet necessários:

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

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

  3. Na API do agente, troque o token de acesso recebido do utilizador por um novo token de acesso da 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();

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.

Conteúdo relacionado

Saiba mais sobre tokens de agente e APIs relacionadas:

  • Last updated on