Downstream-API-integratie met Microsoft. Identity.Web

Microsoft. Identity.Web biedt meerdere methoden voor het aanroepen van downstream-API's, waaronder Microsoft Graph, Azure-services en aangepaste REST API's, vanuit uw ASP.NET Core-, OWIN- of .NET-toepassingen. Dit artikel helpt u bij het kiezen van de juiste benadering voor uw scenario en snel aan de slag te gaan.

Benadering selecteren

Gebruik deze beslissingsstructuur om de beste methode voor uw scenario te selecteren:

Vergelijking van benaderingen op complexiteit en flexibiliteit

De volgende tabel bevat een overzicht van elke benadering op basis van de beoogde use-case, complexiteitsniveau en flexibiliteit.

Patronen voor tokenverwerving

Microsoft. Identity.Web ondersteunt drie belangrijkste patronen voor het verkrijgen van tokens:

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

Gedelegeerde machtigingen (gebruikerstokens)

Gebruik gedelegeerde machtigingen wanneer uw toepassing namens een aangemelde gebruiker handelt.

• Scenario: Web-app roept API aan namens aangemelde gebruiker en autonome agentgebruikersidentiteit.
• Tokentype: Toegangstoken met gedelegeerde machtigingen
• Methoden: CreateAuthorizationHeaderForUserAsync(), GetForUserAsync()

Toepassingsmachtigingen (tokens voor alleen-apps)

Gebruik toepassingsmachtigingen wanneer er geen gebruiker aanwezig is en de app zichzelf authentiseert.

• Scenario: Daemon-app of API voor achtergrondserviceaanroepen. Autonome agentidentiteit
• Tokentype: Toegangstoken met toepassingsmachtigingen
• Methoden: CreateAuthorizationHeaderForAppAsync(), GetForAppAsync()

Proces Op-Aanvraag-Van (OBO)

Gebruik de OBO-stroom wanneer een web-API een andere downstream-API moet aanroepen terwijl de identiteit van de gebruiker behouden blijft.

• Scenario: Web-API ontvangt een gebruikerstoken, roept een andere API aan namens die gebruiker en interactieve agents.
• Tokentype: Nieuw toegangstoken via OBO-stroom
• Methoden: CreateAuthorizationHeaderForUserAsync() van web-API-context

Token-binding (mTLS PoP)

Tokenbinding voegt een extra beveiligingslaag toe door cryptografisch toegangstokens te koppelen aan X.509-certificaten.

• Scenario: Verbeterde beveiliging waarbij tokens cryptografisch zijn gebonden aan certificaten volgens RFC 8705
• Tokentype: Toegangstoken met certificaatbinding (cnf claim)
• Methoden: GetForAppAsync() met ProtocolScheme: "MTLS_POP"
• Beveiliging: Voorkomt diefstal van tokens door bindingstokens aan specifieke certificaten

Meer informatie over tokenbinding met mTLS PoP

Voorbeelden van quickstart-code

In de volgende voorbeelden ziet u elke benadering met end-to-end code die u kunt aanpassen aan uw toepassing.

Microsoft Graph (aanbevolen voor Graph-API's)

In het volgende voorbeeld wordt GraphServiceClient geregistreerd en gebruikt om Microsoft Graph aan te roepen namens de aangemelde gebruiker en als een app-aanroep.

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

Meer informatie over Microsoft Graph integratie

GraphServiceClient-migratie en gedetailleerd gebruik

Azure-SDK's (aanbevolen voor Azure services)

In het volgende voorbeeld wordt MicrosoftIdentityTokenCredential geregistreerd en doorgegeven aan een Azure Blob Storage-client.

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

Meer informatie over Azure SDK integratie

IDownstreamApi (aanbevolen voor aangepaste REST API's)

In het volgende voorbeeld wordt een benoemde downstream-API geconfigureerd appsettings.json en wordt deze aangeroepen met zowel gedelegeerde als alleen-app-tokens.

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

Meer informatie over IDownstreamApi

Tokenbinding met mTLS PoP (verbeterde beveiliging)

Tokenbinding biedt verbeterde beveiliging door cryptografische toegangstokens te binden aan X.509-certificaten. Zelfs als een token wordt onderschept, kan het niet worden gebruikt zonder het bijbehorende certificaat.

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

Belangrijke voordelen:

• Beveiliging tegen diefstal van tokens: gestolen tokens zijn nutteloos zonder het certificaat
• Aanvalspreventie opnieuw afspelen: tokens kunnen niet opnieuw worden afgespeeld vanaf verschillende clients
• Uitlijning van nulvertrouwen: sterke cryptografische binding tussen client en token

Meer informatie over tokenbinding (mTLS PoP)

MicrosoftIdentityMessageHandler (voor HttpClient-integratie)

In het volgende voorbeeld wordt een delegeringshandler toegevoegd aan een HttpClient aanvraag, zodat elke uitgaande aanvraag automatisch een autorisatieheader bevat. De handler registreert bereiken bij het opstarten, en individuele verzoeken kunnen tokenopties overschrijven.

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

Meer informatie over MicrosoftIdentityMessageHandler

IAuthorizationHeaderProvider (maximale flexibiliteit)

In het volgende voorbeeld wordt een autorisatieheader rechtstreeks opgehaald, zodat u deze kunt koppelen aan een HTTP-aanvraag naast aangepaste headers.

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

Meer informatie over IAuthorizationHeaderProvider

Configuratiepatronen

Microsoft. Identity.Web ondersteunt zowel JSON-configuratie als op code gebaseerde configuratie.

configuratie van appsettings.json

In de volgende JSON ziet u een typische configuratie waarmee Microsoft Entra ID referenties en twee downstream-API's worden geregistreerd.

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

Meer informatie over configuratie van referenties

Configuratie op basis van code

U kunt ook referenties en downstream-API's volledig in code configureren, zoals in het volgende voorbeeld wordt weergegeven.

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

Scenariospecifieke handleidingen

De beste aanpak is afhankelijk van waar u de API aanroept:

Web-app-integratie

Web-apps roepen doorgaans downstream-API's aan namens de aangemelde gebruiker.

• Primair patroon: Gedelegeerde machtigingen (namens de gebruiker)
• Token ophalen: gebeurt automatisch tijdens het aanmelden
• Speciale overwegingen: Stapsgewijze toestemming, het verwerken van toestemmingfouten

lees de handleiding Web Apps

Web-API-integratie

Web-API's maken gebruik van de on-Behalf-Of-stroom om een binnenkomende gebruikerstoken uit te wisselen voor een nieuw token dat is gericht op de downstream-API.

• Primair patroon: Stroom aanBehalf-Of (OBO)
• Tokenverwerving: Exchange binnenkomende token voor downstreamtoken
• Speciale overwegingen: langlopende processen, tokencaching, agentidentiteiten.

De handleiding voor web-API's lezen

Integratie van daemon-apps

Daemon-apps verifiëren zich als zichzelf zonder een aangemelde gebruiker.

• Primair patroon: Toepassingsmachtigingen (alleen voor apps)
• Token ophalen: stroom voor clientreferenties
• Speciale overwegingen: geen gebruikerscontext, vereist beheerderstoestemming
• Geavanceerd: Autonome agents, gebruikersidentiteiten van agents

Lees de handleiding voor Daemon-toepassingen

Foutafhandeling voor het verkrijgen van tokens

Alle methoden voor het verkrijgen van tokens kunnen uitzonderingen genereren die door uw toepassing moeten worden verwerkt. In web-apps verwerkt het [AuthorizeForScope(scopes)] kenmerk incrementele toestemming van de gebruiker of het opnieuw ondertekenen.

In het volgende voorbeeld ziet u hoe u veelvoorkomende uitzonderingen voor het verkrijgen van tokens kunt ondervangen en verwerken.

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

Veelvoorkomende foutscenario's

De volgende tabel bevat de meest voorkomende uitzonderingen en hoe u deze kunt oplossen.

Vereiste NuGet-pakketten

Kies het pakket dat overeenkomt met uw scenario. De volgende tabel bevat elk pakket en wanneer u het wilt gebruiken.

Verwante inhoud

Verken deze handleidingen voor een gedetailleerd overzicht en geavanceerde scenario's.

• Bellen vanuit web-apps
• Aanroepen vanuit web-API's
• Microsoft Graph-integratie
• Overzicht van referenties