Autenticar identidades de agente con Microsoft. Identity.Web

¿No .NET? Consulte el sidecar del contenedor del SDK de Entra para obtener la documentación del contenedor del SDK de Entra. El sidecar de contenedores admite identidades de agente en cualquier lenguaje y plataforma.

Descripción de las identidades del agente

El paquete NuGet Microsoft.Identity.Web.AgentIdentities proporciona compatibilidad con identidades de agente en Microsoft Entra ID. Permite a las aplicaciones autenticar y adquirir tokens de forma segura para aplicaciones de agente, identidades de agente e identidades de usuario de agente, que resulta útil para agentes autónomos, agentes interactivos que actúan en nombre de su usuario y agentes que tienen su propia identidad de usuario.

Este paquete forma parte del Microsoft. Identity.Web conjunto de bibliotecas y se introdujo en la versión 3.10.0.

Revisión de los conceptos clave

Los conceptos siguientes son esenciales para trabajar con identidades de agente.

Definición de un plano técnico de identidad del agente

Un esquema de identidad del agente tiene un registro especial de aplicación en Microsoft Entra que cuenta con permisos para actuar en nombre de las identidades de agente o de las identidades de usuario del agente. Se representa mediante su identificador de aplicación (id. de cliente del plano técnico de identidad del agente). El modelo de identidad del agente se configura con credenciales (normalmente FIC+MSI o certificados de cliente) y permisos para adquirir tokens para llamar a Graph. Esta es la aplicación que desarrollas. Es una aplicación cliente confidencial, normalmente una API web. Los únicos permisos que puede tener son mantener (crear o eliminar) identidades del agente (mediante el Microsoft Graph)

Creación de una identidad de agente

Una identidad de agente es un principal de servicio especial en Microsoft Entra. Es una identidad que el esquema de identidad del agente creó y está autorizada para ser suplantada. No tiene credenciales propias. El esquema de identidad del agente puede adquirir tokens en nombre de la identidad del agente siempre que el usuario o el administrador del arrendatario otorguen su consentimiento para la identidad del agente en los ámbitos correspondientes. Los agentes autónomos adquieren tokens de aplicación en nombre de la identidad del agente. Los agentes interactivos llamados con un token de usuario adquieren tokens de usuario en representación de la identidad del agente.

Creación de una identidad de usuario del agente

Una identidad de usuario del agente es una identidad de agente que también puede actuar como usuario (piense en una identidad de agente que tendría su propio buzón o que le informaría en el directorio). Una aplicación de agente puede adquirir un token en representación de la identidad de un usuario agente.

Comprender las credenciales de identidad federada (FIC)

FIC es un mecanismo de confianza en Microsoft Entra que permite a las aplicaciones confiar entre sí mediante tokens de OpenID Connect (OIDC). En el contexto de las identidades de agente, los FIC se usan para establecer la confianza entre la aplicación del agente y las identidades de agente, así como las identidades de agente y las identidades de usuario del agente.

Busque más información.

Para obtener más información sobre las identidades del agente de Microsoft Entra, consulte Agente de Microsoft Entra ID documentación.

Instalar el paquete

Ejecute el siguiente comando para agregar el paquete NuGet al proyecto:

dotnet add package Microsoft.Identity.Web.AgentIdentities

Implementación de identidades de agente

Siga estos pasos para configurar y usar identidades de agente en la aplicación.

1. Configurar servicios

En primer lugar, registre los servicios necesarios en la aplicación:

// 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. Configuración del plano técnico de identidad del agente

Configure la aplicación de plano técnico de identidad del agente con las credenciales necesarias mediante 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
      // }
    ]
  }
}

O bien, si lo prefiere, configure mediante programación:

// 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)
        ];
    });

Consulte https://aka.ms/ms-id-web/credential-description para ver todas las formas de expresar las credenciales.

En ASP.NET Core, use la invalidación de los servicios. Configure la toma de un esquema de autenticación. También puede usar Microsoft.Identity.Web.Owin si tiene una aplicación de ASP.NET Core en OWIN (no se recomienda para nuevas aplicaciones) o incluso crear una aplicación de servicio.

3. Uso de identidades de agente

Elija el patrón de adquisición de tokens adecuado en función del escenario del agente.

Adquisición de tokens para una identidad de agente

Use estos patrones para adquirir tokens para identidades de agente en escenarios autónomos o interactivos.

Adquisición de tokens de aplicación para agentes autónomos

Para que tu aplicación de agente autónomo adquiera tokens de solo aplicación para una identidad 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)

Adquisición de tokens de usuario para agentes interactivos

Para que la aplicación del agente interactivo adquiera tokens de usuario para una identidad de agente en nombre del usuario que llama a la 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)

Adquisición de tokens para la identidad de usuario de un agente

Para que la aplicación del agente adquiera tokens en nombre de una identidad de usuario del agente, puede usar el UPN del usuario (nombre principal de usuario) o el OID (id. de objeto).

Autenticación con UPN (nombre principal de usuario)

En el ejemplo siguiente se adquiere un token de usuario especificando el UPN del usuario:

// 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.

Autenticación con OID (id. de objeto)

En el ejemplo siguiente se adquiere un token de usuario especificando el OID del usuario:

// 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. Integración con Microsoft Graph

Instale el paquete Microsoft.Identity.Web.AgentIdentities, que añade soporte para identidades de agentes.

dotnet add package Microsoft.Identity.Web.AgentIdentities

Agregue compatibilidad para Microsoft Graph en la colección de servicios:

services.AddMicrosoftGraph();

Ahora puede obtener un GraphServiceClient del proveedor de servicios.

Realizar una llamada a Microsoft Graph con la identidad del agente

En el ejemplo siguiente se llama a Microsoft Graph API mediante una identidad 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;
    }));

Realizar llamada a Microsoft Graph con identidad de usuario del agente

Puede usar UPN o OID con 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. Integración con las API de bajada

Para llamar a otras API mediante la IDownstreamApi abstracción:

Instale el paquete Microsoft.Identity.Web.DownstreamApi, que proporciona la abstracción IDownstreamApi

dotnet add package Microsoft.Identity.Web.DownstreamApi

Agregue una DownstreamApis sección en la configuración y especifique los parámetros de la API de bajada:

"AzureAd":{
    // usual config
},
"DownstreamApis":{
   "MyApi":
   {
    "BaseUrl": "https://myapi.domain.com",
    "Scopes": [ "https://myapi.domain.com/read", "https://myapi.domain.com/write" ]
   }
}

Agregue compatibilidad con las API de bajada en la colección de servicios:

services.AddDownstreamApis(Configuration.GetSection("DownstreamApis"));

Ahora puede acceder a un IDownstreamApi servicio desde el proveedor de servicios y llamar a la API "MyApi" mediante cualquier verbo HTTP. En el ejemplo siguiente se muestra cómo llamar a las API con la identidad del agente y la identidad de usuario del 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. Integración con SDK de Azure

Para llamar a los SDKs de Azure, use la clase MicrosoftIdentityAzureCredential desde el paquete NuGet Microsoft.Identity.Web.Azure.

Instale el Microsoft. Identity.Web. Azure paquete:

dotnet add package Microsoft.Identity.Web.Azure

Agregue soporte para credenciales de token de Azure en la colección de servicios:

services.AddMicrosoftIdentityAzureTokenCredential();

Ahora puede obtener un MicrosoftIdentityTokenCredential del proveedor de servicios. Esta clase tiene un miembro Options al que puede aplicar los .WithAgentIdentity() o .WithAgentUserIdentity() métodos.

Consulte SDK de Azure integration para obtener más información.

7. Configurar HttpClient con MicrosoftIdentityMessageHandler

Para usar HttpClient directamente con opciones de autenticación flexibles, use el MicrosoftIdentityMessageHandler del paquete Microsoft.Identity.Web.TokenAcquisition.

Nota: El paquete Microsoft.Identity.Web.TokenAcquisition ya está referenciado por Microsoft.Identity.Web.AgentIdentities.

Autenticación de la identidad del agente con MicrosoftIdentityMessageHandler

En el ejemplo siguiente se configura un HttpClient con la autenticación de identidad del 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();
    }
}

Autenticación de la identidad de usuario del agente con MicrosoftIdentityMessageHandler

En el ejemplo siguiente se envía una solicitud autenticada con una identidad de usuario del 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();
}

Configuración manual de HttpClient

También puede configurar el controlador manualmente para obtener más control:

// 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);

El MicrosoftIdentityMessageHandler proporciona una manera flexible y redactable de agregar autenticación al código basado en HttpClient, a la vez que mantiene la compatibilidad completa con los métodos de extensión web de identidad de Microsoft existentes para las identidades del agente.

Validación de tokens de identidades de agente

Valide los tokens adquiridos para identidades de agente o identidades de usuario del agente de la misma manera que para cualquier API web. Sin embargo, también puede:

Compruebe si se emitió un token para la identidad de un agente y para cuál plano del agente.
```
HttpContext.User.GetParentAgentBlueprint()
```
devuelve el ClientId del modelo de agente principal si el token se emite para una identidad del agente (o identidad de usuario del agente)
compruebe si se emitió un token para una identidad de usuario del agente.
```
HttpContext.User.IsAgentUserIdentity()
```

Estos 2 métodos de extensiones se aplican tanto a ClaimsIdentity como a ClaimsPrincipal.

Revisión de los requisitos previos

Asegúrese de completar estos pasos de configuración antes de implementar identidades de agente.

Configuración del registro de Microsoft Entra

Configuración de la aplicación del agente:

Registro de una aplicación de agente con el SDK de Graph
Adición de credenciales de cliente para la aplicación del agente
Conceda permisos de API adecuados, como Application.ReadWrite.All para crear identidades de agente.

Configuración de ejemplo en JSON:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "agent-application-id",
    "ClientCredentials": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateStorePath": "LocalMachine/My",
        "CertificateDistinguishedName": "CN=YourCertName"
      }
    ]
  }
}

Configuración de identidad del agente:
- Hacer que el agente cree una identidad del agente
- Concesión de permisos de API adecuados en función de lo que la identidad del agente debe hacer
Permiso de usuario:
- Para escenarios de identidad de usuario del agente, asegúrese de que se configuran los permisos de usuario adecuados.

Descripción del flujo de autenticación

Bajo el capó, el paquete Microsoft.Identity.Web.AgentIdentities:

Establece la confianza entre la aplicación del agente y la identidad del agente, y entre la identidad del agente y la identidad de usuario del agente, mediante credenciales de identidad federada (FIC).
Adquiere tokens FIC mediante el GetFicTokenAsync método
Usa los tokens FIC para autenticarse como identidad del agente
En el caso de las identidades de usuario del agente, aprovecha las extensiones de MSAL para realizar la adquisición de tokens de usuario.

Solucionar problemas comunes

Revise estos problemas comunes y soluciones al trabajar con identidades de agente.

Resolución de problemas conocidos

Falta de Configuración FIC: Asegúrese de que las Credenciales de Identidad Federada estén configuradas correctamente en Microsoft Entra entre la aplicación del agente y la identidad del agente.
Problemas de permisos: compruebe que la aplicación del agente tiene permisos suficientes para administrar las identidades del agente y que las identidades del agente tienen permisos suficientes para llamar a las API de bajada.
Problemas de certificado: si usa un certificado de cliente, compruebe que el certificado está registrado en el registro de la aplicación, instalado correctamente y accesible por el código de la aplicación del agente.
Errores de adquisición de tokens: habilite el registro para diagnosticar errores de adquisición de tokens. El siguiente código configura el registro de consola a nivel de depuración
```
services.AddLogging(builder => {
    builder.AddConsole();
    builder.SetMinimumLevel(LogLevel.Debug);
});
```

Exploración de recursos adicionales

Documentación de Microsoft Entra
documentación de Microsoft Identity Web
Federación de identidades de carga de trabajo
documentación del SDK de Microsoft Graph

Comentarios

¿Le resultó útil esta página?

Last updated on 2026-04-29