Volání Graph API Microsoftu z agenta pomocí .NET

Tento článek vysvětluje, jak volat Microsoft Graph API z agenta pomocí identit agentů nebo uživatelského účtu agenta.

Pokud chcete volat rozhraní API z agenta, musíte získat přístupový token, který může agent použít k ověření v rozhraní API. Doporučujeme použít Microsoft. Identity.Web SDK pro .NET pro volání webových rozhraní API Tato sada SDK zjednodušuje proces získávání a ověřování tokenů. Pro ostatní jazyky použijte Microsoft Entra ID Auth SDK (sidecar).

Předpoklady

  • Identita agenta s příslušnými oprávněními pro volání cílového rozhraní API. Pro tok v zastoupení potřebujete uživatele.
  • Uživatelský účet agenta s příslušnými oprávněními pro volání cílového rozhraní API.

Volání Microsoft Graph API

  1. Nainstalujte Microsoft. Identity.Web.GraphServiceClient, který zpracovává ověřování sady Graph SDK a Microsoft. Balíček Identity.Web.AgentIdentities pro přidání podpory identit agentů

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

  2. Přidejte podporu pro Microsoft Graph a identity agenta v kolekci služeb.

    using Microsoft.AspNetCore.Authentication.OpenIdConnect;
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. Konfigurace možností identity graphu a agenta v appsettings.json.

    Výstraha

    Tajné kódy klienta by se neměly používat jako přihlašovací údaje klienta v produkčních prostředích pro podrobné plány identit agentů kvůli rizikům zabezpečení. Místo toho používejte bezpečnější metody ověřování, jako jsou přihlašovací údaje federované identity (FIC) se spravovanými identitami nebo klientskými certifikáty . Tyto metody poskytují lepší zabezpečení tím, že eliminují potřebu ukládat citlivé tajné kódy přímo v konfiguraci vaší aplikace.

    {
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<your-tenant-id>",
    "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"]
    }
  }
}

    Note

    Nakonfigurujte pouze Microsoft Graph oprávnění, která váš agent potřebuje, a ujistěte se, že Scopes nastavení odpovídá prostředkům Graphu, které volá váš kód. Tyto příklady používají User.Read a User.ReadBasic.All; volání jiných prostředků vyžaduje odpovídající oprávnění.

  4. Teď můžete GraphServiceClient získat vložením do vaší služby nebo od poskytovatele služeb a použít Microsoft Graph.

  • Pro identity agenta můžete získat token pouze pro aplikaci (autonomní agenty) nebo token jménem uživatele (interaktivní agenty) pomocí metody WithAgentIdentity. U tokenů pouze pro aplikaci nastavte RequestAppToken vlastnost na true. Pro delegované tokeny uživatele nenastavujte vlastnost RequestAppToken ani ji nenastavujte explicitně na false.

    using Microsoft.Graph;
using Microsoft.Identity.Web;

// 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 usersAppOnly = await graphServiceClient.Users
    .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 usersOnBehalfOfUser = await graphServiceClient.Users
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
    {
        options.WithAgentIdentity(agentIdentity);
        options.RequestAppToken = false; // False to show it's on-behalf of user
    }));

    • Pro identity uživatelského účtu agenta můžete zadat buď hlavní název uživatele (UPN) nebo identitu objektu (OID), abyste pomocí metody identifikovali uživatelský účet WithAgentUserIdentity agenta.

      using Microsoft.Graph;
using Microsoft.Identity.Web;

// 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 meByOid = await graphServiceClient.Me
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
        options.WithAgentUserIdentity(agentIdentity, userOid)));

Související obsah

  • Last updated on