Autenticación de usuarios y adquisición de tokens para agentes interactivos

Los agentes interactivos realizan acciones en nombre de los usuarios. Para actuar en nombre de los usuarios de forma segura, el agente autentica al usuario, obtiene el consentimiento de los permisos necesarios y adquiere tokens de acceso para las API de nivel inferior. En este artículo se explica el flujo de autenticación de un extremo a otro y la adquisición de tokens para el agente interactivo:

  1. Conceda permisos a través de permisos heredables o consentimiento.
  2. Autentique al usuario y obtenga un token de acceso.
  3. Valide el token y extraiga las declaraciones de usuario.
  4. Adquiera tokens para APIs descendentes mediante el flujo On-Behalf-Of (OBO).

Nota:

En este artículo se tratan los agentes interactivos que actúan en nombre de los usuarios que han iniciado sesión mediante el flujo de OBO. Si el agente necesita su propia identidad similar al usuario (un escenario de trabajo digital), consulte Cuentas de usuario del agente y flujo de OAuth de la cuenta de usuario del agente.

Prerrequisitos

Antes de comenzar, asegúrese de que tiene:

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

Para que el agente pueda actuar en nombre de un usuario, el usuario o un administrador deben dar su consentimiento a los permisos necesarios. Hay dos enfoques para conceder permisos:

  • Permisos heredables: autorice previamente los permisos en el plano técnico para que las identidades del agente las hereden automáticamente.
  • Solicitar consentimiento: registre un URI de redireccionamiento y pida a los usuarios o administradores que concedan consentimiento a través de una solicitud de OAuth o usen el punto de conexión de consentimiento del administrador.

Uso de permisos heredables

Configure permisos heredables en el plano técnico de identidad del agente para autenticar previamente un conjunto base de ámbitos delegados y roles de aplicación. Las identidades del agente creadas a partir del plano técnico heredan automáticamente esos permisos sin solicitudes de consentimiento interactivas. Para más información, consulte Configuración de permisos heredables para planos técnicos de identidad del agente.

Para solicitar consentimiento a través de un flujo de OAuth, el plano técnico de identidad del agente debe configurarse primero con un URI de redirección. En el caso de los planos técnicos, el URI de redirección debe ser un tipo de aplicación web . A diferencia de los URI de redirección en los registros de aplicaciones, no se puede usar un URI de redireccionamiento en un plano técnico para obtener tokens de permisos delegados. Solo se admite response_type=none en la solicitud de OAuth2, lo que significa que la solicitud solo registra el consentimiento y no se devuelve ningún token.

Registro de un URI de redirección

Para actualizar el URI de redirección en la plantilla de identidad del agente, primero debe obtener un token de acceso con el permiso delegado AgentIdentityBlueprint.ReadWrite.All. A continuación, envíe una solicitud PATCH al objeto de aplicación para la plantilla de identidad del agente:

PATCH https://graph.microsoft.com/beta/applications/<agent-blueprint-id>
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "web": {
    "redirectUris": [
      "https://myagentapp.com/authorize"
    ]
  }
}

Para que el agente pueda actuar en nombre de un usuario, el usuario debe dar su consentimiento a los permisos necesarios. La solicitud de consentimiento del usuario no devuelve un token. En su lugar, registra que el usuario concedió permiso al agente para actuar en su nombre. La adquisición de tokens se produce en Autenticar al usuario y solicitar un token.

Importante

Utilice el ID de cliente de la identidad del agente en el parámetro client_id, no el ID de la esquema de definición de identidad del agente.

Para pedir consentimiento a un usuario, construya una dirección URL de autorización y redirija al usuario. El agente puede presentar esta dirección URL de diferentes maneras, por ejemplo, como vínculo en un mensaje de chat.

https://login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/authorize?
  client_id=<agent-identity-id>
  &response_type=none
  &redirect_uri=https%3A%2F%2Fmyagentapp.com%2Fauthorize
  &response_mode=query
  &scope=User.Read
  &state=xyz123

Cuando el usuario abra esta dirección URL, Microsoft Entra ID le pedirá que inicie sesión y conceda consentimiento. Después del consentimiento, el usuario se devuelve al URI de redirección.

Los parámetros clave de la dirección URL de autorización de consentimiento del usuario son:

  • client_id: el ID de cliente de identidad del agente (no el ID de cliente del esquema de definición de identidad del agente).
  • response_type: se establece en none porque esta solicitud solo registra el consentimiento. La adquisición de tokens usa response_type=code en Autenticar al usuario y solicitar un token.
  • redirect_uri: debe coincidir exactamente con el URI de redireccionamiento configurado en el plano técnico de identidad del agente.
  • scope: especifique los permisos delegados que necesita (por ejemplo, User.Read).
  • state: parámetro opcional para mantener el estado entre la solicitud y la devolución de llamada.

Para obtener más información sobre los conceptos de autorización de OAuth, consulte Permisos y consentimiento en la plataforma de identidad de Microsoft.

Los agentes también pueden solicitar autorización de un administrador de Microsoft Entra ID, que puede conceder consentimiento al agente para todos los usuarios de su inquilino. El consentimiento del administrador puede ser necesario en función de la configuración de consentimiento configurada en el inquilino.

Para conceder el consentimiento del administrador para todo el inquilino, dirija a un administrador a la siguiente dirección URL. Use el identificador de identidad del agente en el client_id parámetro .

https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/adminconsent
?client_id=<agent-identity-id>
&scope=User.Read
&redirect_uri=<redirect-uri>
&state=xyz123

Una vez que el administrador concede consentimiento, los permisos se aplican a todo el inquilino. Los usuarios no necesitan volver a dar su consentimiento.

Nota:

Configure un URI de redirección en el plano técnico e incluya un state parámetro en la solicitud de consentimiento. Cuando se concede el consentimiento, el usuario se envía al URI de redirección, donde puede mostrar la confirmación. El punto de conexión puede usar el parámetro state para hacer un seguimiento de que se concedió el permiso. Para los agentes de inquilino único, como alternativa, puede reintentar las solicitudes de token hasta que se otorgue el consentimiento, ya que el identificador del inquilino ya se conoce.

Autenticación del usuario y solicitud de un token

Una vez concedido el consentimiento, la aplicación cliente (como un front-end o una aplicación móvil) inicia una solicitud de código de autorización de OAuth 2.0 para obtener un token en el que la audiencia es el plano técnico de identidad del agente. En este paso, client_id hace referencia al propio identificador de aplicación registrado de la aplicación cliente, no a la identidad del agente ni al plano técnico de identidad del agente.

Nota:

El redirect_uri de esta solicitud pertenece al registro de la aplicación cliente, no al URI de redireccionamiento de la plantilla configurado en el paso de consentimiento anterior.

  1. Redirija al usuario al punto de conexión de autorización de Microsoft Entra ID con los parámetros siguientes:

    GET https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/authorize?client_id=<client-app-id>
&response_type=code
&redirect_uri=<redirect_uri>
&response_mode=query
&scope=api://<agent-blueprint-id>/access_agent
&state=abc123

  2. Una vez que el usuario inicia sesión, la aplicación recibe un código de autorización en el URI de redirección. Intercambie el código de autorización por un token de acceso:

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

client_id=<client-app-id>
&grant_type=authorization_code
&code=<authorization_code>
&redirect_uri=<redirect_uri>
&scope=api://<agent-blueprint-id>/access_agent
&client_secret=<client-secret>

    Incluya el client_secret parámetro solo si usa un cliente confidencial.

    La respuesta JSON contiene un token de acceso que se puede usar para acceder a la API del agente.

Validar el token de acceso

La API web debe validar el token de acceso entrante antes de que el agente pueda actuar. Use siempre una biblioteca aprobada para validar tokens. No escriba su propio código de validación de tokens.

  1. Instale el paquete NuGet Microsoft.Identity.Web:

    dotnet add package Microsoft.Identity.Web

  2. En el proyecto de API web de ASP.NET Core, implemente la autenticación de Microsoft Entra ID.

    // Program.cs
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

var app = builder.Build();

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

  3. Configure las credenciales de autenticación en el appsettings.json archivo:

    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.

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

Para obtener más información sobre Microsoft. Identity.Web, consulte Microsoft. Documentación de Identity.Web.

Validar reclamaciones de usuario

Después de la validación del token de acceso, el agente puede identificar al usuario y realizar comprobaciones de autorización. El siguiente ejemplo de ruta de la API extrae las declaraciones del usuario del token de acceso y las devuelve en la respuesta de la API:

app.MapGet("/hello-agent", (HttpContext httpContext) =>
{   
    var claims = httpContext.User.Claims.Select(c => new
    {
        Type = c.Type,
        Value = c.Value
    });

    return Results.Ok(claims);
})
.RequireAuthorization();

Adquisición de tokens para las API de bajada

Una vez que un agente interactivo valida el token del usuario, puede solicitar tokens de acceso para llamar a las API de bajada en nombre del usuario. El flujo con derechos delegados (On-Behalf-Of, OBO) permite que el agente pueda hacer lo siguiente:

  • Recibir un token de acceso de un cliente.
  • Intercámbielo por un nuevo token de acceso para una API descendente, como Microsoft Graph.
  • Use ese nuevo token para acceder a los recursos protegidos en nombre del usuario original.

La biblioteca Microsoft.Identity.Web simplifica la implementación de OBO controlando el intercambio de tokens automáticamente, por lo que no es necesario implementar manualmente el flujo siguiendo el protocolo.

  1. Instale los paquetes NuGet necesarios:

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

  2. En el proyecto de API web de ASP.NET Core, actualice la implementación de autenticación de Microsoft Entra ID:

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

var app = builder.Build();

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

app.Run();

  3. En la API del agente, intercambie el token de acceso de usuario entrante para un nuevo token de acceso para la identidad del agente. Microsoft.Identity.Web valida el token de acceso entrante y controla el intercambio de tokens en nombre de:

    app.MapGet("/agent-obo-user", async (HttpContext httpContext) =>
{
    string agentIdentity = "<your-agent-identity>";
    IAuthorizationHeaderProvider authorizationHeaderProvider = httpContext.RequestServices.GetService<IAuthorizationHeaderProvider>()!;
    AuthorizationHeaderProviderOptions options = new AuthorizationHeaderProviderOptions().WithAgentIdentity(agentIdentity);

    string authorizationHeaderWithUserToken = await authorizationHeaderProvider.CreateAuthorizationHeaderForUserAsync(["https://graph.microsoft.com/.default"], options);

    var response = new { header = authorizationHeaderWithUserToken };
    return Results.Json(response);
})
.RequireAuthorization();

En segundo plano, el flujo de OBO realiza dos intercambios de tokens: en primer lugar, el esquema de definición de identidad del agente obtiene un token de intercambio mediante la credencial de cliente y luego el agente intercambia ese token junto con el token de acceso del usuario en un token de API de destino. Para ver el tutorial completo del protocolo, incluidos los formatos de solicitud HTTP y los detalles de validación de tokens, consulte Flujo con derechos delegados en agentes.

Contenido relacionado

Más información sobre los tokens de agente y las API relacionadas:

  • Last updated on