Вызов Microsoft API Graph из агента с .NET

В этой статье объясняется, как вызвать Microsoft API Graph от агента с помощью удостоверений агента или учетной записи пользователя агента.

Чтобы вызвать API из агента, необходимо получить маркер доступа, который агент может использовать для проверки подлинности в API. Мы рекомендуем использовать Microsoft.Identity.Web SDK для вызова ваших веб-API в .NET. Этот пакет SDK упрощает процесс получения и проверки маркеров. Для других языков используйте пакет SDK аутентификации Microsoft Entra ID (sidecar).

Необходимые условия

  • Удостоверение агента с соответствующими разрешениями для вызова целевого API. Вам нужен пользователь для потока от имени.
  • Учетная запись пользователя агента с соответствующими разрешениями для вызова целевого API.

Вызвать Microsoft API Graph

  1. Установите Microsoft.Identity.Web.GraphServiceClient, обрабатывающий проверку подлинности для SDK Graph, и Microsoft.Identity.Web.AgentIdentities, чтобы добавить поддержку удостоверений агента.

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

  2. Добавьте поддержку Microsoft Graph и идентификаторов агента в сборник служб.

    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. Настройте параметры идентификационных данных Graph и агента в appsettings.json.

    Предупреждение

    Секреты клиента не должны использоваться в качестве учетных данных клиента в рабочих средах для схем удостоверений агента из-за рисков безопасности. Вместо этого используйте более безопасные методы проверки подлинности, такие как учетные данные федеративной идентификации (FIC) с управляемыми идентификациями или клиентские сертификаты. Эти методы обеспечивают повышенную безопасность, устраняя необходимость хранения конфиденциальных секретов непосредственно в конфигурации приложения.

    {
  "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. Теперь вы можете получить GraphServiceClient, внедрив его в ваш сервис или получить от поставщика услуг, и вызвать Microsoft Graph.

  • Для удостоверений агентом можно получить либо токен только для приложения (автономные агенты), либо токен от имени пользователя (интерактивные агенты) с помощью метода WithAgentIdentity. Для токенов только приложения установите свойство RequestAppToken на значение true. Для делегированных токенов от имени пользователей не устанавливайте свойство или явно задайте для него значение RequestAppToken как 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
    }));

    • Для указания удостоверений учетной записи пользователя агента можно использовать либо основное имя пользователя (UPN), либо идентификатор объекта (OID), чтобы идентифицировать учетную запись пользователя агента с помощью метода WithAgentUserIdentity.

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

Связанный контент

  • Last updated on