Memanggil API Microsoft Graph menggunakan agen di .NET

Artikel ini menjelaskan cara memanggil Microsoft Graph API dari agen menggunakan identitas agen atau akun pengguna agen.

Untuk memanggil API dari agen, Anda perlu mendapatkan token akses yang dapat digunakan agen untuk mengautentikasi dirinya ke API. Sebaiknya gunakan Microsoft. Identity.Web SDK untuk .NET memanggil API web Anda. SDK ini menyederhanakan proses memperoleh dan memvalidasi token. Untuk bahasa lain, gunakan Microsoft Entra ID Auth SDK (sidecar).

Prasyarat

  • Identitas agen dengan izin yang sesuai untuk memanggil API target. Anda memerlukan pengguna untuk proses alur atas nama.
  • Akun pengguna agen dengan izin yang sesuai untuk memanggil API target.

Memanggil Microsoft Graph API

  1. Instal Microsoft. Identity.Web.GraphServiceClient yang menangani autentikasi untuk Graph SDK dan Microsoft. Identity.Web.AgentIdentities untuk menambahkan dukungan untuk identitas agen.

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

  2. Tambahkan dukungan untuk Microsoft Graph dan identitas agen dalam koleksi layanan Anda.

    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. Konfigurasikan Graph dan opsi identitas agen di appsettings.json.

    Peringatan

    Rahasia klien tidak boleh digunakan sebagai kredensial klien di lingkungan produksi untuk cetak biru identitas agen karena risiko keamanan. Sebagai gantinya, gunakan metode autentikasi yang lebih aman seperti kredensial identitas gabungan (FIC) dengan identitas terkelola atau sertifikat klien. Metode ini memberikan keamanan yang ditingkatkan dengan menghilangkan kebutuhan untuk menyimpan rahasia sensitif langsung dalam konfigurasi aplikasi Anda.

    {
  "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

    Konfigurasikan hanya izin Microsoft Graph yang diperlukan agen Anda, dan pastikan Scopes yang Anda tetapkan sesuai dengan sumber daya Graph yang dipanggil oleh kode Anda. Contoh-contoh ini menggunakan User.Read dan User.ReadBasic.All; memanggil sumber daya lain memerlukan izin yang sesuai.

  4. Anda sekarang bisa mendapatkan GraphServiceClient dengan menyuntikkannya ke layanan Anda atau dari penyedia layanan, lalu memanggil Microsoft Graph.

  • Untuk identitas agen, Anda dapat memperoleh token aplikasi saja (agen otonom) atau atas nama token pengguna (agen interaktif) dengan menggunakan metode .WithAgentIdentity Untuk token khusus aplikasi, atur properti ke RequestAppTokentrue. Untuk token pengguna yang didelegasikan atas nama, jangan setel properti RequestAppToken atau secara eksplisit setel ke 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
    }));

    • Untuk identitas akun pengguna agen, Anda dapat menentukan Nama Prinsipal Pengguna (UPN) atau Identitas Objek (OID) untuk mengidentifikasi akun pengguna agen dengan menggunakan WithAgentUserIdentity metode .

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

Konten terkait

  • Last updated on