Authentifizieren von Agentidentitäten mit Microsoft. Identity.Web

Nicht .NET? Weitere Informationen finden Sie in der Entra SDK-Container-Sidecar-Dokumentation zum Entra SDK-Container. Das Container-Sidecar unterstützt Agentidentitäten in jeder Sprache und Plattform.

Verstehen der Agentenidentitäten

Das NuGet-Paket Microsoft.Identity.Web.AgentIdentities bietet Unterstützung für Agentidentitäten in Microsoft Entra ID. Es ermöglicht Anwendungen, Token für Agentanwendungen, Agentidentitäten und Agent-Benutzeridentitäten sicher zu authentifizieren und zu erwerben, was für autonome Agents, interaktive Agents, die im Namen ihres Benutzers handeln, und Agents mit ihrer eigenen Benutzeridentität nützlich ist.

Dieses Paket ist Teil des Microsoft. Identity.Web Suite von Bibliotheken und wurde in Version 3.10.0 eingeführt.

Überprüfen der wichtigsten Konzepte

Die folgenden Konzepte sind für die Arbeit mit Agentidentitäten unerlässlich.

Definieren eines Agentidentitäts-Blueprints

Ein Agenten-Identitäts-Blueprint verfügt über eine besondere Anwendungsregistrierung in Microsoft Entra mit Berechtigungen, um im Namen von Agentenidentitäten oder Agenten-Benutzeridentitäten zu handeln. Es wird durch seine Anwendungs-ID (Agent Identity Blueprint-Client-ID) dargestellt. Der Agentidentitäts-Blueprint wird mit Anmeldeinformationen (in der Regel FIC+MSI oder Clientzertifikaten) und Berechtigungen zum Abrufen von Token für sich selbst konfiguriert, um Graph aufzurufen. Dies ist die App, die Sie entwickeln. Es handelt sich um eine vertrauliche Clientanwendung, in der Regel eine Web-API. Die einzigen Berechtigungen, die es haben kann, sind die Verwaltung (Erstellen/Löschen) von Agent-Identitäten, mithilfe von Microsoft Graph.

Erstellen einer Agentidentität

Eine Agentenidentität ist ein besonderer Dienstprinzipal in Microsoft Entra. Es stellt eine Identität dar, die der Agentidentitäts-Blueprint erstellt und zur Nachahmung autorisiert ist. Es besitzt keine eigenen Zugangsdaten. Sofern der Benutzer oder Mandantenadministrator der Agentenidentität zu den entsprechenden Berechtigungsbereichen zugestimmt hat, kann der Blueprint der Agentenidentität Token im Auftrag dieser abrufen. Autonome Agenten erwerben App-Tokens im Namen der Agentenidentität. Interaktive Agenten, die mit einem Benutzertoken aufgerufen werden, erwerben Benutzertokens im Namen der Agentenidentität.

Erstellen einer Agent-Benutzeridentität

Eine Agent-Benutzeridentität ist eine Agentidentität, die auch als Benutzer fungieren kann (denken Sie an eine Agentidentität, die über ein eigenes Postfach verfügt oder Sie im Verzeichnis melden würde). Eine Agentanwendung kann ein Token im Auftrag einer Agent-Benutzeridentität abrufen.

Grundlegendes zu Verbundidentitätsanmeldeinformationen (FIC)

FIC ist ein Vertrauensmechanismus in Microsoft Entra, der ermöglicht, dass Anwendungen einander mithilfe von OpenID Connect (OIDC)-Token vertrauen können. Im Kontext von Agentidentitäten werden FICs verwendet, um eine Vertrauensstellung zwischen der Agentanwendung und Agentidentitäten sowie Agentidentitäten und Agentbenutzeridentitäten herzustellen.

Suchen nach weiteren Informationen

Ausführliche Informationen zu Microsoft Entra Agentidentitäten finden Sie in der Dokumentation Microsoft Entra-Agent-ID.

Installiere das Paket

Führen Sie den folgenden Befehl aus, um das NuGet-Paket zu Ihrem Projekt hinzuzufügen:

dotnet add package Microsoft.Identity.Web.AgentIdentities

Implementieren von Agentidentitäten

Führen Sie die folgenden Schritte aus, um Agentidentitäten in Ihrer Anwendung zu konfigurieren und zu verwenden.

1. Konfigurieren von Diensten

Registrieren Sie zunächst die erforderlichen Dienste in Ihrer Anwendung:

// Add the core Identity Web services
services.AddTokenAcquisition();
services.AddInMemoryTokenCaches();
services.AddHttpClient();

// Add Microsoft Graph integration if needed.
// Requires the Microsoft.Identity.Web.GraphServiceClient package
services.AddMicrosoftGraph();

// Add Agent Identities support
services.AddAgentIdentities();

2. Konfigurieren des Agentidentitäts-Blueprints

Konfigurieren Sie Ihre Agent-Identitäts-Blueprint-Anwendung mit den erforderlichen Anmeldeinformationen mithilfe von appsettings.json:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "agent-application-client-id",

    "ClientCredentials": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateStorePath": "LocalMachine/My",
        "CertificateDistinguishedName": "CN=YourCertificateName"
      }

      // Or for Federation Identity Credential with Managed Identity:
      // {
      //   "SourceType": "SignedAssertionFromManagedIdentity",
      //   "ManagedIdentityClientId": "managed-identity-client-id"  // Omit for system-assigned
      // }
    ]
  }
}

Oder konfigurieren Sie bei Bedarf programmgesteuert:

// Configure the information about the agent application
services.Configure<MicrosoftIdentityApplicationOptions>(
    options =>
    {
        options.Instance = "https://login.microsoftonline.com/";
        options.TenantId = "your-tenant-id";
        options.ClientId = "agent-application-client-id";
        options.ClientCredentials = [
            CertificateDescription.FromStoreWithDistinguishedName(
                "CN=YourCertificateName", StoreLocation.LocalMachine, StoreName.My)
        ];
    });

Hier finden Sie https://aka.ms/ms-id-web/credential-description alle Möglichkeiten, um Anmeldeinformationen anzugeben.

Verwenden Sie auf ASP.NET Core die Außerkraftsetzung von Diensten. Konfigurieren sie das Übernehmen eines Authentifizierungsschemas. Sie können auch Microsoft.Identity.Web.Owin verwenden, wenn Sie eine ASP.NET Core-Anwendung auf OWIN haben (für neue Apps nicht empfohlen) oder sogar eine Daemon-Anwendung erstellen.

3. Verwenden von Agentidentitäten

Wählen Sie das entsprechende Tokenerwerbsmuster basierend auf Ihrem Agentszenario aus.

Abrufen von Token für eine Agentidentität

Verwenden Sie diese Muster, um Token für Agentidentitäten in autonomen oder interaktiven Szenarien abzurufen.

Erwerben von App-Token für autonome Agents

Damit Ihre autonome Agent-Anwendung nur App-Token für eine Agentidentität erwirbt:

// Get the required services from the DI container
IAuthorizationHeaderProvider authorizationHeaderProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Configure options for the agent identity
string agentIdentity = "agent-identity-guid";
var options = new AuthorizationHeaderProviderOptions()
    .WithAgentIdentity(agentIdentity);

// Acquire an access token for the agent identity
string authHeader = await authorizationHeaderProvider
    .CreateAuthorizationHeaderForAppAsync("https://resource/.default", options);

// The authHeader contains "Bearer " + the access token (or another protocol
// depending on the options)
Erwerben von Benutzertoken für interaktive Agents

Damit Ihre interaktive Agent-Anwendung Benutzertoken für eine Agentidentität im Namen des Benutzers erwirbt, der die Web-API aufruft:

// Get the required services from the DI container
IAuthorizationHeaderProvider authorizationHeaderProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Configure options for the agent identity
string agentIdentity = "agent-identity-guid";
var options = new AuthorizationHeaderProviderOptions()
    .WithAgentIdentity(agentIdentity);

// Acquire an access token for the agent identity
string authHeader = await authorizationHeaderProvider
    .CreateAuthorizationHeaderForAppAsync(["https://resource/.default"], options);

// The authHeader contains "Bearer " + the access token (or another protocol
// depending on the options)

Abrufen von Token für eine Agenten-Benutzeridentität

Damit Ihre Agentanwendung Token im Namen einer Agent-Benutzeridentität erwirbt, können Sie entweder den UPN des Benutzers (Benutzerprinzipalname) oder OID (Objekt-ID) verwenden.

Authentifizieren mit UPN (Benutzerprinzipalname)

Im folgenden Beispiel wird ein Benutzertoken durch Angabe des UPN des Benutzers abgerufen:

// Get the required services
IAuthorizationHeaderProvider authorizationHeaderProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Configure options for the agent user identity using UPN
string agentIdentity = "agent-identity-client-id";
string userUpn = "user@contoso.com";
var options = new AuthorizationHeaderProviderOptions()
    .WithAgentUserIdentity(agentIdentity, userUpn);

// Create a ClaimsPrincipal to enable token caching
ClaimsPrincipal user = new ClaimsPrincipal();

// Acquire a user token
string authHeader = await authorizationHeaderProvider
    .CreateAuthorizationHeaderForUserAsync(
        scopes: ["https://graph.microsoft.com/.default"],
        options: options,
        user: user);

// The user object now has claims including uid and utid. If you use it
// in another call it will use the cached token.
Authentifizieren mit OID (Objekt-ID)

Im folgenden Beispiel wird ein Benutzertoken durch Angabe des OID des Benutzers abgerufen:

// Get the required services
IAuthorizationHeaderProvider authorizationHeaderProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Configure options for the agent user identity using OID
string agentIdentity = "agent-identity-client-id";
Guid userOid = Guid.Parse("e1f76997-1b35-4aa8-8a58-a5d8f1ac4636");
var options = new AuthorizationHeaderProviderOptions()
    .WithAgentUserIdentity(agentIdentity, userOid);

// Create a ClaimsPrincipal to enable token caching
ClaimsPrincipal user = new ClaimsPrincipal();

// Acquire a user token
string authHeader = await authorizationHeaderProvider
    .CreateAuthorizationHeaderForUserAsync(
        scopes: ["https://graph.microsoft.com/.default"],
        options: options,
        user: user);

// The user object now has claims including uid and utid. If you use it
// in another call it will use the cached token.

4. Integration mit Microsoft Graph

Installieren Sie die Microsoft. Identity.Web.AgentIdentities-Paket, das Unterstützung für Agentidentitäten hinzufügt.

dotnet add package Microsoft.Identity.Web.AgentIdentities

Fügen Sie Unterstützung für Microsoft Graph in Ihrer Dienstsammlung hinzu:

services.AddMicrosoftGraph();

Sie können jetzt einen GraphServiceClient vom Dienstanbieter erhalten.

Aufrufen von Microsoft Graph mit Agentidentität

Im folgenden Beispiel werden Microsoft Graph APIs mithilfe einer Agentidentität aufgerufen:

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

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

Aufrufen von Microsoft Graph mit Agent-Benutzeridentität

Sie können UPN oder OID mit Microsoft Graph verwenden:

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

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

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

5. Integration mit downstream-APIs

So rufen Sie andere APIs mithilfe der IDownstreamApi Abstraktion auf:

  1. Installieren Sie das Microsoft.Identity.Web.DownstreamApi-Paket, das die IDownstreamApi-Abstraktion bereitstellt.
dotnet add package Microsoft.Identity.Web.DownstreamApi
  1. Fügen Sie in Ihrer Konfiguration einen DownstreamApis Abschnitt hinzu, der die Parameter für Die downstream-API angibt:
"AzureAd":{
    // usual config
},
"DownstreamApis":{
   "MyApi":
   {
    "BaseUrl": "https://myapi.domain.com",
    "Scopes": [ "https://myapi.domain.com/read", "https://myapi.domain.com/write" ]
   }
}
  1. Fügen Sie Unterstützung für nachgeschaltete APIs in Ihrer Dienstsammlung hinzu:
services.AddDownstreamApis(Configuration.GetSection("DownstreamApis"));

Sie können jetzt über den Dienstanbieter auf einen IDownstreamApi Dienst zugreifen und die "MyApi"-API mithilfe eines beliebigen HTTP-Verbs aufrufen. Das folgende Beispiel veranschaulicht das Aufrufen von APIs mit Agentidentität und Agent-Benutzeridentität:

// Get the IDownstreamApi service
IDownstreamApi downstreamApi = serviceProvider.GetRequiredService<IDownstreamApi>();

// Call API with agent identity
var response = await downstreamApi.GetForAppAsync<string>(
    "MyApi",
    options => options.WithAgentIdentity(agentIdentity));

// Call API with agent user identity using UPN
var userResponse = await downstreamApi.GetForUserAsync<string>(
    "MyApi",
    options => options.WithAgentUserIdentity(agentIdentity, userUpn));

// Or using OID
var userResponseByOid = await downstreamApi.GetForUserAsync<string>(
    "MyApi",
    options => options.WithAgentUserIdentity(agentIdentity, userOid));

6. Integration mit Azure SDKs

Um Azure SDKs aufzurufen, verwenden Sie die klasse MicrosoftIdentityAzureCredential aus dem Microsoft. Identity.Web. Azure NuGet-Paket.

Installieren Sie das Microsoft.Identity.Web.Azure-Paket:

dotnet add package Microsoft.Identity.Web.Azure

Fügen Sie Unterstützung für Azure-Token-Anmeldeinformationen zu Ihrer Dienstsammlung hinzu:

services.AddMicrosoftIdentityAzureTokenCredential();

Sie können jetzt einen MicrosoftIdentityTokenCredential vom Dienstanbieter erhalten. Diese Klasse verfügt über ein Mitglied namens Options, auf das Sie die Methoden .WithAgentIdentity() oder .WithAgentUserIdentity() anwenden können.

Weitere Informationen finden Sie unter Azure SDKs integration.

7. Konfigurieren von HttpClient mit MicrosoftIdentityMessageHandler

Um HttpClient direkt mit flexiblen Authentifizierungsoptionen zu verwenden, verwenden Sie die MicrosoftIdentityMessageHandler aus dem Microsoft. Identity.Web.TokenAcquisition-Paket.

Hinweis: Das Paket Microsoft.Identity.Web.TokenAcquisition wird bereits von Microsoft.Identity.Web.AgentIdentities referenziert.

Authentifizieren der Agentidentität mit MicrosoftIdentityMessageHandler

Im folgenden Beispiel wird ein HttpClient mit Agentidentitätsauthentifizierung konfiguriert:

// Configure HttpClient with MicrosoftIdentityMessageHandler in DI
services.AddHttpClient("MyApiClient", client =>
{
    client.BaseAddress = new Uri("https://myapi.domain.com");
})
.AddMicrosoftIdentityMessageHandler(options =>
{
    options.Scopes= { "https://myapi.domain.com/.default" }
});

// Usage in your service or controller
public class MyService
{
    private readonly HttpClient _httpClient;

    public MyService(IHttpClientFactory httpClientFactory)
    {
        _httpClient = httpClientFactory.CreateClient("MyApiClient");
    }

    public async Task<string> CallApiWithAgentIdentity(string agentIdentity)
    {
        // Create request with agent identity authentication
        var request = new HttpRequestMessage(HttpMethod.Get, "/api/data")
            .WithAuthenticationOptions(options =>
            {
                options.WithAgentIdentity(agentIdentity);
                options.RequestAppToken = true;
            });

        var response = await _httpClient.SendAsync(request);
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadAsStringAsync();
    }
}

Authentifizieren der Agent-Benutzeridentität mit MicrosoftIdentityMessageHandler

Im folgenden Beispiel wird eine anforderung gesendet, die mit einer Agent-Benutzeridentität authentifiziert wurde:

public async Task<string> CallApiWithAgentUserIdentity(string agentIdentity, string userUpn)
{
    // Create request with agent user identity authentication
    var request = new HttpRequestMessage(HttpMethod.Get, "/api/userdata")
        .WithAuthenticationOptions(options =>
        {
            options.WithAgentUserIdentity(agentIdentity, userUpn);
            options.Scopes.Add("https://myapi.domain.com/user.read");
        });

    var response = await _httpClient.SendAsync(request);
    response.EnsureSuccessStatusCode();
    return await response.Content.ReadAsStringAsync();
}

Manuelles Konfigurieren von HttpClient

Sie können den Handler auch manuell für mehr Kontrolle konfigurieren:

// Get the authorization header provider
IAuthorizationHeaderProvider headerProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Create the handler with default options
var handler = new MicrosoftIdentityMessageHandler(
    headerProvider,
    new MicrosoftIdentityMessageHandlerOptions
    {
        Scopes = { "https://graph.microsoft.com/.default" }
    });

// Create HttpClient with the handler
using var httpClient = new HttpClient(handler);

// Make requests with per-request authentication options
var request = new HttpRequestMessage(HttpMethod.Get, "https://graph.microsoft.com/v1.0/applications")
    .WithAuthenticationOptions(options =>
    {
        options.WithAgentIdentity(agentIdentity);
        options.RequestAppToken = true;
    });

var response = await httpClient.SendAsync(request);

Die MicrosoftIdentityMessageHandler bietet eine flexible, komponierbare Möglichkeit zum Hinzufügen der Authentifizierung zu Ihrem httpClient-basierten Code und gleichzeitig die vollständige Kompatibilität mit vorhandenen Microsoft Identity Web Extension-Methoden für Agentidentitäten.

Überprüfung von Token aus Agentidentitäten

Überprüfen Sie Token, die für Agentenidentitäten oder Agenten-Benutzeridentitäten erworben wurden, auf die gleiche Weise wie für jede Web-API. Sie können jedoch auch:

  • Überprüfen Sie, ob ein Token für eine Agentenidentität ausgestellt wurde und für welchen Agenten-Blueprint.

    HttpContext.User.GetParentAgentBlueprint()

    gibt die ClientId des übergeordneten Agent-Blueprints zurück, wenn das Token für eine Agent-Identität (oder Agent-Benutzeridentität) ausgegeben wird\

  • Überprüfen Sie, ob ein Token für eine Agent-Benutzeridentität ausgestellt wurde.

    HttpContext.User.IsAgentUserIdentity()

Diese beiden Erweiterungsmethoden gelten sowohl für ClaimsIdentity als auch für ClaimsPrincipal.

Überprüfen der Voraussetzungen

Stellen Sie sicher, dass Sie diese Konfigurationsschritte vor der Implementierung von Agentidentitäten ausführen.

Konfigurieren Microsoft Entra Registrierung

  1. Agentanwendungskonfiguration:

    • Registrieren einer Agentanwendung mit dem Graph SDK
    • Client-Anmeldeinformationen zur Agentanwendung hinzufügen
    • Erteilen geeigneter API-Berechtigungen, z. B. Application.ReadWrite.All zum Erstellen von Agentidentitäten
    • Beispielkonfiguration in JSON: 
      {
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "agent-application-id",
    "ClientCredentials": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateStorePath": "LocalMachine/My",
        "CertificateDistinguishedName": "CN=YourCertName"
      }
    ]
  }
}

  2. Agent-Identitätskonfiguration:

    • Lassen Sie den Agenten eine Agentenidentität erstellen.
    • Erteilen Sie entsprechende API-Berechtigungen basierend auf den Erfordernissen Ihrer Agentenidentität.

  3. Benutzerberechtigung:

    • Stellen Sie für Agentbenutzeridentitätsszenarien sicher, dass geeignete Benutzerberechtigungen konfiguriert sind.

Grundlegendes zum Authentifizierungsfluss

Unter der Haube ist das Microsoft.Identity.Web.AgentIdentities-Paket:

  1. Stellt eine Vertrauensstellung zwischen der Agentanwendung und der Agentidentität sowie zwischen der Agent-Identität und der Agent-Benutzeridentität mithilfe von Verbundidentitätsanmeldeinformationen (FIC) her.
  2. Erwirbt FIC-Token mithilfe der GetFicTokenAsync Methode
  3. Verwendet die FIC-Token, um sich als Agentenidentität zu authentifizieren
  4. Für Benutzeridentitäten von Agenten verwendet es MSAL-Erweiterungen, um Benutzertoken zu erwerben.

Häufige Probleme beheben

Überprüfen Sie diese häufig auftretenden Probleme und Lösungen beim Arbeiten mit Agentidentitäten.

Beheben bekannter Probleme

  1. Fehlende FIC-Konfiguration: Stellen Sie sicher, dass die Verbundidentitätsnachweise in Microsoft Entra zwischen der Agentanwendung und der Agentidentität ordnungsgemäß konfiguriert sind.

  2. Berechtigungsprobleme: Überprüfen Sie, ob die Agentanwendung über ausreichende Berechtigungen zum Verwalten von Agentidentitäten verfügt und dass die Agentidentitäten über ausreichende Berechtigungen zum Aufrufen der downstream-APIs verfügen.

  3. Zertifikatprobleme: Wenn Sie ein Clientzertifikat verwenden, überprüfen Sie, ob das Zertifikat in der App-Registrierung registriert ist, ordnungsgemäß installiert und vom Agentanwendungscode zugänglich ist.

  4. Tokenerwerbsfehler: Aktivieren der Protokollierung zum Diagnostizieren von Tokenakquisitionsfehlern. Der folgende Code konfiguriert die Protokollierung auf Debugebene der Konsole:

    services.AddLogging(builder => {
    builder.AddConsole();
    builder.SetMinimumLevel(LogLevel.Debug);
});

Weitere Ressourcen erkunden

  • Last updated on