Abrufen und Zwischenspeichern von Token mithilfe der Microsoft-Authentifizierungsbibliothek (Microsoft Authentication Library, MSAL)

  • Artikel

Zugriffstoken ermöglichen Clients das sichere Aufrufen von Web-APIs, die durch Azure geschützt sind. Es gibt verschiedene Möglichkeiten zum Abrufen von Token mithilfe der Microsoft-Authentifizierungsbibliothek (Microsoft Authentication Library, MSAL). Einige erfordern eine Benutzerinteraktion über einen Webbrowser, während bei anderen keine Benutzerinteraktionen erforderlich sind. Die Methode zum Anfordern eines Tokens ist in der Regel davon abhängig, ob es sich bei der Anwendung um eine öffentliche Clientanwendung (Desktopanwendung oder mobile App) oder um eine vertrauliche Clientanwendung (Web-App, Web-API oder Daemon-App) handelt.

Nachdem ein Token abgerufen wurde, wird es von MSAL zwischengespeichert. Ihr Anwendungscode sollte zunächst versuchen, ein Token ohne Eingriff aus dem Cache abzurufen, bevor andere Methoden angewandt werden.

Sie können den Inhalt des Tokencaches auch löschen, indem Sie die Konten aus dem Cache entfernen. Das Sitzungscookie im Browser wird dabei jedoch nicht entfernt.

Geltungsbereiche beim Abrufen von Token

Geltungsbereiche sind die Berechtigungen, die von einer Web-API verfügbar gemacht werden und auf die Clientanwendungen Zugriff anfordern können. Clientanwendungen fordern die Benutzereinwilligung für diese Geltungsbereiche an, wenn sie Authentifizierungsanforderungen zum Tokenabruf senden, um auf die Web-APIs zuzugreifen. Über MSAL können Sie Token für den Zugriff auf Microsoft Identity Platform-APIs abrufen. Das v2.0-Protokoll verwendet in den Anforderungen Geltungsbereiche anstelle von Ressourcen. Abhängig von der Web-API-Konfiguration der akzeptierten Tokenversion gibt der v2.0-Endpunkt das Zugriffstoken an MSAL zurück.

Einige der Tokenabrufmethoden von MSAL erfordern den Parameter scopes. Bei dem Parameter scopes handelt es sich um eine Liste von Zeichenfolgen, die die gewünschten Berechtigungen und die angeforderten Ressourcen deklarieren. Bekannte Geltungsbereiche sind die Microsoft Graph-Berechtigungen.

Anfordern von Bereichen für eine Web-API

Wenn Ihre Anwendung Token mit bestimmten Berechtigungen für eine Ressourcen-API anfordern muss, übergeben Sie die Geltungsbereiche mit dem App-ID-URI der API im Format <app ID URI>/<scope>.

Einige Beispielwerte für Geltungsbereiche für verschiedene Ressourcen:

  • Microsoft Graph-API: https://graph.microsoft.com/User.Read
  • Benutzerdefinierte Web-API: api://11111111-1111-1111-1111-111111111111/api.read

Das Format des Bereichswerts variiert abhängig von der Ressource (API), die das Zugriffstoken empfängt, und den aud-Anspruchswerten, die sie akzeptiert.

Nur für Microsoft Graph wird der Bereich user.readhttps://graph.microsoft.com/User.Read zugeordnet, und beide Bereichsformate können austauschbar verwendet werden.

Für bestimmte Web-APIs wie die Azure Resource Manager-API (https://management.core.windows.net/) wird ein nachstehender Vorwärtsschrägstrich (/) im Zielgruppenanspruch (aud) des Zugriffstokens erwartet. Übergeben Sie in diesem Fall den Bereich als https://management.core.windows.net//user_impersonation, einschließlich des doppelten Vorwärtsschrägstrichs (//).

Bei anderen APIs darf im Bereichswert möglicherweise kein Schema oder Host enthalten sind, und es werden nur die App-ID (GUID) und der Bereichsname erwartet, z. B.:

11111111-1111-1111-1111-111111111111/api.read

Tipp

Wenn sich die Downstreamressource nicht in Ihrer Kontrolle befindet, müssen Sie möglicherweise verschiedene Bereichswertformate ausprobieren (z. B. mit/ohne Schema und Host), wenn Sie beim Übergeben des Zugriffstokens an die Ressource 401 oder andere Fehler erhalten.

Wenn die von Ihrer Anwendung bereitgestellten Features oder ihre Anforderungen geändert werden, können Sie bei Bedarf mithilfe des Bereichsparameters zusätzliche Berechtigungen anfordern. Diese dynamischen Bereiche ermöglichen Ihren Benutzern, ihre inkrementelle Einwilligung für Bereiche anzugeben.

Beispielsweise können Sie den Benutzer anmelden, ihm anfänglich jedoch den Zugriff auf alle Ressourcen verweigern. Später können Sie ihm dann die Möglichkeit einräumen, seinen Kalender anzuzeigen, indem der Kalenderbereich in der Tokenabrufmethode angefordert und die Benutzereinwilligung eingeholt werden. Dies kann z. B. durch Anfordern der Bereiche https://graph.microsoft.com/User.Read und https://graph.microsoft.com/Calendar.Read erfolgen.

Automatisches Abrufen von Token (aus dem Cache)

MSAL verwaltet einen Tokencache (bzw. zwei Caches im Fall von vertraulichen Clientanwendungen) und speichert Token nach dem Abruf zwischen. Beim automatischen Tokenabruf wird in vielen Fällen ein weiteres Token mit weiteren Geltungsbereichen abgerufen, die auf einem Token im Cache basieren. Auch die Aktualisierung von Token, die demnächst ablaufen, ist möglich (da der Tokencache auch ein Aktualisierungstoken enthält).

Der Anwendungsquellcode sollte zunächst versuchen, ein Token unbemerkt aus dem Cache abzurufen. Wenn der Methodenaufruf einen Fehler oder eine Ausnahme vom Typ „UI erforderlich“ zurückgibt, sollten Sie andere Methoden für den Tokenabruf probieren.

Bei zwei Flows sollten Sie Token nicht automatisch abrufen:

  • Flow für Clientanmeldeinformationen, für den anstelle des Benutzertokencaches ein Anwendungstokencache verwendet wird. Bei dieser Methode wird der Anwendungstokencache überprüft, bevor eine Anforderung an den Sicherheitstokendienst (STS) gesendet wird.
  • Flow für Autorisierungscode in Web-Apps. In diesem Fall wird der von der Anwendung abgerufene Code eingelöst, indem der Benutzer angemeldet und seine Einwilligung für weitere Geltungsbereiche eingeholt wird. Da ein Code und nicht ein Konto als Parameter übergeben wird, sind bei dieser Methode keine Einblicke in den Cache vor dem Einlösen des Codes möglich, da hierbei der Dienst aufgerufen wird.

Für Webanwendungen, die den Autorisierungscodeflow „OpenID Connect“ verwenden, wird das folgende Muster in Controllern empfohlen:

  • Instanziieren einer vertraulichen Clientanwendung mit einem Tokencache unter Verwendung der benutzerdefinierten Serialisierung
  • Abrufen des Tokens mithilfe des Flows für Autorisierungscode

Abrufen von Token

Welche Methode zum Tokenabruf verwendet wird, hängt davon ab, ob es sich um eine öffentliche oder vertrauliche Clientanwendung handelt.

Öffentliche Clientanwendungen

In öffentlichen Clientanwendungen (Desktopanwendung oder mobile App) verfügen Sie über folgende Möglichkeiten:

  • Rufen Sie Token interaktiv ab, indem sich Benutzer über eine Benutzeroberfläche oder ein Popupfenster anmelden.
  • Rufen Sie Token für angemeldete Benutzer automatisch über die integrierte Windows-Authentifizierung (IWA/Kerberos) ab, wenn die Desktopanwendung auf einem Windows-Computer ausgeführt wird, der mit einer Domäne oder mit Azure verknüpft ist.
  • Rufen Sie Token in .NET Framework-Desktopclientanwendungen über Benutzernamen und Kennwort ab. Dies wird jedoch nicht empfohlen. Es wird davon abgeraten, Benutzernamen/Kennwörter in vertraulichen Clientanwendungen zu verwenden.
  • Rufen Sie Token in Anwendungen, die auf Geräten ohne Webbrowser ausgeführt werden, über den Gerätecodeflow ab. Der Benutzer erhält eine URL und einen Code, den er auf einem anderen Gerät in einen Webbrowser eingeben kann, um sich anzumelden. Microsoft Entra ID sendet daraufhin ein Token zurück an das browserlose Gerät.

Vertrauliche Clientanwendungen

Bei vertraulichen Clientanwendungen (Web-App, Web-API oder Daemon-App wie einem Windows-Dienst) können Sie Folgendes tun;

  • Token werden über den Flow für Clientanmeldeinformationenfür die Anwendung selbst und nicht für einen Benutzer angefordert. Diese Technik kann für Synchronisierungstools verwendet werden oder für Tools, die Benutzer allgemein und nicht als bestimmte Benutzer verarbeiten.
  • Der On-Behalf-Of-Flow (OBO) wird für eine Web-API verwendet, die eine API im Namen des Benutzers aufruft. Die Anwendung wird anhand von Clientanmeldeinformationen identifiziert, um ein Token basierend auf einer Benutzerassertion (z. B. SAML oder ein JWT-Token) abzurufen. Dieser Flow wird von Anwendungen verwendet, die für Dienst-zu-Dienst-Aufrufe auf Ressourcen eines bestimmten Benutzers zugreifen müssen. Token sollten auf Sitzungsbasis zwischengespeichert werden, nicht auf Benutzerbasis.
  • Token werden in Web-Apps über den Flow für Autorisierungscode abgerufen, nachdem sich der Benutzer über die URL für Autorisierungsanforderungen angemeldet hat. OpenID Connect-Anwendungen verwenden in der Regel diesen Mechanismus, der die Benutzeranmeldung über OpenID Connect sowie den Zugriff auf Web-APIs im Namen des Benutzers bzw. der Benutzerin zulässt. Token können auf Benutzer- oder Sitzungsbasis zwischengespeichert werden. Wenn Token auf Benutzerbasis zwischengespeichert werden, empfiehlt es sich, die Sitzungsdauer einzuschränken, damit Microsoft Entra ID den Status der Richtlinien für bedingten Zugriff häufig überprüfen kann.

Authentifizierungsergebnisse

Wenn Ihr Client ein Zugriffstoken anfordert, gibt Microsoft Entra ID auch ein Authentifizierungsergebnis zurück, das Metadaten zum Zugriffstoken enthält. Diese Informationen umfassen die Ablaufzeit eines Zugriffstokens und die Bereiche, für die es gilt. Die Daten ermöglichen Ihrer App das intelligente Zwischenspeichern von Zugriffstoken, ohne dass dabei das Zugriffstoken selbst analysiert werden muss. Folgende Informationen werden im Authentifizierungsergebnis verfügbar gemacht:

  • Das Zugriffstoken, über das die Web-API auf Ressourcen zugreifen kann. Diese Zeichenfolge ist meist ein Base64-codiertes JWT, dem Client sollten jedoch niemals Einblicke in das Zugriffstoken gewährt werden. Die Stabilität des Formats ist nicht garantiert, und das Format kann für die Ressource verschlüsselt werden. Programmcode, der vom Inhalt von Zugriffstoken auf dem Client abhängig ist, stellt eine der häufigsten Ursachen für Fehler und Brüche in der Clientlogik dar.
  • Das ID-Token für den Benutzer (ein JWT).
  • Das Ablaufdatum des Tokens, das das Datum/die Uhrzeit für den Ablauf des Tokens enthält.
  • Die Mandanten-ID enthält den Mandanten, in dem der Benutzer gefunden wurde. Bei Gastbenutzer*innen (Microsoft Entra B2B-Szenarien) entspricht die Mandanten-ID dem Gastmandanten, nicht dem eindeutigen Mandanten. Wenn das Token im Namen eines Benutzers gesendet wird, enthält das Authentifizierungsergebnis auch Informationen über diesen Benutzer. Bei Flows für vertrauliche Clients, in denen Token ohne Benutzer (für die Anwendung) angefordert werden, wird für diese Benutzerinformationen NULL zurückgegeben.
  • Die Geltungsbereiche, für die das Token ausgegeben wurde
  • Die eindeutige ID für den Benutzer

(Erweitert) Zugreifen auf die zwischengespeicherten Token des Benutzers in Hintergrund-Apps und Diensten

Sie können mit der Tokencacheimplementierung von MSAL Hintergrund-Apps, APIs und Diensten die Verwendung des Zugriffstokencaches ermöglichen, um bei Abwesenheit von Benutzern weiterhin in deren Auftrag zu agieren. Dies ist besonders nützlich, wenn die Hintergrund-Apps und Dienste im Auftrag des Benutzers weiterhin funktionieren müssen, nachdem der Benutzer die Front-End-Web-App beendet hat.

Heutzutage verwenden die meisten Hintergrundprozesse Anwendungsberechtigungen, wenn sie mit den Daten eines Benutzers arbeiten müssen, ohne dass dieser zum Authentifizieren oder erneuten Authentifizieren anwesend ist. Da Anwendungsberechtigungen häufig eine Zustimmung des Administrators erfordern, was eine Erhöhung von Berechtigungen erfordert, entstehen vermeidbare Reibungsverluste, wenn der Entwickler nicht beabsichtigte, eine Berechtigung abzurufen, die über die Berechtigung hinausgeht, in die der Benutzer ursprünglich für seine App eingewilligt hat.

Dieses Codebeispiel auf GitHub zeigt, wie Sie diese vermeidbaren Reibungsverluste vermeiden, indem Sie über Hintergrund-Apps auf den Tokencache von MSAL zugreifen:

Zugreifen auf den Tokencache des angemeldeten Benutzers über Hintergrund-Apps, APIs und Dienste

Siehe auch

Einige der von MSAL unterstützten Plattformen enthalten in der Dokumentation für die Bibliothek der Plattform zusätzliche Informationen zum Tokencache. Beispiel: