Autenticación y adquisición de tokens para agentes autónomos

Los agentes autónomos realizan operaciones con su propia identidad en lugar de actuar como delegado de un usuario. Para operar de forma segura, un agente autónomo debe autenticarse con Microsoft Entra ID, obtener tokens de acceso y conceder los permisos adecuados. En este artículo se explica el flujo de un extremo a otro:

Configure las credenciales de cliente.
Solicite un token para el esquema de identidad del agente.
Solicite un token de identidad del agente.
Conceda permisos de aplicación (consentimiento del administrador).
(Opcional) Cree y autentíquese como cuenta de usuario de un agente para los recursos que requieren una identidad de usuario.

Nota:

En este artículo se tratan los agentes autónomos que operan con su propia identidad. Si el agente necesita actuar en nombre de un usuario que ha iniciado sesión, consulte Autenticación de usuarios y adquisición de tokens para agentes interactivos.

Prerrequisitos

Antes de implementar la autenticación de tokens del agente, asegúrese de que tiene:

Un plano técnico de identidad del agente.
Una identidad del agente. Necesita el identificador de cliente de identidad del agente.
Descripción de los protocolos OAuth en Agente de Microsoft Entra ID.

Para la autorización de administrador, también necesita lo siguiente:

Privilegios de administrador en el entorno de Microsoft Entra ID.
Descripción de los permisos específicos que requiere el agente.

Para la autenticación de la cuenta de usuario del agente, también necesita lo siguiente:

Descripción de las cuentas de usuario de agents en Agente de Microsoft Entra ID.

Configuración de las credenciales de cliente

Obtenga los detalles de las credenciales de cliente. Este podría ser el secreto de cliente, un certificado o una identidad administrada que usa como credencial de identidad federada.

Advertencia

Los secretos de cliente no se deben usar como credenciales de cliente en entornos de producción para planos técnicos de identidad del agente debido a riesgos de seguridad. En su lugar, use métodos de autenticación más seguros, como credenciales de identidad federada (FIC) con identidades administradas o certificados de cliente. Estos métodos proporcionan seguridad mejorada eliminando la necesidad de almacenar secretos confidenciales directamente dentro de la configuración de la aplicación.

API de Microsoft Graph
Microsoft. Identity.Web

Recopile las credenciales que configuró en el plano técnico de identidad del agente. Necesita una de las siguientes opciones:

Identidad administrada (recomendado): el identificador de cliente de identidad administrada y un token del servicio de metadatos de instancia (IMDS) de Azure.
Certificado: la huella digital del certificado o el archivo PFX.
Secreto de cliente (solo desarrollo): valor secreto.

Para producción, use una identidad administrada como credencial de identidad federada:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<your-tenant-id>",
    "ClientId": "<agent-blueprint-clientid>",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "<managed-identity-client-id>"
      }
    ]
  }
}

Solo para desarrollo y pruebas locales, puede usar un secreto de cliente en su lugar:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<your-tenant-id>",
    "ClientId": "<agent-blueprint-clientid>",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  }
}

Solicitud de un token para el plano técnico de identidad del agente

Al solicitar el token para el plano de identidad del agente, proporcione el ID de cliente de la identidad del agente en el parámetro fmi_path (ruta de acceso de identidad administrada federada). Este parámetro indica a Microsoft Entra ID qué identidad de agente representa el blueprint.

Cuando se usa un secreto de cliente durante el desarrollo local, proporcione el client_secret parámetro . En el caso de los certificados y las identidades administradas, use client_assertion y client_assertion_type en su lugar.

API de Microsoft Graph
Microsoft. Identity.Web

POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-blueprint-client-id>
&scope=api://AzureADTokenExchange/.default
&grant_type=client_credentials
&client_secret=<client-secret>
&fmi_path=<agent-identity-client-id>

Con Microsoft. Identity.Web, no es necesario solicitar explícitamente un token para el plano técnico de identidad del agente. Microsoft. Identity.Web lo hace por usted.

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

Solicitud de un token de identidad del agente

API de Microsoft Graph
Microsoft. Identity.Web

Una vez que tenga el token de plano técnico de identidad del agente (T1), úselo para solicitar el token de identidad del agente.

POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-identity-client-id>
&scope=https://graph.microsoft.com/.default
&grant_type=client_credentials
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<agent-blueprint-token-T1>

Microsoft.Identity.Web gestiona los detalles del protocolo de adquisición de tokens, siempre que utilice el nuevo services.AddAgentIdentities() en la colección de servicios al inicializar la aplicación.

Inicialice la aplicación:

// 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);
builder.Services.AddAgentIdentities();
builder.Services.AddInMemoryTokenCaches();

Use el .WithAgentIdentity() patrón para solicitar tokens de acceso:

// In an API endpoint or service method where HttpContext is available
app.MapGet("/call-api", async (HttpContext httpContext) =>
{
    IAuthorizationHeaderProvider authorizationHeaderProvider =
        httpContext.RequestServices.GetRequiredService<IAuthorizationHeaderProvider>();

    AuthorizationHeaderProviderOptions options =
        new AuthorizationHeaderProviderOptions().WithAgentIdentity("<agent-identity-client-id>");

    // Request agent identity tokens
    string authorizationHeader = await authorizationHeaderProvider
        .CreateAuthorizationHeaderForAppAsync("https://graph.microsoft.com/.default", options);

    // The authHeader contains "Bearer " + the access token
    return Results.Ok(authorizationHeader);
});

Conceder permisos de aplicación

A menudo, los agentes necesitan realizar acciones en Microsoft Graph y otros servicios web que requieren un permiso de aplicación de Microsoft Entra ID (representado como roles de aplicación). Los agentes autónomos deben solicitar estos permisos a un administrador de Microsoft Entra ID.

Hay dos maneras de conceder permisos de aplicación a un agente autónomo:

Un administrador puede crear una appRoleAssignment mediante Microsoft Graph API o PowerShell.
El agente puede dirigir al administrador a una página de consentimiento mediante una dirección URL de consentimiento del administrador.

Creación de una asignación de roles de aplicación mediante API

Siga estos pasos para obtener una asignación de roles de una aplicación.

Obtenga un token de acceso con los permisos Application.Read.All de aplicación y AppRoleAssignment.ReadWrite.All.
Obtenga el identificador de objeto de la entidad de servicio de recursos a la que intenta acceder. Por ejemplo, para buscar el identificador de objeto del principal de servicio de Microsoft Graph:
1. Vaya al Centro de administración Microsoft Entra.
2. Vaya a Entra ID --> Aplicaciones empresariales
3. Filtrar por tipo de aplicación == Microsoft Aplicaciones
4. Busque Microsoft Graph.
Obtenga el identificador único del rol de aplicación que desea asignar.

Cree la asignación del rol de la aplicación:

API de Microsoft Graph
Microsoft Graph PowerShell

POST https://graph.microsoft.com/v1.0/servicePrincipals/<agent-identity-id>/appRoleAssignments
Authorization: Bearer <token>
Content-Type: application/json

{
  "principalId": "<agent-identity-id>",
  "resourceId": "<microsoft-graph-sp-object-id>",
  "appRoleId": "<app-role-id>"
}

Connect-MgGraph -Scopes "Application.Read.All AppRoleAssignment.ReadWrite.All" -TenantId <your-test-tenant>

# Get the service principal for Microsoft Graph (well-known app ID)
$graphSp = Get-MgServicePrincipal -Filter "appId eq '00000003-0000-0000-c000-000000000000'"

# Get your application's service principal (replace with your app's client ID)
$agentId = "<agent-identity-id>"

# Find the App Role ID for "User.ReadBasic.All"
$userReadBasicRole = $graphSp.AppRoles | Where-Object {
    $_.Value -eq "User.ReadBasic.All" -and $_.AllowedMemberTypes -contains "Application"
}

# Assign the app role
New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $agentId `
    -PrincipalId $agentId `
    -ResourceId $graphSp.Id `
    -AppRoleId $userReadBasicRole.Id

Solicitud de autorización de un administrador de inquilinos

Para conceder permisos delegados, construya la dirección URL de autorización que se usa para solicitar al administrador. El parámetro role se usa para especificar los permisos de aplicación solicitados.

Asegúrese de usar el identificador de cliente de identidad del agente en la solicitud siguiente.

https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/adminconsent
?client_id=<agent-identity-client-id>
&role=User.Read.All
&redirect_uri=https://entra.microsoft.com/TokenAuthorize
&state=xyz123

Las implementaciones del agente pueden redirigir al administrador a esta dirección URL de varias maneras, como incluirla en un mensaje enviado al administrador en una ventana de chat. Cuando el administrador se redirige a esta dirección URL, se le pide que inicie sesión y conceda consentimiento a los permisos especificados en el parámetro de ámbito. En este momento debe usar el URI de redirección que aparece, que dirige al administrador a una página en blanco después de conceder el consentimiento.

Después de conceder a la aplicación los permisos necesarios, solicite un nuevo token de acceso de agente para que los permisos surtan efecto.

Autenticación como cuenta de usuario de un agente

Además de funcionar con tokens de solo aplicación, los agentes autónomos se pueden autenticar como cuenta de usuario de un agente. Las cuentas de usuario de los agentes son un tipo especial de cuenta de usuario en Microsoft Entra diseñada para su uso por agentes. Normalmente se usan cuando un agente necesita conectarse a sistemas que requieren la existencia de una cuenta de usuario, por ejemplo, un buzón, un canal de Teams u otros recursos específicos del usuario.

Cada identidad del agente solo puede tener una sola cuenta de usuario del agente asociada y la cuenta de usuario de cada agente solo se puede asociar a una identidad de agente única.

Obtención de autorización para crear cuentas de usuario de agentes

Para crear cuentas de usuario de agentes, el esquema de identidad del agente debe concederse el permiso AgentIdUser.ReadWrite.IdentityParentedBy de aplicación en la entidad. Puede obtener la autorización de una de estas dos maneras:

Solicitar autorización del agente. Asegúrese de usar el plano de identidad del agente como client_id, no como la identidad del agente.
Crear manualmente un appRoleAssignment en el entorno de cliente. Utilice el ID del objeto principal de servicio del plan de identidad del agente como valor de principalId, no como su ID de aplicación (cliente).

Si desea usar un cliente diferente, no la plantilla de identidad del agente, para crear cuentas de usuario de los agentes, ese cliente debe obtener el permiso delegado o de aplicación en su lugar.

Creación de la cuenta de usuario de un agente

Cree la cuenta de usuario de un agente mediante el plano técnico de identidad del agente u otro cliente aprobado. La manera recomendada de crear la cuenta de usuario del agente es usar su plan de identidad del agente. Necesita un token de acceso para crear la cuenta de usuario de un agente.

REST
Microsoft. Identity.Web

Una vez que tenga un token de acceso con el permiso necesario, realice la siguiente solicitud:

POST https://graph.microsoft.com/beta/users
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "@odata.type": "microsoft.graph.agentUser",
  "displayName": "New Agent User",
  "userPrincipalName": "agentuserupn@tenant.onmicrosoft.com",
  "identityParentId": "{agent-identity-id}",
  "mailNickname": "agentuserupn",
  "accountEnabled": true
}

Para usar Microsoft.Identity.Web para crear la cuenta de usuario de un agente, siga estos pasos:

Agregue lo siguiente al archivo de configuración:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<my-test-tenant>",
    "ClientId": "<my-agent-blueprint-id>",
    "Scopes": "access_agent",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "managed-identity-client-id"  // Omit for system-assigned
      }
    ]
  },

  "DownstreamApis": {
    "agent-identity": {
      "BaseUrl": "https://graph.microsoft.com",
      "RelativePath": "/v1.0/users",
      "Scopes": ["00000003-0000-0000-c000-000000000000/.default"],
      "RequestAppToken": true
    }
  }
}

Adición de paquetes necesarios

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

Configurar servicios.

using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web.Resource;
using Microsoft.IdentityModel.S2S.Extensions.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi();
builder.Services.AddAgentIdentities();
builder.Services.AddInMemoryTokenCaches();

var app = builder.Build();
app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();
app.Run();

Cree el punto de conexión para crear la cuenta de usuario del agente.

app.MapPost("/create-agent-id-user", async (HttpContext httpContext) =>
{
    try
    {
        // Get the service to call the downstream API (preconfigured in the appsettings.json file)
        IDownstreamApi downstreamApi = httpContext.RequestServices.GetRequiredService<IDownstreamApi>();

        var requestBody = new AgentIdUser
        {
            displayName = "my-agent-name",
            mailNickname = "my-agent-alias",
            userPrincipalName = "my-agent-email-address",
            accountEnabled = true,
            identityParentId = "<associated-agent-identity-id>"
        };

        // Call the downstream API (Graph) with a POST request to create an agent's user account
        var jsonResult = await downstreamApi.PostForAppAsync<AgentIdUser, AgentIdUser>(
            "agent-identity",
            requestBody
        );

        return Results.Json(jsonResult);
    }
    catch (Exception ex)
    {
        return ex.Message;
    }
})

Una vez creada la cuenta de usuario del agente, no es necesario configurar nada más. Estas cuentas no tienen credenciales y solo se pueden autenticar mediante el protocolo descrito en las secciones siguientes.

Las cuentas de usuario de los agentes se comportan como cualquier otra cuenta de usuario. Para poder solicitar tokens mediante la cuenta de usuario del agente, debe autorizar a la identidad del agente para que actúe en su nombre. Puede autorizar la identidad del agente mediante la autorización admin o crear manualmente una oAuth2PermissionGrant mediante Microsoft Graph o Microsoft Graph PowerShell.

Para Microsoft Graph, la solicitud se muestra en el siguiente fragmento de código:

POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
Authorization: Bearer {token}
Content-Type: application/json

{
  "clientId": "{agent-identity-id}",
  "consentType": "Principal",
  "principalId": "{agent-id-user-object-id}",
  "resourceId": "{ms-graph-service-principal-object-id}",
  "scope": "Mail.Read"
}

Para Microsoft Graph PowerShell, use el siguiente script:

Connect-MgGraph -Scopes "DelegatedPermissionGrant.ReadWrite.All" -TenantId <your-test-tenant>

# Get the service principal for Microsoft Graph
$graphSp = Get-MgServicePrincipal -Filter "appId eq '00000003-0000-0000-c000-000000000000'"

# Get the service principal for your client app
$clientSp = Get-MgServicePrincipal -Filter "appId eq '{agent-identity-id}'"

# Create the delegated permission grant
New-MgOauth2PermissionGrant -BodyParameter @{
    clientId    = $clientSp.Id
    consentType = "Principal"
    principalId = "{agent-id-user-object-id}"
    resourceId  = $graphSp.Id
    scope       = "Mail.Read"
}

Solicitud del token de cuenta de usuario de un agente

Para autenticar la cuenta de usuario de un agente, debe seguir un proceso de tres pasos:

Obtenga un token como plano técnico de identidad del agente.
Use ese token para obtener otro token como identidad del agente.
Utiliza los dos tokens anteriores para obtener otro token como la cuenta de usuario del agente.

REST
Microsoft. Identity.Web

En primer lugar, solicite un token como plano técnico de identidad del agente, como se describe en Solicitud de un token para el plano técnico de identidad del agente. Una vez que tenga el token de aplicación del agente, úselo para solicitar una credencial de identidad federada (FIC) para la identidad del agente:

POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-identity-id>
&scope=api://AzureADTokenExchange/.default
&grant_type=client_credentials
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<agent-blueprint-token>

Esto devuelve un token de intercambio (T2) para la identidad del agente. Úselo en la siguiente solicitud para obtener un token delegado para la cuenta de usuario del agente:

POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-identity-id>
&scope=https://graph.microsoft.com/.default
&grant_type=user_fic
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<agent-blueprint-token>
&user_id=<agent-user-object-id>
&user_federated_identity_credential=<agent-identity-token>

Esto le proporciona un token de acceso delegado que puede usar para llamar a Microsoft Graph como cuenta de usuario del agente. Puede usar user_id=<user-object-id> en lugar de username=<UPN> para el identificador de usuario.

Microsoft. Identity.Web controla la adquisición de tokens por usted. Use el .WithAgentUserIdentity() patrón para solicitar tokens de acceso.

// In an API endpoint or service method where HttpContext is available
app.MapGet("/agent-user-token", async (HttpContext httpContext) =>
{
    IAuthorizationHeaderProvider authorizationHeaderProvider =
        httpContext.RequestServices.GetRequiredService<IAuthorizationHeaderProvider>();

    // Configure options for the agent's user account identity
    string agentIdentity = "agent-identity-id";
    string userId = "<user-object-id>";
    var options = new AuthorizationHeaderProviderOptions()
        .WithAgentUserIdentity(agentIdentity, userId);

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

    return Results.Ok(authHeader);
});

También puede usar el nombre principal de la cuenta de usuario del agente en lugar del identificador de objeto.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-04-09