Nedströms-API-integrering med Microsoft. Identity.Web

Microsoft. Identity.Web innehåller flera metoder för att anropa underordnade API:er, inklusive Microsoft Graph, Azure-tjänster och anpassade REST-API:er, från dina ASP.NET Core-, OWIN- eller .NET-program. Den här artikeln hjälper dig att välja rätt metod för ditt scenario och komma igång snabbt.

Metodval

Använd det här beslutsträdet för att välja den bästa metoden för ditt scenario:

Metodjämförelse med komplexitet och flexibilitet

I följande tabell sammanfattas varje metod med det avsedda användningsfallet, komplexitetsnivån och flexibiliteten.

Mönster för tokenförvärv

Microsoft. Identity.Web har stöd för tre huvudsakliga tokenförvärvsmönster:

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

Delegerade behörigheter (användartoken)

Använd delegerade behörigheter när ditt program agerar för en inloggad användares räkning.

• Scenario: Webbappen anropar API för en inloggad användare och den autonoma agentens användaridentitet.
• Tokentyp: Åtkomsttoken med delegerade behörigheter
• Metoder: CreateAuthorizationHeaderForUserAsync(), GetForUserAsync()

Programbehörigheter (endast apptoken)

Använd programbehörigheter när ingen användare finns och appen autentiseras som sig själv.

• Scenario: Daemon-appen eller bakgrundstjänsten anropar API. Den autonoma agentens identitet
• Tokentyp: Åtkomsttoken med programbehörigheter
• Metoder: CreateAuthorizationHeaderForAppAsync(), GetForAppAsync()

Flöde för På Uppdrag Av (OBO)

Använd OBO-flödet när ett webb-API behöver anropa ett annat underordnat API samtidigt som användarens identitet bevaras.

• Scenario: Webb-API tar emot användartoken, anropar ett annat API för användaren och interaktiva agenter.
• Tokentyp: Ny åtkomsttoken via OBO-flöde
• Metoder: CreateAuthorizationHeaderForUserAsync() från webb-API-kontext

Tokenbindning (mTLS PoP)

Tokenbindning lägger till ett extra säkerhetslager genom att kryptografiskt binda åtkomsttoken till X.509-certifikat.

• Scenario: Förbättrad säkerhet där token är kryptografiskt bundna till certifikat enligt RFC 8705
• Tokentyp: Åtkomsttoken med bindning till certifikat (cnf påstående)
• Metoder: GetForAppAsync() med ProtocolScheme: "MTLS_POP"
• Säkerhet: Förhindrar tokenstöld genom att binda token till specifika certifikat

Läs mer om tokenbindning med mTLS PoP

Exempel på snabbstartskod

Följande exempel visar varje metod med kod från slutpunkt till slutpunkt som du kan anpassa till ditt program.

Microsoft Graph (rekommenderas för Graph API:er)

I följande exempel registreras GraphServiceClient och använder det för att anropa Microsoft Graph för den inloggade användarens räkning och som ett appsamtal.

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

Läs mer om Microsoft Graph integrering

GraphServiceClient-migrering och detaljerad användning

Azure-SDK:er (rekommenderas för Azure tjänster)

I följande exempel registreras MicrosoftIdentityTokenCredential och skickas till en Azure Blob Storage-klient.

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

Läs mer om Azure SDKs integrering

IDownstreamApi (rekommenderas för anpassade REST-API:er)

I följande exempel konfigureras ett namngivet underordnat API i appsettings.json och anropar det med både delegerade token och endast apptoken.

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

Läs mer om IDownstreamApi

Tokenbindning med mTLS PoP (förbättrad säkerhet)

Tokenbindning ger förbättrad säkerhet genom krypteringsbindning av åtkomsttoken till X.509-certifikat. Även om en token fångas upp kan den inte användas utan motsvarande certifikat.

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

Viktiga fördelar:

• Skydd mot tokenstöld: Stulna token är värdelösa utan certifikatet
• Skydd mot reprisattacker: Token kan inte spelas upp från olika klienter
• Noll förtroendejustering: Stark kryptografisk bindning mellan klient och token

Läs mer om tokenbindning (mTLS PoP)

MicrosoftIdentityMessageHandler (för HttpClient-integrering)

I följande exempel läggs en delegeringshanterare till en HttpClient så att varje utgående begäran automatiskt innehåller ett auktoriseringshuvud. Hanteraren registrerar omfång vid start och enskilda begäranden kan åsidosätta tokenalternativ.

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

Läs mer om MicrosoftIdentityMessageHandler

IAuthorizationHeaderProvider (högsta flexibilitet)

I följande exempel hämtas en auktoriseringsrubrik direkt så att du kan koppla den till alla HTTP-begäranden tillsammans med anpassade rubriker.

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

Läs mer om IAuthorizationHeaderProvider

Konfigurationsmönster

Microsoft. Identity.Web stöder både JSON-konfiguration och kodbaserad konfiguration.

appsettings.json-konfiguration

Följande JSON visar en typisk konfiguration som registrerar Microsoft Entra ID autentiseringsuppgifter och två underordnade API:er.

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

Läs mer om konfiguration av autentiseringsuppgifter

Kodbaserad konfiguration

Du kan också konfigurera autentiseringsuppgifter och underordnade API:er helt i kod, vilket visas i följande exempel.

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

Scenariospecifika guider

Den bästa metoden beror på var du anropar API:et från:

Integration av webbappar

Webbappar anropar vanligtvis underordnade API:er för den inloggade användarens räkning.

• Primärt mönster: Delegerade behörigheter (för användarens räkning)
• Tokenförvärv: Sker automatiskt vid inloggning
• Särskilda överväganden: Inkrementellt medgivande, hantering av medgivandefel

Läs guiden Web Apps

Webb-API-integrering

Web-API:er använder On-Behalf-Of-flödet för att byta ut en inkommande användartoken mot en ny token avsedd för det underliggande API:et.

• Primärt mönster: OBO-flöde (On-Behalf-Of)
• Token-förvärv: Byt inkommande token mot en nedströms-token
• Särskilda överväganden: Tidskrävande processer, cachelagring av token, agentidentiteter.

Läs guiden webb-API:er

Daemon-appintegrering

Daemon-appar autentiseras som sig själva utan en inloggad användare.

• Primärt mönster: Programbehörigheter (endast app)
• Tokenförvärv: Klientautentiseringsflöde
• Särskilda överväganden: Ingen användarkontext, kräver administratörsmedgivande
• Avancerat: Autonoma agenter, agentanvändares identiteter

Läs guiden Daemon Applications (Daemon-program)

Felhantering för tokenförvärv

Alla metoder för tokenförvärv kan utlösa undantag som programmet ska hantera. I webbappar [AuthorizeForScope(scopes)] hanterar attributet användarens inkrementella medgivande eller omsignering.

I följande exempel visas hur du fångar upp och hanterar vanliga undantag för tokenförvärv.

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

Vanliga felscenarier

I följande tabell visas de vanligaste undantagen och hur du löser dem.

Nödvändiga NuGet-paket

Välj det paket som matchar ditt scenario. I följande tabell visas varje paket och när det ska användas.

Relaterat innehåll

Utforska dessa guider för detaljerade genomgångar och avancerade scenarier.

• Anropa från webbappar
• Anropa från webb-API:er
• Integration med Microsoft Graph
• Översikt över autentiseringsuppgifter