Llamar a una API de Microsoft Graph desde un agente usando .NET

En este artículo se explica cómo llamar a un Graph API de Microsoft desde un agente mediante identidades de agente o la cuenta de usuario de un agente.

Para llamar a una API desde un agente, debe obtener un token de acceso que el agente puede usar para autenticarse en la API. Se recomienda usar el Microsoft.Identity.Web SDK para llamar a sus API web en .NET. Este SDK simplifica el proceso de adquisición y validación de tokens. Para otros idiomas, use el SDK de Microsoft Entra para el ID del agente.

Prerrequisitos

  • Una identidad del agente con los permisos adecuados para llamar a la API de destino. Necesita un usuario para el flujo de representación.
  • Una cuenta de usuario del agente con los permisos adecuados para llamar a la API de destino.

Llamada a un Graph API de Microsoft

  1. Instale el Microsoft. Identity.Web.GraphServiceClient que controla la autenticación del SDK de Graph y el Microsoft. Paquete Identity.Web.AgentIdentities para agregar compatibilidad con identidades de agente.

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

  2. Agregue la compatibilidad con Microsoft Graph e identidades de agente en la colección de servicios.

    using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add authentication (web app or web API)
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

// Add Microsoft Graph support
builder.Services.AddMicrosoftGraph();

// Add Agent Identities support
builder.Services.AddAgentIdentities();

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

  3. Configure las opciones de identidad de Graph y agente en appsettings.json.

    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-client-id>",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  },
  "DownstreamApis": {
    "MicrosoftGraph": {
      "BaseUrl": "https://graph.microsoft.com/v1.0",
      "Scopes": ["User.Read", "User.ReadBasic.All"]
    }
  }
}

  4. Ahora puede obtener el GraphServiceClient y insertarlo en su servicio o desde el proveedor de servicios y llamar a Microsoft Graph.

  • En el caso de las identidades de agente, puede adquirir un token únicamente de aplicación (agentes autónomos) o un token en nombre del usuario (agentes interactivos) usando el método WithAgentIdentity. En el caso de los tokens de solo aplicación, establezca la propiedad RequestAppToken en true. Para los tokens delegados en nombre de usuario, no establezca la propiedad RequestAppToken o establézcala explícitamente en false.

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

string agentIdentity = "agent-identity-guid";

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

// Call Microsoft Graph APIs with the agent identity for on-behalf of user scenario
var applications = await graphServiceClient.Applications
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
    {
        options.WithAgentIdentity(agentIdentity);
        options.RequestAppToken = false; // False to show it's on-behalf of user
    }));

    • En el caso de las identidades de cuenta de usuario del agente, puede especificar el nombre principal de usuario (UPN) o la identidad de objeto (OID) para identificar la cuenta de usuario del agente mediante el WithAgentUserIdentity método .

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

string agentIdentity = "agent-identity-guid";

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

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

Contenido relacionado

  • Last updated on