Nachgeschaltete API-Integration mit Microsoft. Identity.Web

Microsoft. Identity.Web bietet mehrere Ansätze zum Aufrufen nachgeschalteter APIs – einschließlich Microsoft Graph, Azure Diensten und benutzerdefinierten REST-APIs – aus Ihren ASP.NET Core, OWIN oder .NET Anwendungen. Dieser Artikel hilft Ihnen, den richtigen Ansatz für Ihr Szenario auszuwählen und schnell loszulegen.

Ansatzauswahl

Verwenden Sie diese Entscheidungsstruktur, um die beste Methode für Ihr Szenario auszuwählen:

Ansatzvergleich durch Komplexität und Flexibilität

In der folgenden Tabelle werden die einzelnen Ansätze anhand des vorgesehenen Anwendungsfalles, der Komplexitätsebene und der Flexibilität zusammengefasst.

Tokenakquisitionsmuster

Microsoft. Identity.Web unterstützt drei Haupttokenakquisitionsmuster:

graph LR
    A[Token Acquisition] --> B[Delegated<br/>On behalf of user]
    A --> C[App-Only<br/>Application permissions in all apps]
    A --> D[On-Behalf-Of OBO<br/>in web API]

    B --> B1[Web Apps]
    B --> B2[Daemon acting as user / user agent]
    C --> C1[Daemon Apps]
    C --> C2[Web APIs with app permissions]
    D --> D1[Web APIs calling other APIs]

    style B fill:#cfe2ff
    style C fill:#fff3cd
    style D fill:#f8d7da

Delegierte Berechtigungen (Benutzertoken)

Verwenden Sie delegierte Berechtigungen, wenn Ihre Anwendung im Namen eines angemeldeten Benutzers fungiert.

• Szenario: Eine Web-App ruft die API im Auftrag eines angemeldeten Benutzers und einer autonomen Benutzeridentität eines Agenten auf.
• Tokentyp: Zugriffstoken mit delegierten Berechtigungen
• Methoden: CreateAuthorizationHeaderForUserAsync(), GetForUserAsync()

Anwendungsberechtigungen (nur App-Token)

Verwenden Sie Anwendungsberechtigungen, wenn kein Benutzer vorhanden ist und sich die App als sich selbst authentifiziert.

• Szenario: Daemon-App oder Hintergrunddienstaufruf-API. Autonome Agentidentität
• Tokentyp: Zugriffstoken mit Anwendungsberechtigungen
• Methoden: CreateAuthorizationHeaderForAppAsync(), GetForAppAsync()

On-Behalf-Of (OBO) Ablauf

Verwenden Sie den OBO-Fluss, wenn eine Web-API eine andere downstream-API aufrufen muss, während die Identität des Benutzers erhalten bleibt.

• Szenario: Web-API empfängt Benutzertoken, ruft eine andere API im Namen dieses Benutzers und interaktiver Agents auf.
• Tokentyp: Neues Zugriffstoken über den OBO-Fluss
• Methoden: CreateAuthorizationHeaderForUserAsync() aus web-API-Kontext

Tokenbindung (mTLS PoP)

Die Tokenbindung fügt eine zusätzliche Sicherheitsebene hinzu, indem Zugriffstoken kryptografisch mit X.509-Zertifikaten gebunden werden.

• Szenario: Erweiterte Sicherheit, bei der Token kryptografisch an Zertifikate gemäß RFC 8705 gebunden sind
• Tokentyp: Zugriffstoken mit Zertifikatbindung (cnf Anspruch)
• Methoden: GetForAppAsync() mit ProtocolScheme: "MTLS_POP"
• Sicherheit: Verhindert den Tokendiebstahl, indem Token an bestimmte Zertifikate gebunden werden

Weitere Informationen zur Tokenbindung mit mTLS-PoP

Schnellstartcodebeispiele

Die folgenden Beispiele veranschaulichen jeden Ansatz mit End-to-End-Code, den Sie an Ihre Anwendung anpassen können.

Microsoft Graph (empfohlen für Graph-APIs)

Im folgenden Beispiel wird GraphServiceClient registriert und verwendet, um Microsoft Graph im Namen des angemeldeten Benutzers und als Nur-App-Aufruf aufzurufen.

// Installation
// dotnet add package Microsoft.Identity.Web.GraphServiceClient

// Startup configuration
using Microsoft.Identity.Web;

builder.Services.AddMicrosoftGraph();

// Usage in controller
public class HomeController : Controller
{
    private readonly GraphServiceClient _graphClient;

    public HomeController(GraphServiceClient graphClient)
    {
        _graphClient = graphClient;
    }

    public async Task<IActionResult> Profile()
    {
        // Delegated - calls on behalf of signed-in user
        var user = await _graphClient.Me.GetAsync();

        // App-only - requires app permissions
        var users = await _graphClient.Users
            .GetAsync(r => r.Options.WithAppOnly());

        return View(user);
    }
}

Erfahren Sie mehr über Microsoft Graph Integration

GraphServiceClient-Migration und detaillierte Nutzung

Azure SDKs (empfohlen für Azure Dienste)

Im folgenden Beispiel wird MicrosoftIdentityTokenCredential registriert und an einen Azure Blob Storage-Client übergeben.

// Installation
// dotnet add package Microsoft.Identity.Web.Azure
// dotnet add package Azure.Storage.Blobs

// Startup configuration
using Microsoft.Identity.Web;

builder.Services.AddMicrosoftIdentityAzureTokenCredential();

// Usage
public class StorageService
{
    private readonly MicrosoftIdentityTokenCredential _credential;

    public StorageService(MicrosoftIdentityTokenCredential credential)
    {
        _credential = credential;
    }

    public async Task<List<string>> ListBlobsAsync()
    {
        var blobClient = new BlobServiceClient(
            new Uri("https://myaccount.blob.core.windows.net"),
            _credential);

        var container = blobClient.GetBlobContainerClient("mycontainer");
        var blobs = new List<string>();

        await foreach (var blob in container.GetBlobsAsync())
        {
            blobs.Add(blob.Name);
        }

        return blobs;
    }
}

Erfahren Sie mehr über Azure SDK Integration

IDownstreamApi (empfohlen für benutzerdefinierte REST-APIs)

Im folgenden Beispiel wird eine benannte downstream-API konfiguriert appsettings.json und mit delegierten Tokens sowie App-only-Tokens aufgerufen.

// Installation
// dotnet add package Microsoft.Identity.Web.DownstreamApi

// appsettings.json
{
  "DownstreamApis": {
    "MyApi": {
      "BaseUrl": "https://myapi.example.com",
      "Scopes": ["api://myapi/read", "api://myapi/write"]
    }
  }
}

// Startup configuration
using Microsoft.Identity.Web;

builder.Services.AddDownstreamApis(
    builder.Configuration.GetSection("DownstreamApis"));

// Usage
public class ApiService
{
    private readonly IDownstreamApi _api;

    public ApiService(IDownstreamApi api)
    {
        _api = api;
    }

    public async Task<Product> GetProductAsync(int id)
    {
        // Delegated - on behalf of user
        return await _api.GetForUserAsync<Product>(
            "MyApi",
            $"api/products/{id}"
        );
    }

    public async Task<List<Product>> GetAllProductsAsync()
    {
        // App-only - using app permissions
        return await _api.GetForAppAsync<List<Product>>(
            "MyApi",
            "api/products");
    }
}

Weitere Informationen zu IDownstreamApi

Tokenbindung mit mTLS PoP (erweiterte Sicherheit)

Tokenbindung bietet erweiterte Sicherheit durch kryptografische Bindung von Zugriffstoken an X.509-Zertifikate. Auch wenn ein Token abgefangen wird, kann es nicht ohne das entsprechende Zertifikat verwendet werden.

// Installation
// dotnet add package Microsoft.Identity.Web.DownstreamApi

// appsettings.json
{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateStorePath": "CurrentUser/My",
        "CertificateDistinguishedName": "CN=YourCertificate"
      }
    ],
    "SendX5c": true
  },
  "SecureApi": {
    "BaseUrl": "https://api.contoso.com/",
    "RelativePath": "api/data",
    "ProtocolScheme": "MTLS_POP",
    "RequestAppToken": true,
    "Scopes": [ "api://your-api/.default" ]
  }
}

// Startup configuration
builder.Services.AddDownstreamApi(
    "SecureApi",
    builder.Configuration.GetSection("SecureApi"));

// Usage
public class SecureApiService
{
    private readonly IDownstreamApi _api;

    public SecureApiService(IDownstreamApi api)
    {
        _api = api;
    }

    public async Task<SecureData> GetSecureDataAsync()
    {
        // Token is bound to certificate - enhanced security
        return await _api.GetForAppAsync<SecureData>("SecureApi");
    }
}

Wichtige Vorteile:

• Tokendiebstahlschutz: Gestohlene Token sind ohne das Zertifikat nutzlos
• Verhinderung von Replay-Angriffen: Token können nicht von verschiedenen Clients wiedergegeben werden.
• Zero Trust Alignment: Starke kryptografische Bindung zwischen Client und Token

Weitere Informationen zur Tokenbindung (mTLS PoP)

MicrosoftIdentityMessageHandler (für httpClient-Integration)

Im folgenden Beispiel wird ein delegierender Handler zu HttpClient hinzugefügt, sodass jede ausgehende Anforderung automatisch einen Autorisierungsheader enthält. Der Handler registriert Bereiche beim Start, und einzelne Anforderungen können Tokenoptionen überschreiben.

// Startup configuration
using Microsoft.Identity.Web;

builder.Services.AddHttpClient("MyApiClient", client =>
{
    client.BaseAddress = new Uri("https://myapi.example.com");
})
.AddHttpMessageHandler(sp => new MicrosoftIdentityMessageHandler(
    sp.GetRequiredService<IAuthorizationHeaderProvider>(),
    new MicrosoftIdentityMessageHandlerOptions
    {
        Scopes = new[] { "api://myapi/.default" }
    }));

// Usage
public class ApiService
{
    private readonly HttpClient _httpClient;

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

    public async Task<Product> GetProductAsync(int id)
    {
        var request = new HttpRequestMessage(HttpMethod.Get, $"api/products/{id}")
            .WithAuthenticationOptions(options =>
            {
                options.RequestAppToken = false; // Use delegated token
                options.scopes = [ "myApi.scopes" ];
            });

        var response = await _httpClient.SendAsync(request);
        response.EnsureSuccessStatusCode();

        return await response.Content.ReadFromJsonAsync<Product>();
    }
}

Weitere Informationen zu MicrosoftIdentityMessageHandler

IAuthorizationHeaderProvider (maximale Flexibilität)

Im folgenden Beispiel wird ein Autorisierungsheader direkt abgerufen, sodass Sie ihn zusammen mit benutzerdefinierten Headern an eine beliebige HTTP-Anforderung anfügen können.

// Direct usage for custom scenarios
public class CustomAuthService
{
    private readonly IAuthorizationHeaderProvider _headerProvider;

    public CustomAuthService(IAuthorizationHeaderProvider headerProvider)
    {
        _headerProvider = headerProvider;
    }

    public async Task<string> CallApiAsync()
    {
        // Get auth header (includes "Bearer " + token)
        string authHeader = await _headerProvider
            .CreateAuthorizationHeaderForUserAsync(
                scopes: new[] { "api://myapi/.default" });

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", authHeader);
        client.DefaultRequestHeaders.Add("X-Custom-Header", "MyValue");

        var response = await client.GetStringAsync("https://myapi.example.com/data");
        return response;
    }
}

Weitere Informationen zu IAuthorizationHeaderProvider

Konfigurationsmuster

Microsoft. Identity.Web unterstützt sowohl JSON-Konfiguration als auch codebasierte Konfiguration.

appsettings.json Konfiguration

Der folgende JSON-Code zeigt eine typische Konfiguration, die Microsoft Entra ID Anmeldeinformationen und zwei downstream-APIs registriert.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity"
      }
    ]
  },
  "DownstreamApis": {
    "MicrosoftGraph": {
      "BaseUrl": "https://graph.microsoft.com/v1.0",
      "Scopes": ["User.Read", "Mail.Read"]
    },
    "MyApi": {
      "BaseUrl": "https://myapi.example.com",
      "Scopes": ["api://myapi/read"]
    }
  }
}

Mehr über die Konfiguration von Anmeldedaten erfahren

Codebasierte Konfiguration

Sie können anmeldeinformationen und downstream-APIs auch vollständig im Code konfigurieren, wie im folgenden Beispiel gezeigt.

// Explicit configuration in code
builder.Services.Configure<MicrosoftIdentityApplicationOptions>(options =>
{
    options.Instance = "https://login.microsoftonline.com/";
    options.TenantId = "your-tenant-id";
    options.ClientId = "your-client-id";
    options.ClientCredentials = new[]
    {
        CertificateDescription.FromKeyVault(
            "https://myvault.vault.azure.net",
            "MyCertificate")
    };
});

builder.Services.AddDownstreamApi("MyApi", options =>
{
    options.BaseUrl = "https://myapi.example.com";
    options.Scopes = new[] { "api://myapi/read" };
});

Szenariospezifische Leitfäden

Der beste Ansatz hängt davon ab, von wo aus Sie die API aufrufen:

Web-App-Integration

Web-Apps rufen in der Regel downstream-APIs im Namen des angemeldeten Benutzers auf.

• Primäres Muster: Delegierte Berechtigungen (im Auftrag des Benutzers)
• Tokenerwerb: Erfolgt während der Anmeldung automatisch
• Besondere Überlegungen: Inkrementelle Zustimmung, Behandlung von Zustimmungsfehlern

Lesen Sie das Web-Apps Handbuch

Web-API-Integration

Web-APIs verwenden den On-Behalf-Of Flow, um ein eingehendes Benutzertoken gegen ein neues Token auszutauschen, das auf die Downstream-API ausgerichtet ist.

• Primäres Muster: On-Behalf-Of (OBO)-Fluss
• Token acquisition: Tausche ein eingehendes Token gegen ein nachgelagertes Token
• Besondere Überlegungen: Lang andauernde Prozesse, Tokenzwischenspeicherung, Agentidentitäten.

Lesen des Web-APIs-Handbuchs

Daemon-App-Integration

Daemon-Apps authentifizieren sich selbst ohne dass ein Benutzer angemeldet ist.

• Primäres Muster: Anwendungsberechtigungen (nur App)
• Tokenerwerb: Clientanmeldeinformationsfluss
• Besondere Überlegungen: Kein Benutzerkontext, erfordert Administratorzustimmung
• Erweitert: Autonome Agents, Agent-Benutzeridentitäten

Lesen des Daemon-Anwendungshandbuchs

Fehlerbehandlung für den Tokenerwerb

Alle Tokenakquisitionsmethoden können Ausnahmen auslösen, die ihre Anwendung behandeln soll. In Web-Apps behandelt das [AuthorizeForScope(scopes)]-Attribut die inkrementelle Zustimmung des Benutzers oder das erneute Einwilligen.

Das folgende Beispiel zeigt, wie häufige Ausnahmen bei der Token-Akquisition erfasst und behandelt werden können.

using Microsoft.Identity.Abstractions;

try
{
    var result = await _api.GetForUserAsync<Data>("MyApi", "api/data");
}
catch (MicrosoftIdentityWebChallengeUserException ex)
{
    // User needs to sign in or consent to additional scopes
    // In web apps, this triggers a redirect to Microsoft Entra ID
    throw;
}
catch (HttpRequestException ex)
{
    // Downstream API returned error
    _logger.LogError(ex, "API call failed");
}

Häufige Fehlerszenarien

In der folgenden Tabelle sind die am häufigsten verwendeten Ausnahmen und deren Auflösung aufgeführt.

Erforderliche NuGet-Pakete

Wählen Sie das Paket aus, das Ihrem Szenario entspricht. In der folgenden Tabelle sind die einzelnen Pakete und deren Verwendung aufgeführt.

Verwandte Inhalte

In diesen Leitfäden finden Sie ausführliche exemplarische Vorgehensweisen und erweiterte Szenarien.

• Anrufe aus Web-Apps
• Aufrufen von Web-APIs
• Microsoft Graph integration
• Übersicht über Anmeldeinformationen