Web-App, die Web-APIs aufruft: CodekonfigurationA web app that calls web APIs: Code configuration

Wie im Szenario Web-App, die Benutzer anmeldet gezeigt, verwendet die Web-App den OAuth 2.0-Autorisierungscodeflow, um den Benutzer anzumelden.As shown in the Web app that signs in users scenario, the web app uses the OAuth 2.0 authorization code flow to sign the user in. Dieser Flow besteht aus zwei Schritten:This flow has two steps:

  1. Anfordern eines Autorisierungscodes.Request an authorization code. Dieser Teil delegiert einen privaten Dialog mit dem Benutzer an Microsoft Identity Platform.This part delegates a private dialogue with the user to the Microsoft identity platform. Während des Dialogs meldet sich der Benutzer an und stimmt der Verwendung von Web-APIs zu.During that dialogue, the user signs in and consents to the use of web APIs. Wenn dieser private Dialog erfolgreich beendet wird, erhält die Web-App einen Autorisierungscode an ihren Umleitungs-URI.When the private dialogue ends successfully, the web app receives an authorization code on its redirect URI.
  2. Anfordern eines Zugriffstokens für die API durch Einlösen des Autorisierungscodes.Request an access token for the API by redeeming the authorization code.

In den Szenarien Web-App, die Benutzer anmeldet wurde nur der erste Schritt behandelt.The Web app that signs in users scenarios covered only the first step. Hier erfahren Sie, wie Sie Ihre Web-App so ändern, dass sie nicht nur Benutzer anmeldet, sondern auch Web-APIs aufruft.Here you learn how to modify your web app so that it not only signs users in but also now calls web APIs.

Bibliotheken mit Unterstützung für Web-App-SzenarienLibraries that support web-app scenarios

Die folgenden Bibliotheken in der Microsoft-Authentifizierungsbibliothek (Microsoft Authentification Library, MSAL) unterstützen den Autorisierungscodeflow für Web-Apps:The following libraries in the Microsoft Authentication Library (MSAL) support the authorization code flow for web apps:

MSAL-BibliothekMSAL library BESCHREIBUNGDescription
MSAL.NET
MSAL.NETMSAL.NET
Unterstützung für .NET Framework- und .NET Core-Plattformen.Support for .NET Framework and .NET Core platforms. Nicht unterstützt werden UWP (Universal Windows Platform), Xamarin.iOS und Xamarin.Android, da diese Plattformen zum Erstellen öffentlicher Clientanwendungen verwendet werden.Not supported are Universal Windows Platform (UWP), Xamarin.iOS, and Xamarin.Android, because those platforms are used to build public client applications.

Für ASP.NET Core-Web-Apps und Web-APIs ist MSAL.NET in einer Bibliothek höherer Ebene namens Microsoft.Identity.Web gekapselt.For ASP.NET Core web apps and web APIs, MSAL.NET is encapsulated in a higher-level library named Microsoft.Identity.Web.
MSAL Python
MSAL für PythonMSAL for Python
Unterstützung für Python-Webanwendungen.Support for Python web applications.
MSAL Java
MSAL für JavaMSAL for Java
Unterstützung für Java-Webanwendungen.Support for Java web applications.

Wählen Sie die Registerkarte für die Plattform aus, die Sie interessiert:Select the tab for the platform you're interested in:

Geheime Clientschlüssel oder ClientzertifikateClient secrets or client certificates

Wenn Ihre Web-App jetzt eine Downstream-Web-API aufruft, geben Sie in der Datei appsettings.json einen geheimen Clientschlüssel oder ein Clientzertifikat an.Given that your web app now calls a downstream web API, provide a client secret or client certificate in the appsettings.json file. Sie können auch einen Abschnitt hinzufügen, in dem Folgendes angegeben wird:You can also add a section that specifies:

  • Die URL der Downstream-Web-APIThe URL of the downstream web API
  • Die zum Aufrufen der API erforderlichen BereicheThe scopes required for calling the API

Im folgenden Beispiel sind diese Einstellungen im Abschnitt GraphBeta angegeben.In the following example, the GraphBeta section specifies these settings.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Client_id-of-web-app-eg-2ec40e65-ba09-4853-bcde-bcb60029e596]",
    "TenantId": "common"

   // To call an API
   "ClientSecret": "[Copy the client secret added to the app from the Azure portal]",
   "ClientCertificates": [
  ]
 },
 "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": "user.read"
    }
}

Statt eines geheimen Clientschlüssels können Sie ein Clientzertifikat angeben.Instead of a client secret, you can provide a client certificate. Im folgenden Codeausschnitt ist die Verwendung eines in Azure Key Vault gespeicherten Zertifikats dargestellt.The following code snippet shows using a certificate stored in Azure Key Vault.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Client_id-of-web-app-eg-2ec40e65-ba09-4853-bcde-bcb60029e596]",
    "TenantId": "common"

   // To call an API
   "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
        "KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
      }
   ]
  },
  "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": "user.read"
  }
}

Microsoft.Identity.Web bietet verschiedene Möglichkeiten, Zertifikate zu beschreiben, sowohl durch Konfiguration als auch durch Code.Microsoft.Identity.Web provides several ways to describe certificates, both by configuration or by code. Weitere Informationen finden Sie unter Microsoft.Identity.Web: Verwenden von Zertifikaten auf GitHub.For details, see Microsoft.Identity.Web - Using certificates on GitHub.

Startup.csStartup.cs

Ihre Web-App muss ein Token für die Downstream-API abrufen.Your web app will need to acquire a token for the downstream API. Die Angabe erfolgt durch Hinzufügen der Zeile .EnableTokenAcquisitionToCallDownstreamApi() nach .AddMicrosoftIdentityWebApi(Configuration).You specify it by adding the .EnableTokenAcquisitionToCallDownstreamApi() line after .AddMicrosoftIdentityWebApi(Configuration). Diese Zeile macht den ITokenAcquisition-Dienst verfügbar, den Sie in Ihren Controller- und Seitenaktionen verwenden können.This line exposes the ITokenAcquisition service that you can use in your controller and page actions. Wie jedoch aus den folgenden beiden Optionen hervorgeht, kann es einfacher gemacht werden.However, as you'll see in the following two options, it can be done more simply. Sie müssen auch eine Tokencacheimplementierung (z. B. .AddInMemoryTokenCaches()) in Startup.cs auswählen:You'll also need to choose a token cache implementation, for example .AddInMemoryTokenCaches(), in Startup.cs:

using Microsoft.Identity.Web;

public class Startup
{
  // ...
  public void ConfigureServices(IServiceCollection services)
  {
  // ...
  services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
          .AddMicrosoftIdentityWebApp(Configuration, Configuration.GetSection("AzureAd"))
            .EnableTokenAcquisitionToCallDownstreamApi(new string[]{"user.read" })
            .AddInMemoryTokenCaches();
   // ...
  }
  // ...
}

Die an EnableTokenAcquisitionToCallDownstreamApi übergebenen Bereiche sind optional und ermöglichen Ihrer Web-App das Anfordern der Bereiche und der Zustimmung des Benutzers zu diesen Bereichen bei der Anmeldung.The scopes passed to EnableTokenAcquisitionToCallDownstreamApi are optional, and enable your web app to request the scopes and the user's consent to those scopes when they log in. Wenn Sie die Bereiche nicht angeben, aktiviert Microsoft.Identity.Web einen inkrementellen Zustimmungsprozess.If you don't specify the scopes, Microsoft.Identity.Web will enable an incremental consent experience.

Wenn Sie das Token nicht selbst abrufen möchten, bietet Microsoft.Identity.Web zwei Mechanismen zum Aufrufen einer Web-API über eine Web-App.If you don't want to acquire the token yourself, Microsoft.Identity.Web provides two mechanisms for calling a web API from a web app. Welche Option Sie auswählen, hängt davon ab, ob Sie Microsoft Graph oder eine andere API aufrufen möchten.The option you choose depends on whether you want to call Microsoft Graph or another API.

Option 1: Aufrufen von Microsoft GraphOption 1: Call Microsoft Graph

Wenn Sie Microsoft Graph aufrufen möchten, bietet Microsoft.Identity.Web die Möglichkeit, den (über das Microsoft Graph SDK verfügbar gemachten) GraphServiceClient in Ihren API-Aktionen direkt zu verwenden.If you want to call Microsoft Graph, Microsoft.Identity.Web enables you to directly use the GraphServiceClient (exposed by the Microsoft Graph SDK) in your API actions. Gehen Sie wie folgt vor, um Microsoft Graph verfügbar zu machen:To expose Microsoft Graph:

  1. Fügen Sie Ihrem Projekt das NuGet-Paket Microsoft.Identity.Web.MicrosoftGraph hinzu.Add the Microsoft.Identity.Web.MicrosoftGraph NuGet package to your project.

  2. Fügen Sie in der Datei Startup.cs nach .EnableTokenAcquisitionToCallDownstreamApi() den Eintrag .AddMicrosoftGraph() hinzu.Add .AddMicrosoftGraph() after .EnableTokenAcquisitionToCallDownstreamApi() in the Startup.cs file. .AddMicrosoftGraph() verfügt über mehrere Überschreibungen..AddMicrosoftGraph() has several overrides. Wenn Sie die Überschreibung verwenden, die einen Konfigurationsabschnitt als Parameter annimmt, sieht der Code wie folgt aus:Using the override that takes a configuration section as a parameter, the code becomes:

    using Microsoft.Identity.Web;
    
    public class Startup
    {
      // ...
      public void ConfigureServices(IServiceCollection services)
      {
      // ...
      services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
              .AddMicrosoftIdentityWebApp(Configuration, Configuration.GetSection("AzureAd"))
                .EnableTokenAcquisitionToCallDownstreamApi(new string[]{"user.read" })
                   .AddMicrosoftGraph(Configuration.GetSection("GraphBeta"))
                .AddInMemoryTokenCaches();
       // ...
      }
      // ...
    }
    

Option 2: Aufrufen einer anderen Downstream-Web-API als Microsoft GraphOption 2: Call a downstream web API other than Microsoft Graph

Zum Aufrufen einer anderen Web-API als Microsoft Graph stellt Microsoft.Identity.Web die Methode .AddDownstreamWebApi() bereit, die Token anfordert und die Downstream-Web-API aufruft.To call a web API other than Microsoft Graph, Microsoft.Identity.Web provides .AddDownstreamWebApi(), which requests tokens and calls the downstream web API.

using Microsoft.Identity.Web;

public class Startup
{
  // ...
  public void ConfigureServices(IServiceCollection services)
  {
  // ...
  services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
          .AddMicrosoftIdentityWebApp(Configuration, "AzureAd")
            .EnableTokenAcquisitionToCallDownstreamApi(new string[]{"user.read" })
               .AddDownstreamWebApi("MyApi", Configuration.GetSection("GraphBeta"))
            .AddInMemoryTokenCaches();
   // ...
  }
  // ...
}

ZusammenfassungSummary

Wie bei Web-APIs können Sie verschiedene Tokencacheimplementierungen auswählen.As with web APIs, you can choose various token cache implementations. Weitere Informationen finden Sie unter Microsoft.Identity.Web: Tokencacheserialisierung auf GitHub.For details, see Microsoft.Identity.Web - Token cache serialization on GitHub.

In der folgenden Abbildung sind die verschiedenen Möglichkeiten von Microsoft.Identity.Web und die Auswirkungen auf die Datei Startup.cs dargestellt:The following image shows the various possibilities of Microsoft.Identity.Web and their impact on the Startup.cs file:

Blockdiagramm mit Dienstkonfigurationsoptionen in der Datei „Startup.cs“ zum Aufrufen einer Web-API und zum Angeben einer Tokencacheimplementierung

Hinweis

Um die hier aufgeführten Codebeispiele in vollem Umfang zu verstehen, müssen Sie mit den ASP.NET Core-Grundlagen und insbesondere mit der Abhängigkeitsinjektion und den Optionen vertraut sein.To fully understand the code examples here, be familiar with ASP.NET Core fundamentals, and in particular with dependency injection and options.

Code, der den Autorisierungscode einlöstCode that redeems the authorization code

Microsoft.Identity.Web vereinfacht Ihren Code, indem es die richtigen OpenID-Verbindungseinstellungen festlegt, das Ereignis „Code erhalten“ abonniert und den Code einlöst.Microsoft.Identity.Web simplifies your code by setting the correct OpenID Connect settings, subscribing to the code received event, and redeeming the code. Zum Einlösen des Autorisierungscodes ist kein weiterer Code erforderlich.No additional code is required to redeem the authorization code. Ausführliche Informationen zur Funktionsweise finden Sie im Microsoft.Identity.Web-Quellcode.See Microsoft.Identity.Web source code for details on how this works.

Die vertrauliche Clientanwendung kann ihre Identität statt mit einem geheimen Clientschlüssel auch mithilfe eines Clientzertifikats oder einer Clientassertion nachweisen.Instead of a client secret, the confidential client application can also prove its identity by using a client certificate, or a client assertion. Die Verwendung von Clientassertionen ist ein erweitertes Szenario, das unter Clientassertionen detailliert beschrieben ist.The use of client assertions is an advanced scenario, detailed in Client assertions.

TokencacheToken cache

Wichtig

Die Tokencache-Implementierung für Web-Apps oder Web-APIs unterscheidet sich von der Implementierung für Desktopanwendungen, die häufig dateibasiert ist.The token-cache implementation for web apps or web APIs is different from the implementation for desktop applications, which is often file based. Aus Sicherheits- und Leistungsgründen ist es wichtig, sicherzustellen, dass es für Web-Apps und Web-APIs ein Tokencache pro Benutzerkonto gibt.For security and performance reasons, it's important to ensure that for web apps and web APIs there is one token cache per user account. Sie müssen den Tokencache für jedes Konto serialisieren.You must serialize the token cache for each account.

Im ASP.NET Core-Tutorial wird die Abhängigkeitsinjektion verwendet, um Ihnen die Entscheidung über die Tokencache-Implementierung in der Datei „Startup.cs“ für Ihre Anwendung zu ermöglichen.The ASP.NET core tutorial uses dependency injection to let you decide the token cache implementation in the Startup.cs file for your application. Microsoft.Identity.Web enthält eine Reihe vordefinierter Tokencache-Serialisierungsmodule, die unter Tokencacheserialisierung beschrieben sind.Microsoft.Identity.Web comes with pre-built token-cache serializers described in Token cache serialization. Eine interessante Möglichkeit besteht darin, verteilte Arbeitsspeichercaches von ASP.NET Core auszuwählen:An interesting possibility is to choose ASP.NET Core distributed memory caches:

// Use a distributed token cache by adding:
    services.AddMicrosoftIdentityWebAppAuthentication(Configuration, "AzureAd")
            .EnableTokenAcquisitionToCallDownstreamApi(
                initialScopes: new string[] { "user.read" })
            .AddDistributedTokenCaches();

// Then, choose your implementation.
// For instance, the distributed in-memory cache (not cleared when you stop the app):
services.AddDistributedMemoryCache();

// Or a Redis cache:
services.AddStackExchangeRedisCache(options =>
{
 options.Configuration = "localhost";
 options.InstanceName = "SampleInstance";
});

// Or even a SQL Server token cache:
services.AddDistributedSqlServerCache(options =>
{
 options.ConnectionString = _config["DistCache_ConnectionString"];
 options.SchemaName = "dbo";
 options.TableName = "TestCache";
});

Ausführliche Informationen zu den Tokencacheanbietern finden Sie im Artikel Tokencacheserialisierung von Microsoft.Identity.Web sowie in den Tutorials zu ASP.NET Core-Web-Apps | Tokencaches in der entsprechenden Phase des Web-App-Tutorials.For details about the token-cache providers, see also Microsoft.Identity.Web's Token cache serialization article, as well as the ASP.NET Core Web app tutorials | Token caches phase of the web apps tutorial.

Nächste SchritteNext steps

Wenn sich der Benutzer anmeldet, wird zu diesem Zeitpunkt ein Token im Tokencache gespeichert.At this point, when the user signs in, a token is stored in the token cache. Sehen wir uns an, wie dieses dann in anderen Teilen der Web-App verwendet wird.Let's see how it's then used in other parts of the web app.

Entfernen von Konten aus dem Cache bei der globalen AbmeldungRemove accounts from the cache on global sign-out