Autenticar as identidades dos agentes com a Microsoft. Identity.Web

Não é .NET? Consulte o contentor sidecar do Entra SDK para obter a documentação do container do Entra SDK. O contenedor sidecar suporta identidades de agentes em qualquer idioma e plataforma.

Compreender as identidades dos agentes

O pacote NuGet Microsoft.Identity.Web.AgentIdentities fornece suporte para identidades de agentes no Microsoft Entra ID. Permite que as aplicações autentiquem e adquiram tokens de forma segura para aplicações de agentes, identidades de agentes e identidades de utilizadores de agentes, o que é útil para agentes autónomos, agentes interativos que atuam em nome do seu utilizador e agentes que têm a sua própria identidade de utilizador.

Este pacote faz parte do Microsoft. Identity.Web conjunto de bibliotecas e foi introduzido na versão 3.10.0.

Rever conceitos-chave

Os seguintes conceitos são essenciais para trabalhar com identidades de agentes.

Defina um esquema de identidade de agente

Um plano de identidade de agente tem um registo especial de aplicação no Microsoft Entra que tem permissões para agir em nome das identidades de agentes ou das identidades de utilizadores agentes. É representado pelo seu ID de aplicação (ID de Agente, blueprint, ID do Cliente). O plano de identidade do agente é configurado com credenciais (tipicamente FIC+MSI ou certificados de cliente) e permissões para adquirir tokens para si próprio e chamar o Grafo. Esta é a aplicação que desenvolves. É uma aplicação cliente confidencial, normalmente uma API web. As únicas permissões que pode ter são manter (criar/eliminar) Identidades de Agente (usando o Microsoft Graph)

Criar uma identidade de agente

A identidade de um agente é um princípio de serviço especial na Microsoft Entra. Representa uma identidade que o blueprint de identidade do agente criou e está autorizado a imitar. Não possui credenciais próprias. O plano de identidade do agente pode adquirir tokens em nome da identidade do agente, desde que o utilizador ou administrador do locatário tenha dado o seu consentimento para a identidade do agente nos respetivos âmbitos. Os agentes autónomos adquirem tokens de aplicação em nome da identidade do agente. Agentes interativos, ao serem chamados com um token de utilizador, obtêm tokens de utilizador em representação da identidade do agente.

Criar uma identidade de utilizador agente

Uma identidade de utilizador de agente é uma identidade de agente que também pode atuar como utilizador (pense numa identidade de agente que teria a sua própria caixa de correio, ou que lhe reportaria no diretório). Uma aplicação agente pode adquirir um token em nome de um utilizador agente.

Entender credenciais de identidade federada (FIC)

O FIC é um mecanismo de confiança no Microsoft Entra que permite que as aplicações confiem umas nas outras usando tokens OpenID Connect (OIDC). No contexto das identidades dos agentes, os FICs são usados para estabelecer confiança entre as aplicações dos agentes e as identidades de agentes, bem como entre as identidades dos agentes e as identidades dos utilizadores de agentes.

Encontrar mais informações

Para detalhes sobre Microsoft Entra identidades de agentes, consulte ID do Agente Microsoft Entra documentação.

Instale o pacote

Execute o seguinte comando para adicionar o pacote NuGet ao seu projeto:

dotnet add package Microsoft.Identity.Web.AgentIdentities

Implementar identidades de agentes

Siga estes passos para configurar e usar as identidades dos agentes na sua aplicação.

1. Configurar serviços

Primeiro, registe os serviços exigidos na sua aplicação.

// Add the core Identity Web services
services.AddTokenAcquisition();
services.AddInMemoryTokenCaches();
services.AddHttpClient();

// Add Microsoft Graph integration if needed.
// Requires the Microsoft.Identity.Web.GraphServiceClient package
services.AddMicrosoftGraph();

// Add Agent Identities support
services.AddAgentIdentities();

2. Configurar o modelo de identidade do agente

Configure a sua aplicação de blueprint de identidade de agente com as credenciais necessárias usando appsettings.json:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "agent-application-client-id",

    "ClientCredentials": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateStorePath": "LocalMachine/My",
        "CertificateDistinguishedName": "CN=YourCertificateName"
      }

      // Or for Federation Identity Credential with Managed Identity:
      // {
      //   "SourceType": "SignedAssertionFromManagedIdentity",
      //   "ManagedIdentityClientId": "managed-identity-client-id"  // Omit for system-assigned
      // }
    ]
  }
}

Ou, se preferires, configura programáticamente:

// Configure the information about the agent application
services.Configure<MicrosoftIdentityApplicationOptions>(
    options =>
    {
        options.Instance = "https://login.microsoftonline.com/";
        options.TenantId = "your-tenant-id";
        options.ClientId = "agent-application-client-id";
        options.ClientCredentials = [
            CertificateDescription.FromStoreWithDistinguishedName(
                "CN=YourCertificateName", StoreLocation.LocalMachine, StoreName.My)
        ];
    });

Veja https://aka.ms/ms-id-web/credential-description para todas as formas de expressar credenciais.

No ASP.NET Core, use a sobreposição de serviços. Configure um esquema de autenticação. Também pode usar a Microsoft. Identity.Web.Owin se tiveres uma aplicação ASP.NET Core em OWIN (não recomendado para aplicações novas), ou até criar uma aplicação daemon.

3. Utilizar identidades de agentes

Escolha o padrão de aquisição de tokens adequado com base no seu cenário de agente.

Adquirir tokens para a identidade de um agente

Utilize estes padrões para adquirir tokens para identidades de agentes em cenários autónomos ou interativos.

Adquirir tokens de aplicação para agentes autónomos

Para que a sua aplicação de agente autónomo adquira tokens só de aplicação para uma identidade de agente:

// Get the required services from the DI container
IAuthorizationHeaderProvider authorizationHeaderProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Configure options for the agent identity
string agentIdentity = "agent-identity-guid";
var options = new AuthorizationHeaderProviderOptions()
    .WithAgentIdentity(agentIdentity);

// Acquire an access token for the agent identity
string authHeader = await authorizationHeaderProvider
    .CreateAuthorizationHeaderForAppAsync("https://resource/.default", options);

// The authHeader contains "Bearer " + the access token (or another protocol
// depending on the options)
Adquirir tokens de utilizador para agentes interativos

Para que a sua aplicação de agente interativo adquira tokens de utilizador para uma identidade de agente em nome do utilizador que invoca a API web:

// Get the required services from the DI container
IAuthorizationHeaderProvider authorizationHeaderProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Configure options for the agent identity
string agentIdentity = "agent-identity-guid";
var options = new AuthorizationHeaderProviderOptions()
    .WithAgentIdentity(agentIdentity);

// Acquire an access token for the agent identity
string authHeader = await authorizationHeaderProvider
    .CreateAuthorizationHeaderForAppAsync(["https://resource/.default"], options);

// The authHeader contains "Bearer " + the access token (or another protocol
// depending on the options)

Adquirir tokens para a identidade de um utilizador agente

Para que a sua aplicação agente adquira tokens em nome da identidade do utilizador agente, pode usar o UPN (Nome Principal do Utilizador) ou o OID (ID do Objeto).

Autenticar com UPN (Nome Principal do Utilizador)

O exemplo seguinte adquire um token de utilizador especificando o UPN do utilizador:

// Get the required services
IAuthorizationHeaderProvider authorizationHeaderProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Configure options for the agent user identity using UPN
string agentIdentity = "agent-identity-client-id";
string userUpn = "user@contoso.com";
var options = new AuthorizationHeaderProviderOptions()
    .WithAgentUserIdentity(agentIdentity, userUpn);

// Create a ClaimsPrincipal to enable token caching
ClaimsPrincipal user = new ClaimsPrincipal();

// Acquire a user token
string authHeader = await authorizationHeaderProvider
    .CreateAuthorizationHeaderForUserAsync(
        scopes: ["https://graph.microsoft.com/.default"],
        options: options,
        user: user);

// The user object now has claims including uid and utid. If you use it
// in another call it will use the cached token.
Autenticar com OID (ID de Objeto)

O exemplo seguinte adquire um token de utilizador especificando o OID do utilizador:

// Get the required services
IAuthorizationHeaderProvider authorizationHeaderProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Configure options for the agent user identity using OID
string agentIdentity = "agent-identity-client-id";
Guid userOid = Guid.Parse("e1f76997-1b35-4aa8-8a58-a5d8f1ac4636");
var options = new AuthorizationHeaderProviderOptions()
    .WithAgentUserIdentity(agentIdentity, userOid);

// Create a ClaimsPrincipal to enable token caching
ClaimsPrincipal user = new ClaimsPrincipal();

// Acquire a user token
string authHeader = await authorizationHeaderProvider
    .CreateAuthorizationHeaderForUserAsync(
        scopes: ["https://graph.microsoft.com/.default"],
        options: options,
        user: user);

// The user object now has claims including uid and utid. If you use it
// in another call it will use the cached token.

4. Integrar com o Microsoft Graph

Instale o pacote Microsoft.Identity.Web.AgentIdentities, que adiciona suporte para identidades de agente.

dotnet add package Microsoft.Identity.Web.AgentIdentities

Adicione suporte para Microsoft Graph na sua coleção de serviços:

services.AddMicrosoftGraph();

Agora pode obter um GraphServiceClient do fornecedor de serviços.

Chamar Microsoft Graph com identidade de agente

O exemplo seguinte chama APIs Microsoft Graph usando uma identidade de agente:

// Get the GraphServiceClient
GraphServiceClient graphServiceClient = serviceProvider.GetRequiredService<GraphServiceClient>();

// Call Microsoft Graph APIs with the agent identity
var applications = await graphServiceClient.Applications
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
    {
        options.WithAgentIdentity(agentIdentity);
        options.RequestAppToken = true;
    }));

Chame Microsoft Graph com identidade de utilizador agente

Pode usar UPN ou OID com Microsoft Graph:

// Get the GraphServiceClient
GraphServiceClient graphServiceClient = serviceProvider.GetRequiredService<GraphServiceClient>();

// Call Microsoft Graph APIs with the agent user identity using UPN
var me = await graphServiceClient.Me
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
        options.WithAgentUserIdentity(agentIdentity, userUpn)));

// Or using OID
var me = await graphServiceClient.Me
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
        options.WithAgentUserIdentity(agentIdentity, userOid)));

5. Integrar com APIs a jusante

Para chamar outras APIs usando a IDownstreamApi abstração:

  1. Instale o pacote Microsoft.Identity.Web.DownstreamApi, que fornece a abstração IDownstreamApi
dotnet add package Microsoft.Identity.Web.DownstreamApi
  1. Adicione uma DownstreamApis secção na sua configuração, especificando os parâmetros para a sua API a jusante:
"AzureAd":{
    // usual config
},
"DownstreamApis":{
   "MyApi":
   {
    "BaseUrl": "https://myapi.domain.com",
    "Scopes": [ "https://myapi.domain.com/read", "https://myapi.domain.com/write" ]
   }
}
  1. Adicione suporte para APIs downstream na sua coleção de serviços:
services.AddDownstreamApis(Configuration.GetSection("DownstreamApis"));

Agora pode aceder a um IDownstreamApi serviço do fornecedor de serviços e chamar a API "MyApi" usando qualquer verbo HTTP. O exemplo seguinte demonstra a chamada de APIs com identidade de agente e identidade de utilizador de agente:

// Get the IDownstreamApi service
IDownstreamApi downstreamApi = serviceProvider.GetRequiredService<IDownstreamApi>();

// Call API with agent identity
var response = await downstreamApi.GetForAppAsync<string>(
    "MyApi",
    options => options.WithAgentIdentity(agentIdentity));

// Call API with agent user identity using UPN
var userResponse = await downstreamApi.GetForUserAsync<string>(
    "MyApi",
    options => options.WithAgentUserIdentity(agentIdentity, userUpn));

// Or using OID
var userResponseByOid = await downstreamApi.GetForUserAsync<string>(
    "MyApi",
    options => options.WithAgentUserIdentity(agentIdentity, userOid));

6. Integrar com SDKs do Azure

Para utilizar os SDKs do Azure, use a classe MicrosoftIdentityAzureCredential do pacote NuGet Microsoft.Identity.Web.Azure.

Instalar o pacote Microsoft.Identity.Web.Azure:

dotnet add package Microsoft.Identity.Web.Azure

Adicione suporte para credencial de token Azure na sua coleção de serviços:

services.AddMicrosoftIdentityAzureTokenCredential();

Agora pode obter um MicrosoftIdentityTokenCredential do fornecedor de serviços. Esta classe tem um membro chamado Options ao qual pode aplicar os métodos .WithAgentIdentity() ou .WithAgentUserIdentity().

Consulte SDKs do Azure integração para mais detalhes.

7. Configurar o HttpClient com o MicrosoftIdentityMessageHandler

Para usar o HttpClient diretamente com opções de autenticação flexíveis, utilize o MicrosoftIdentityMessageHandler do pacote Microsoft.Identity.Web.TokenAcquisition.

Nota: O pacote Microsoft.Identity.Web.TokenAcquisition já é referenciado por Microsoft.Identity.Web.AgentIdentities.

Autenticar a identidade do agente com MicrosoftIdentityMessageHandler

O exemplo seguinte configura um HttpClient com autenticação de identidade de agente:

// Configure HttpClient with MicrosoftIdentityMessageHandler in DI
services.AddHttpClient("MyApiClient", client =>
{
    client.BaseAddress = new Uri("https://myapi.domain.com");
})
.AddMicrosoftIdentityMessageHandler(options =>
{
    options.Scopes= { "https://myapi.domain.com/.default" }
});

// Usage in your service or controller
public class MyService
{
    private readonly HttpClient _httpClient;

    public MyService(IHttpClientFactory httpClientFactory)
    {
        _httpClient = httpClientFactory.CreateClient("MyApiClient");
    }

    public async Task<string> CallApiWithAgentIdentity(string agentIdentity)
    {
        // Create request with agent identity authentication
        var request = new HttpRequestMessage(HttpMethod.Get, "/api/data")
            .WithAuthenticationOptions(options =>
            {
                options.WithAgentIdentity(agentIdentity);
                options.RequestAppToken = true;
            });

        var response = await _httpClient.SendAsync(request);
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadAsStringAsync();
    }
}

Autenticar a identidade do utilizador agente com MicrosoftIdentityMessageHandler

O exemplo seguinte envia um pedido autenticado com a identidade de um utilizador agente:

public async Task<string> CallApiWithAgentUserIdentity(string agentIdentity, string userUpn)
{
    // Create request with agent user identity authentication
    var request = new HttpRequestMessage(HttpMethod.Get, "/api/userdata")
        .WithAuthenticationOptions(options =>
        {
            options.WithAgentUserIdentity(agentIdentity, userUpn);
            options.Scopes.Add("https://myapi.domain.com/user.read");
        });

    var response = await _httpClient.SendAsync(request);
    response.EnsureSuccessStatusCode();
    return await response.Content.ReadAsStringAsync();
}

Configurar o HttpClient manualmente

Também pode configurar o handler manualmente para mais controlo:

// Get the authorization header provider
IAuthorizationHeaderProvider headerProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Create the handler with default options
var handler = new MicrosoftIdentityMessageHandler(
    headerProvider,
    new MicrosoftIdentityMessageHandlerOptions
    {
        Scopes = { "https://graph.microsoft.com/.default" }
    });

// Create HttpClient with the handler
using var httpClient = new HttpClient(handler);

// Make requests with per-request authentication options
var request = new HttpRequestMessage(HttpMethod.Get, "https://graph.microsoft.com/v1.0/applications")
    .WithAuthenticationOptions(options =>
    {
        options.WithAgentIdentity(agentIdentity);
        options.RequestAppToken = true;
    });

var response = await httpClient.SendAsync(request);

O MicrosoftIdentityMessageHandler oferece uma forma flexível e componível de adicionar autenticação ao seu código baseado em HttpClient, mantendo total compatibilidade com os métodos existentes de extensão Microsoft Identity Web para identidades de agentes.

Validar tokens a partir das identidades dos agentes

Validar tokens obtidos para identidades de agentes ou identidades de utilizadores de agentes da mesma forma que para qualquer API da web. No entanto, também pode:

  • Verifique se foi emitido um token para a identidade de um agente e para qual plano de agente.

    HttpContext.User.GetParentAgentBlueprint()

    retorna o ClientId do blueprint do agente pai se o token for emitido para uma identidade de agente (ou identidade de utilizador do agente)\

  • Verifique se foi emitido um token para a identidade de um utilizador agente.

    HttpContext.User.IsAgentUserIdentity()

Estes dois métodos de extensão aplicam-se tanto ao ClaimsIdentity como ao ClaimsPrincipal.

Rever pré-requisitos

Certifique-se de que completa estes passos de configuração antes de implementar as identidades dos agentes.

Configurar o registo do Microsoft Entra

  1. Configuração da Aplicação do Agente:

    • Registar uma aplicação de agente com o SDK de gráficos
    • Adicionar credenciais de cliente para a aplicação de agente
    • Conceda permissões de API apropriadas, como Application.ReadWrite.All, para criar identidades de agentes
    • Exemplo de configuração em JSON: 
      {
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "agent-application-id",
    "ClientCredentials": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateStorePath": "LocalMachine/My",
        "CertificateDistinguishedName": "CN=YourCertName"
      }
    ]
  }
}

  2. Configuração de identidade do agente:

    • Peça ao agente para criar uma identidade de agente
    • Conceda permissões de API apropriadas com base no que a identidade do seu agente precisa de fazer

  3. Permissão do Utilizador:

    • Para cenários de identidade de utilizador agente, certifique-se de que as permissões de utilizador apropriadas estão configuradas.

Compreender o fluxo de autenticação

Sob o capô, o pacote Microsoft.Identity.Web.AgentIdentities:

  1. Estabelece confiança entre a aplicação do agente e a identidade do agente, e entre a identidade do agente e a identidade do utilizador do agente, utilizando Credenciais de Identidade Federada (FIC).
  2. Adquirir os tokens FIC usando o GetFicTokenAsync método
  3. Usa os tokens FIC para autenticar como a identidade do agente
  4. Para as identidades de utilizadores agentes, recorre a extensões MSAL para a aquisição de tokens de utilizador.

Resolver problemas comuns

Reveja estas questões e resoluções comuns ao trabalhar com identidades de agentes.

Resolver problemas conhecidos

  1. Missing FIC Configuration: Garanta que as Credenciais de Identidade Federada estão devidamente configuradas no Microsoft Entra entre a aplicação do agente e a identidade do agente.

  2. Questões de Permissões: Verifique se a aplicação do agente tem permissões suficientes para gerir as identidades dos agentes e se as identidades dos agentes têm permissões suficientes para chamar as APIs a jusante.

  3. Problemas com o Certificado: Se usar um certificado de cliente, verifique se este está registado no registo da aplicação, está devidamente instalado e acessível pelo código da aplicação do agente.

  4. Falhas na Aquisição de Tokens: Ative o registo para diagnosticar falhas na aquisição de tokens. O seguinte código configura o registo no console ao nível de debug:

    services.AddLogging(builder => {
    builder.AddConsole();
    builder.SetMinimumLevel(LogLevel.Debug);
});

Explore recursos adicionais

  • Last updated on