Web-App, die Web-APIs aufruft: Codekonfiguration

Wie im Szenario Web-App, die Benutzer anmeldet gezeigt, verwendet die Web-App den OAuth 2.0-Autorisierungscodeflow, um den Benutzer anzumelden. Dieser Flow besteht aus zwei Schritten:

  1. Anfordern eines Autorisierungscodes. Dieser Teil delegiert einen privaten Dialog mit dem Benutzer an Microsoft Identity Platform. Während des Dialogs meldet sich der Benutzer an und stimmt der Verwendung von Web-APIs zu. Wenn dieser private Dialog erfolgreich beendet wird, erhält die Web-App einen Autorisierungscode an ihren Umleitungs-URI.
  2. Anfordern eines Zugriffstokens für die API durch Einlösen des Autorisierungscodes.

In den Szenarien Web-App, die Benutzer anmeldet wurde nur der erste Schritt behandelt. Hier erfahren Sie, wie Sie Ihre Web-App so ändern, dass sie nicht nur Benutzer anmeldet, sondern auch Web-APIs aufruft.

Microsoft-Bibliotheken, die Web-Apps unterstützen

Die folgenden Microsoft-Bibliotheken unterstützen Web-Apps:

Programmiersprache/Framework Projekt auf
GitHub
Paket Erste Schritte
gestartet
Anmelden von Benutzern Zugriff auf Web-APIs Allgemein verfügbar (Generally Available, GA) oder
Öffentliche Vorschau1
.NET MSAL.NET Microsoft.Identity.Client Bibliothek kann keine ID-Token für die Benutzeranmeldung anfordern Bibliothek kann Zugriffstoken für geschützte Web-APIs anfordern Allgemein verfügbar
.NET Microsoft.IdentityModel Microsoft.IdentityModel Library cannot request ID tokens for user sign-in.2 Library cannot request access tokens for protected web APIs.2 Allgemein verfügbar
ASP.NET Core ASP.NET Core Microsoft.AspNetCore.Authentication Schnellstart Bibliothek kann ID-Token für die Benutzeranmeldung anfordern Bibliothek kann keine Zugriffstoken für geschützte Web-APIs anfordern Allgemein verfügbar
ASP.NET Core Microsoft.Identity.Web Microsoft.Identity.Web Schnellstart Bibliothek kann ID-Token für die Benutzeranmeldung anfordern Bibliothek kann Zugriffstoken für geschützte Web-APIs anfordern Allgemein verfügbar
Java MSAL4J msal4j Schnellstart Bibliothek kann ID-Token für die Benutzeranmeldung anfordern Bibliothek kann Zugriffstoken für geschützte Web-APIs anfordern Allgemein verfügbar
Spring spring-cloud-azure-starter-active-directory spring-cloud-azure-starter-active-directory Tutorial Bibliothek kann ID-Token für die Benutzeranmeldung anfordern Bibliothek kann Zugriffstoken für geschützte Web-APIs anfordern Allgemein verfügbar
Node.js MSAL Node msal-node Schnellstart Bibliothek kann ID-Token für die Benutzeranmeldung anfordern Bibliothek kann Zugriffstoken für geschützte Web-APIs anfordern Allgemein verfügbar
Python MSAL Python msal Schnellstart Bibliothek kann ID-Token für die Benutzeranmeldung anfordern Bibliothek kann Zugriffstoken für geschützte Web-APIs anfordern Allgemein verfügbar

1 Für Bibliotheken in der öffentlichen Vorschau gelten ergänzende Nutzungsbedingungen für Microsoft Azure-Vorschauversionen.

2 Die Bibliothek Microsoft.IdentityModelüberprüft nur Token. Sie kann keine ID- oder Zugriffstoken anfordern.

Wählen Sie die Registerkarte für die Plattform aus, die Sie interessiert:

Geheime Clientschlüssel oder Clientzertifikate

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. Sie können auch einen Abschnitt hinzufügen, in dem Folgendes angegeben wird:

  • Die URL der Downstream-Web-API
  • Die zum Aufrufen der API erforderlichen Bereiche

Im folgenden Beispiel sind diese Einstellungen im Abschnitt GraphBeta angegeben.

{
  "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. Im folgenden Codeausschnitt ist die Verwendung eines in Azure Key Vault gespeicherten Zertifikats dargestellt.

{
  "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. Weitere Informationen finden Sie unter Microsoft.Identity.Web: Verwenden von Zertifikaten auf GitHub.

Startup.cs

Ihre Web-App muss ein Token für die Downstream-API abrufen. Die Angabe erfolgt durch Hinzufügen der Zeile .EnableTokenAcquisitionToCallDownstreamApi() nach .AddMicrosoftIdentityWebApp(Configuration). Diese Zeile macht den ITokenAcquisition-Dienst verfügbar, den Sie in Ihren Controller- und Seitenaktionen verwenden können. Wie jedoch aus den folgenden beiden Optionen hervorgeht, kann es einfacher gemacht werden. Sie müssen auch eine Tokencacheimplementierung (z. B. .AddInMemoryTokenCaches()) in Startup.cs auswählen:

using Microsoft.Identity.Web;

public class Startup
{
  // ...
  public void ConfigureServices(IServiceCollection services)
  {
  // ...
  services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
          .AddMicrosoftIdentityWebApp(Configuration, "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. Wenn Sie die Bereiche nicht angeben, aktiviert Microsoft.Identity.Web einen inkrementellen Zustimmungsprozess.

Wenn Sie das Token nicht selbst abrufen möchten, bietet Microsoft.Identity.Web zwei Mechanismen zum Aufrufen einer Web-API über eine Web-App. Welche Option Sie auswählen, hängt davon ab, ob Sie Microsoft Graph oder eine andere API aufrufen möchten.

Option 1: Aufrufen von 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. Gehen Sie wie folgt vor, um Microsoft Graph verfügbar zu machen:

  1. Fügen Sie Ihrem Projekt das NuGet-Paket Microsoft.Identity.Web.MicrosoftGraph hinzu.

  2. Fügen Sie in der Datei Startup.cs nach .EnableTokenAcquisitionToCallDownstreamApi() den Eintrag .AddMicrosoftGraph() hinzu. .AddMicrosoftGraph() verfügt über mehrere Überschreibungen. Wenn Sie die Überschreibung verwenden, die einen Konfigurationsabschnitt als Parameter annimmt, sieht der Code wie folgt aus:

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

Option 2: Aufrufen einer anderen Downstream-Web-API als 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.

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

Zusammenfassung

Wie bei Web-APIs können Sie verschiedene Tokencacheimplementierungen auswählen. Weitere Informationen finden Sie unter Microsoft.Identity.Web: Tokencacheserialisierung auf GitHub.

In der folgenden Abbildung sind die verschiedenen Möglichkeiten von Microsoft.Identity.Web und die Auswirkungen auf die Datei Startup.cs dargestellt:

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.

Code, der den Autorisierungscode einlöst

Microsoft.Identity.Web vereinfacht Ihren Code, indem es die richtigen OpenID-Verbindungseinstellungen festlegt, das Ereignis „Code erhalten“ abonniert und den Code einlöst. Zum Einlösen des Autorisierungscodes ist kein weiterer Code erforderlich. Ausführliche Informationen zur Funktionsweise finden Sie im Microsoft.Identity.Web-Quellcode.

Die vertrauliche Clientanwendung kann ihre Identität statt mit einem geheimen Clientschlüssel auch mithilfe eines Clientzertifikats oder einer Clientassertion nachweisen. Die Verwendung von Clientassertionen ist ein erweitertes Szenario, das unter Clientassertionen detailliert beschrieben ist.

Tokencache

Wichtig

Die Tokencache-Implementierung für Web-Apps oder Web-APIs unterscheidet sich von der Implementierung für Desktopanwendungen, die häufig dateibasiert ist. Aus Sicherheits- und Leistungsgründen ist es wichtig, sicherzustellen, dass es für Web-Apps und Web-APIs ein Tokencache pro Benutzerkonto gibt. Sie müssen den Tokencache für jedes Konto serialisieren.

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. Microsoft.Identity.Web enthält eine Reihe vordefinierter Tokencache-Serialisierungsmodule, die unter Tokencacheserialisierung beschrieben sind. Eine interessante Möglichkeit besteht darin, verteilte Arbeitsspeichercaches von ASP.NET Core auszuwählen:

// 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.

Nächste Schritte

Wenn sich der Benutzer anmeldet, wird zu diesem Zeitpunkt ein Token im Tokencache gespeichert. Sehen wir uns an, wie dieses dann in anderen Teilen der Web-App verwendet wird.

Entfernen von Konten aus dem Cache bei der globalen Abmeldung