Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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 --truste 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.
- Registre um aplicativo single-tenant chamado cliente de teste da API do Agente no locatário do agente.
- 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. - 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.
- No plano, exponha um URI do identificador e o escopo delegado. Use
access_agentcomo o valor de escopo para este passo a passo. Preservar scopes existentes e definirapi.requestedAccessTokenVersioncomo2. - Declare esse escopo no
requiredResourceAccessdo cliente upstream. Use o ID do cliente do agente compartilhado comoresourceAppIde o GUID do escopo exposto com"type": "Scope". - 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.
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.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" }clientIderesourceIdsã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.Registre o ID da concessão
idpara 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
- O cliente upstream autentica o usuário.
- O cliente obtém um token de acesso para
access_agent. - O cliente envia
Authorization: Bearer <token>para a API do agente. - O middleware de autenticação de ASP.NET Core valida o token.
- 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.