Autenticar usuários em uma API de agente do ASP.NET Core

Um cliente upstream autentica o usuário e envia um token de acesso à API do agente. Este artigo configura a API do agente ASP.NET Core para validar esse token e mostra um cliente de teste local que entra em um usuário e chama/whoami.

A autenticação estabelece a identidade do chamador. Controle de acesso do usuário aos agentes determina separadamente se essa identidade pode invocar o agente.

Prerequisites

  • Conclusão de Criar uma identidade para o agente, incluindo a habilitação do locatário e a transferência para o administrador. Registre a ID do cliente compartilhado e a ID do objeto da identidade do agente.
  • O SDK do .NET 10. Os exemplos usam Microsoft.Identity.Web 4.17.0.
  • Um aplicativo cliente upstream que pode conectar usuários e solicitar um token de acesso para a API do agente ou permissão para registrar o cliente de teste local.
  • Para a etapa de consentimento de visualização, use o cliente de gerenciamento com o consentimento do administrador para a permissão adicional delegada do Graph DelegatedPermissionGrant.ReadWrite.All. Use um administrador autorizado a dar consentimento para essas permissões delegadas. Escolha a função com suporte de menor privilégio de Conceder consentimento do administrador em todo o locatário e confirme quaisquer requisitos adicionais de consentimento da versão prévia com seu representante Microsoft.
  • Um certificado de desenvolvimento HTTPS local confiável para teste local. Execute dotnet dev-certs https --trust e aprove o prompt de confiança em seu computador de desenvolvimento. Não desabilite a verificação de certificado.

Registrar um cliente de teste local

Ignore esta seção se você já tiver um cliente que permita que os usuários entrem e chame seu agente. Esse cliente de teste é um registro de aplicativo comum separado, e não outra identidade de agente.

  1. Registre um aplicativo single-tenant chamado cliente de teste da API do Agente no locatário do agente.
  2. Em Autenticação, adicione a plataforma de aplicativos móveis e da área de trabalho com URI http://localhostde redirecionamento. Nenhum segredo do cliente é necessário.
  3. Registre a ID do aplicativo (cliente). Em aplicativos empresariais, localize o aplicativo correspondente e registre sua ID de Objeto. As solicitações de token usam a ID do cliente; As concessões de consentimento usam a ID do objeto do aplicativo empresarial.

O cliente usa um navegador e PKCE. O redirecionamento de loopback recebe a resposta de autorização localmente; As chamadas à API ainda usam HTTPS.

Configurar a permissão delegada

O cliente upstream precisa de uma permissão delegada para chamar a API do agente para o usuário conectado.

  1. No plano, exponha um URI do identificador e o escopo delegado. Use access_agent como o valor de escopo para este passo a passo. Preservar scopes existentes e definir api.requestedAccessTokenVersion como 2.
  2. Declare esse escopo no requiredResourceAccess do cliente upstream. Use o ID do cliente do agente compartilhado como resourceAppId e o GUID do escopo exposto com "type": "Scope".
  3. Conceda ao cliente upstream acesso para o usuário de teste, conforme descrito na próxima seção. Durante a visualização, o consentimento do navegador não dá suporte a uma identidade de agente como o recurso.

Para obter mais informações, consulte Configurar um aplicativo cliente para acessar uma API Web e permissões e consentimento no plataforma de identidade da Microsoft.

Configure o cliente upstream seguindo o fluxo de autenticação para esse tipo de cliente. Por exemplo, consulte o fluxo de código de autorização do OAuth 2.0. Solicite o escopo da API do agente totalmente qualificado:

api://<agent-client-id>/access_agent

Use uma biblioteca de autenticação no cliente upstream. Não envie tokens de ID ou códigos de autorização para a API do agente.

Conceder acesso ao cliente upstream

Use o cliente de gerenciamento para essas solicitações do Microsoft Graph, não a credencial de runtime do agente. Essa concessão autoriza o cliente upstream a chamar o agente; ele não concede ao agente acesso a APIs downstream.

Antes de executar as solicitações, abra o registro do aplicativo de gerenciamento no centro de administração do Microsoft Entra. Em permissões de API, selecione Adicionar uma permissão>Microsoft Graph>Permissões delegadas, adicione DelegatedPermissionGrant.ReadWrite.All e peça a um administrador autorizado que conceda o consentimento. Mantenha as duas permissões de gerenciamento do provisionamento. Não adicione essas permissões ao agente ou ao cliente de teste.

Reconecte-se com os três escopos com consentimento:

Disconnect-MgGraph
Connect-MgGraph -ClientId "<management-app-client-id>" `
    -TenantId "<tenant-id>" `
    -Scopes "AgentIdentityBlueprint.ReadWrite.All", "AgentIdentity.ReadWrite.All", "DelegatedPermissionGrant.ReadWrite.All" `
    -ContextScope Process

Use Invoke-MgGraphRequest conforme mostrado em Configurar o cliente de gerenciamento.

  1. Verifique se há uma concessão aplicável existente:

    GET https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq '<upstream-client-service-principal-object-id>' and resourceId eq '<agent-identity-object-id>'
    

    Siga a paginação. Uma concessão aplicável em todo o locatário ou uma concessão para o usuário de teste já pode incluir access_agent.

  2. Se não houver nenhuma concessão aplicável, conceda acesso para o único usuário que fará login:

    POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
    Content-Type: application/json
    
    {
      "clientId": "<upstream-client-service-principal-object-id>",
      "resourceId": "<agent-identity-object-id>",
      "consentType": "Principal",
      "principalId": "<user-object-id>",
      "scope": "access_agent"
    }
    

    clientId e resourceId são IDs de objeto do service principal, não IDs de cliente OAuth. Se já existir uma concessão para esse usuário, mas não tiver o escopo, atualize o escopo de concessão de permissão OAuth2 com a união de escopos existentes e necessários. Não crie uma duplicata ou remova escopos não relacionados.

  3. Registre o ID da concessão id para limpeza. Entre como esse usuário quando você executar o cliente de teste. Não force um novo prompt de consentimento para o recurso do agente.

Configurar a validação de token

Crie o projeto de API do agente se você ainda não tiver um:

dotnet new webapi --framework net10.0 --name AgentApi
cd AgentApi

Instale Microsoft.Identity.Web no diretório do projeto:

dotnet add package Microsoft.Identity.Web --version 4.17.0

Configure a API do agente em appsettings.json:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<tenant-id>",
    "ClientId": "<agent-client-id>"
  }
}

Substitua o Program.cs do projeto pelo código a seguir. Ele requer o access_agent escopo antes de retornar a identidade validada do chamador:

using System.Security.Claims;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.Resource;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMicrosoftIdentityWebApiAuthentication(
    builder.Configuration);
builder.Services.AddAuthorization();

var app = builder.Build();

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

app.MapGet("/whoami", (HttpContext context) =>
{
    context.VerifyUserHasAnyAcceptedScope("access_agent");

    ClaimsPrincipal user = context.User;
    string? objectId = user.GetObjectId();
    string? tenantId = user.GetTenantId();

    return Results.Ok(new { objectId, tenantId });
})
.RequireAuthorization();

app.Run();

AddMicrosoftIdentityWebApiAuthentication valida a assinatura do token, o emissor, o público-alvo e o tempo de vida. As políticas de autorização podem avaliar escopos, funções de aplicativo e outras declarações.

VerifyUserHasAnyAcceptedScope rejeita um token válido que não contém a access_agent permissão delegada.

Use GetObjectId() e GetTenantId() para ler a identidade estável. Esses auxiliares lidam com os nomes de declaração JWT originais e os nomes de declaração mapeados pelo middleware de autenticação.

Entender o caminho da solicitação

  1. O cliente upstream autentica o usuário.
  2. O cliente obtém um token de acesso para access_agent.
  3. O cliente envia Authorization: Bearer <token> para a API do agente.
  4. O middleware de autenticação de ASP.NET Core valida o token.
  5. A interface de programação de aplicações (API) do agente aplica sua política de autorização.

Executar o cliente de teste

Inicie a API do agente:

dotnet run --urls https://localhost:5001

Em outro terminal, crie um projeto de console fora do diretório da API do agente:

dotnet new console --framework net10.0 --name AgentTestClient
cd AgentTestClient
dotnet add package Microsoft.Identity.Client

Substitua o Program.cs do projeto de console por este código. Substitua a ID do locatário, a ID do cliente do cliente de teste e a ID do cliente compartilhado do agente:

using System.Net.Http.Headers;
using Microsoft.Identity.Client;

var client = PublicClientApplicationBuilder.Create("<upstream-client-id>")
    .WithAuthority("https://login.microsoftonline.com/<tenant-id>")
    .WithRedirectUri("http://localhost")
    .Build();

var result = await client
    .AcquireTokenInteractive(["api://<agent-client-id>/access_agent"])
    .ExecuteAsync();

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", result.AccessToken);
using var response = await http.GetAsync("https://localhost:5001/whoami");
Console.WriteLine($"HTTP {(int)response.StatusCode}");
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Execute dotnet run e entre como o usuário nomeado na concessão de consentimento. Espere HTTP 200 e a ID do objeto desse usuário e a ID do locatário. Uma solicitação para /whoami sem um token deve retornar 401. Não registre o token ou use um token de ID em seu lugar.

Se a API expor outro escopo delegado e seu cliente de teste tiver consentimento, solicite também um token apenas para esse escopo e chame /whoami. Confirme se o token tem o público-alvo da API do agente, mas não tem access_agent, e se a solicitação é rejeitada. Esse teste opcional de escopo negativo requer um segundo escopo; a configuração local mínima define apenas access_agent. Um token para um público-alvo diferente testa a validação do público-alvo, não a autorização de escopo.

Se o login falhar, verifique o URI de redirecionamento do cliente de teste e a concessão por usuário antes de alterar a configuração do agente. Se o HTTPS falhar, corrija a confiança do certificado de desenvolvimento em vez de ignorar a validação.

Limpar o teste local

Interrompa os dois projetos quando terminar. Mantenha o registro do cliente e do agente de teste se você continuar para a próxima tarefa. Quando você não precisar mais de uma concessão de teste, exclua-a DELETE https://graph.microsoft.com/v1.0/oauth2PermissionGrants/<grant-id> por meio do cliente de gerenciamento antes de excluir o registro do aplicativo cliente. Não exclua clientes compartilhados ou concessões usadas por outros usuários.

Próxima etapa

Chame uma API personalizada como o usuário conectado. Para restringir quais usuários podem invocar o agente, consulte Controlar o acesso do usuário aos agentes.