OpenID Connect auf Microsoft Identity Platform

OpenID Connect (OIDC) erweitert das Berechtigungsprotokoll OAuth 2.0 zur Verwendung als weiteres Authentifizierungsprotokoll. Mit OIDC können Sie einmaliges Anmelden (Single Sign-On, SSO) zwischen Ihren OAuth-fähigen Anwendungen ermöglichen, indem Sie ein sogenanntes ID-Token als Sicherheitstoken verwenden.

Die vollständige Spezifikation für OIDC ist auf der OpenID Foundation-Website unter OpenID Connect Core 1.0 Specification verfügbar.

Protokollflow: Anmelden

Im folgenden Diagramm wird der grundlegende OpenID Connect-Anmeldeflow dargestellt. Die Schritte im Flow werden in späteren Abschnitten des Artikels ausführlicher beschrieben.

Aktivieren von ID-Token

Das von OpenID Connect eingeführte ID-Token wird vom Autorisierungsserver (Microsoft Identity Platform) ausgestellt, wenn die Clientanwendung bei der Benutzerauthentifizierung ein Token anfordert. Mit dem ID-Token kann eine Clientanwendung die Identität des Benutzers überprüfen und weitere ihn betreffende Informationen (Ansprüche) abrufen.

ID-Token werden für eine Anwendung, die bei Microsoft Identity Platform registriert ist, nicht standardmäßig ausgestellt. ID-Token für eine Anwendung werden mithilfe einer der folgenden Methoden aktiviert:

1. Melden Sie sich beim Microsoft Entra Admin Center an.
2. Gehen Sie zu Identitäts>anwendungen>App- Registrierungen><Ihre Anwendung>>Authentifizierung.
3. Wählen Sie unter Plattformkonfigurationen die Option Plattform hinzufügen aus.
4. Wählen Sie im daraufhin geöffneten Bereich die entsprechende Plattform für Ihre Anwendung aus. Wählen Sie beispielsweise Web für eine Webanwendung aus.
5. Fügen Sie unter „Umleitungs-URIs“ den Umleitungs-URI Ihrer Anwendung hinzu. Beispiel: https://localhost:8080/.
6. Aktivieren Sie unter Implizite Genehmigung und Hybridflows das Kontrollkästchen ID-Token (für implizite und Hybridflows verwendet).

Oder:

1. Wählen Sie Identität>Anwendungen>App-Registrierungen><Anwendungsname>>Manifest aus.
2. Legen Sie oauth2AllowIdTokenImplicitFlow auf true im Anwendungsmanifest der App-Registrierung fest.

Wenn ID-Tokens für Ihre App nicht aktiviert sind und eines angefordert wird, gibt die Microsoft-Identitätsplattform einen unsupported_response-Fehler ähnlich dem folgenden zurück:

„Der angegebene Wert für den Eingabeparameter ‚response_type‘ ist für diesen Client nicht zulässig. Der erwartete Wert ist „code“.

Das Anfordern eines ID-Tokens durch Angeben von id_token als response_type wird unter Senden der Anmeldeanforderung weiter unten im Artikel erläutert.

Abrufen des OpenID-Konfigurationsdokuments

OpenID-Anbieter wie Microsoft Identity Platform stellen ein OpenID-Anbieter-Konfigurationsdokument, das die OIDC-Endpunkte des Anbieters, unterstützte Ansprüche und andere Metadaten enthält, an einem öffentlich zugänglichen Endpunkt bereit. Clientanwendungen können anhand der Metadaten die URLs für die Authentifizierung und die öffentlichen Signaturschlüssel des Authentifizierungsdiensts ermitteln.

Authentifizierungsbibliotheken sind die häufigsten Nutzer des OpenID-Konfigurationsdokuments, das sie zum Ermitteln von Authentifizierungs-URLs, den öffentlichen Signaturschlüsseln des Anbieters und anderen Dienstmetadaten verwenden. Wenn eine Authentifizierungsbibliothek in Ihrer App verwendet wird (empfohlen), brauchen Sie wahrscheinlich keine Anforderungen an den OpenID-Konfigurationsdokumentendpunkt und Antworten dieses Endpunkts manuell zu codieren.

Suchen nach den URIs für das OpenID-Konfigurationsdokument Ihrer App

Für jede App-Registrierung in Microsoft Entra ID wird ein öffentlich zugänglicher Endpunkt bereitgestellt, der das zugehörige OpenID-Konfigurationsdokument enthält. Um den URI des Endpunkts des Konfigurationsdokuments für Ihre App zu ermitteln, fügen Sie den bekannten OpenID-Konfigurationspfad an die Autoritäts-URL für die App-Registrierung an.

• Bekannter Konfigurationsdokumentpfad: /.well-known/openid-configuration
• Autoritäts-URL: https://login.microsoftonline.com/{tenant}/v2.0

Der Wert {tenant} variiert und hängt von der Anmeldezielgruppe der Anwendung ab, wie aus der folgenden Tabelle hervorgeht. Die Autoritäts-URL variiert ebenso je nach Cloudinstanz.

Wert	Beschreibung
common	Benutzer mit einem persönlichen Microsoft-Konto und einem Geschäfts-, Schul- oder Unikonto aus Microsoft Entra ID können sich bei der Anwendung anmelden.
organizations	Nur Benutzer mit Geschäfts-, Schul- oder Unikonten aus Microsoft Entra ID können sich bei der Anwendung anmelden.
consumers	Nur Benutzer mit einem persönlich Microsoft-Konto können sich bei der Anwendung anmelden.
Directory (tenant) ID oder contoso.onmicrosoft.com	Nur Benutzer eines bestimmten Microsoft Entra-Mandanten (Verzeichnismitglieder mit einem Geschäfts-, Schul- oder Unikonto oder Verzeichnisgäste mit einem persönlichen Microsoft-Konto) können sich bei der Anwendung anmelden. Der Domänenname des Microsoft Entra-Mandanten oder die Mandanten-ID im GUID-Format kann als Wert verwendet werden.

Tipp

Beachten Sie, dass bei Verwendung der Autorität common oder consumers für persönliche Microsoft-Konten die ressourcenverbrauchende Anwendung so konfiguriert werden muss, dass diese Art von Konten in Übereinstimmung mit signInAudience unterstützt wird.

Um das OIDC-Konfigurationsdokument im Microsoft Entra Admin Center zu finden, melden Sie sich beim Microsoft Entra Admin Center an und dann:

1. Gehen Sie zu Identitäts>anwendungen>App- Registrierungen><Ihre Anwendung>>Entpunkte.
2. Suchen Sie den URI unter OpenID Connect-Metadatendokument.

Beispiel für eine Anforderung

Mit der folgenden Anforderung werden die OpenID-Konfigurationsmetadaten vom OpenID-Konfigurationsdokumentendpunkt der gängigen Autorität (common) in der öffentlichen Azure-Cloud abgerufen:

GET /common/v2.0/.well-known/openid-configuration
Host: login.microsoftonline.com

Tipp

Testen Um das OpenID-Konfigurationsdokument für die gängige Autorität einer Anwendung (common authority) anzuzeigen, navigieren Sie zu https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration.

Beispiel für eine Antwort

Die Konfigurationsmetadaten werden im JSON-Format zurückgegeben, wie im folgenden Beispiel gezeigt (der Kürze halber abgeschnitten). Die in der JSON-Antwort zurückgegebenen Metadaten werden in der OpenID Connect 1.0-Nachschlagespezifikation ausführlich beschrieben.

{
  "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize",
  "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "private_key_jwt"
  ],
  "jwks_uri": "https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys",
  "userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo",
  "subject_types_supported": [
      "pairwise"
  ],
  ...
}

Senden der Anmeldeanforderung

Um einen Benutzer zu authentifizieren und ein ID-Token für die Verwendung in Ihrer Anwendung anzufordern, leiten Sie den entsprechenden Benutzer-Agent an den /authorize-Endpunkt von Microsoft Identity Platform weiter. Diese Anforderung ist dem ersten Abschnitt des OAuth 2.0-Autorisierungscodeflows vergleichbar, weist allerdings folgende Unterschiede auf:

• Nehmen Sie den Bereich openid in den Parameter scope auf.
• Geben Sie id_token im Parameter response_type an.
• Schließen Sie den Parameter nonce ein.

Beispiel für eine Anmeldeanforderung (wegen der besseren Lesbarkeit wurden Zeilenumbrüche hinzugefügt):

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=form_post
&scope=openid
&state=12345
&nonce=678910

Parameter	Condition	Beschreibung
tenant	Erforderlich	Mit dem {tenant}-Wert im Pfad der Anforderung kann festgelegt werden, welche Benutzer sich bei der Anwendung anmelden können. Zulässige Werte sind common, organizations, consumers und Mandantenbezeichner. Weitere Informationen finden Sie in den Protokollgrundlagen. Wichtig: In Gastszenarien, in denen Sie einen Benutzer aus einem Mandanten bei einem anderen Mandanten anmelden, müssen Sie die Mandanten-ID angeben, um ihn beim Ressourcenmandanten ordnungsgemäß anmelden zu können.
client_id	Erforderlich	Die Anwendungs-ID (Client-ID), die Ihrer App auf der Benutzeroberfläche „App-Registrierungen“ im Microsoft Entra Admin Center zugewiesen ist.
response_type	Erforderlich	Muss das id_token für die OpenID Connect-Anmeldung enthalten.
redirect_uri	Empfohlen	Der Umleitungs-URI der App, in dem Authentifizierungsantworten gesendet und von der App empfangen werden können. Er muss genau mit einem der Umleitungs-URIs übereinstimmen, den Sie im Portal registriert haben – mit dem Unterschied, dass er URL-codiert sein muss. Ist dies nicht der Fall, wählt der Endpunkt zufällig einen registrierten redirect_uri aus, an den er den Benutzer zurückschickt.
scope	Erforderlich	Eine durch Leerzeichen getrennte Liste von Bereichen. Für OpenID Connect muss der Bereich openid enthalten sein, der auf der Zustimmungsbenutzeroberfläche die Anmeldeberechtigung Anmelden überträgt. Sie können in diese Anforderung auch andere Bereiche für das Anfordern der Zustimmung aufnehmen.
nonce	Erforderlich	Ein Wert, der von Ihrer App generiert und in der Anforderung eines ID-Tokens gesendet wird. Derselbe Wert nonce ist im ID-Token enthalten, das von Microsoft Identity Platform an Ihre App zurückgegeben wird. Um das Risiko von Token-Replay-Angriffen zu minimieren, sollte Ihre App überprüfen, ob der Wert nonce im ID-Token dem Wert entspricht, der beim Anfordern des Tokens gesendet wurde. Der Wert ist in der Regel eine eindeutige zufällige Zeichenfolge.
response_mode	Empfohlen	Gibt die Methode an, die zum Senden des resultierenden Autorisierungscodes zurück an Ihre App verwendet werden soll. Kann form_post oder fragment sein. Bei Webanwendungen empfiehlt sich die Verwendung von response_mode=form_post, um eine möglichst sichere Tokenübertragung an die Anwendung zu gewährleisten.
state	Empfohlen	Ein in der Anforderung enthaltener Wert, der ebenfalls in der Tokenantwort zurückgegeben wird. Es kann sich um eine Zeichenfolge mit jedem beliebigen Inhalt handeln. Normalerweise wird ein zufällig generierter eindeutiger Wert verwendet, um websiteübergreifende Anforderungsfälschungsangriffe zu verhindern. Der Status wird außerdem verwendet, um Informationen über den Status des Benutzers in der App zu codieren, bevor die Authentifizierungsanforderung aufgetreten ist, z.B. Informationen zu der Seite oder Ansicht, die der Benutzer besucht hat.
prompt	Optional	Gibt den Typ der erforderlichen Benutzerinteraktion an. Die einzigen gültigen Werte sind gegenwärtig login, none, consent und select_account. Der Anspruch prompt=login zwingt den Benutzer, seine Anmeldeinformationen bei dieser Anforderung einzugeben. Einmaliges Anmelden ist dadurch nicht möglich. Der Parameter prompt=none ist das Gegenstück, und ihm sollte login_hint zugeordnet werden, um anzugeben, welcher Benutzer angemeldet werden muss. Diese Parameter stellen sicher, dass dem Benutzer überhaupt keine interaktive Eingabeaufforderung angezeigt wird. Wenn die Anforderung nicht über einmaliges Anmelden im Hintergrund abgeschlossen werden kann, gibt Microsoft Identity Platform einen Fehler zurück. Mögliche Ursachen: Kein angemeldeter Benutzer, der Benutzer im Hinweis ist nicht angemeldet, oder mehrere Benutzer sind angemeldet, es wurde aber kein Hinweis bereitgestellt. Der Anspruch prompt=consent löst das OAuth-Zustimmungsdialogfeld aus, sobald sich der Benutzer angemeldet hat. Das Dialogfeld fordert den Benutzer zum Erteilen von Berechtigungen für die App auf. Schließlich zeigt select_account dem Benutzer einen Kontoselektor an, der eine einmalige Abmeldung verhindert, dem Benutzer aber die Möglichkeit gibt, das Konto auszuwählen, mit dem er sich anmelden will, ohne dass er seine Anmeldedaten eingeben muss. Sie können weder login_hint noch select_account verwenden.
login_hint	Optional	Sie können diesen Parameter verwenden, um das Feld für den Benutzernamen und die E-Mail-Adresse auf der Anmeldeseite vorab für die Benutzerin oder den Benutzer auszufüllen, wenn der Benutzername im Vorfeld bekannt ist. Apps verwenden diesen Parameter oft während der erneuten Authentifizierung, nachdem sie den optionalen Anspruch login_hintbereits aus einer vorherigen Anmeldung extrahiert haben.
domain_hint	Optional	Der Bereich des Benutzers in einem Verbundverzeichnis. Mit diesem Parameter wird der E-Mail-basierte Ermittlungsvorgang übersprungen, den der Benutzer auf der Anmeldeseite durchläuft, was die Benutzerfreundlichkeit verbessert. Für Mandanten, die über ein lokales Verzeichnis wie z. B. AD FS verbunden sind, führt dies wegen der vorhandenen Anmeldesitzung häufig zu einer nahtlosen Anmeldung.

An dieser Stelle wird der Benutzer dazu aufgefordert, seine Anmeldeinformationen einzugeben und die Authentifizierung abzuschließen. Microsoft Identity Platform überprüft, ob der Benutzer den Berechtigungen zugestimmt hat, die im Abfrageparameter scope angegeben sind. Wenn der Benutzer keiner dieser Berechtigungen zugestimmt hat, wird er von Microsoft Identity Platform aufgefordert, den erforderlichen Berechtigungen zuzustimmen. Lesen Sie mehr über Berechtigungen, die Zustimmung und mehrinstanzenfähige Apps.

Sobald der Benutzer authentifiziert wurde und seine Zustimmung erteilt hat, gibt Microsoft Identity Platform mithilfe der im Parameter response_mode festgelegten Methode eine Antwort über den angegebenen Umleitungs-URI an Ihre App zurück.

Erfolgreiche Antwort

Bei Verwendung von response_mode=form_postsieht eine erfolgreiche Antwort in etwa wie folgt aus:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345

Parameter	BESCHREIBUNG
id_token	Das ID-Token, das die App angefordert hat. Sie können mit dem Parameter id_token die Identität des Benutzers überprüfen und eine Sitzung mit dem Benutzer beginnen. Weitere Informationen zu ID-Token und deren Inhalt finden Sie in der Referenz zu ID-Token.
state	Wenn ein Parameter state in der Anforderung enthalten ist, sollte der gleiche Wert in der Antwort angezeigt werden. Die Anwendung sollte überprüfen, ob die Statuswerte in der Anforderung und in der Antwort identisch sind.

Fehlerantwort

Fehlerantworten können auch an den Umleitungs-URI gesendet werden, damit die App diese behandeln kann, zum Beispiel:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

Parameter	BESCHREIBUNG
error	Eine Fehlercodezeichenfolge, die verwendet werden kann, um unterschiedliche Arten auftretender Fehler zu klassifizieren und um auf Fehler zu reagieren.
error_description	Eine spezifische Fehlermeldung, mit der Sie die Hauptursache eines Authentifizierungsfehlers identifizieren können.

Fehlercodes beim Autorisierungsendpunktfehler

Die folgende Tabelle beschreibt die Fehlercodes, die im Parameter error der Fehlerantwort zurückgegeben werden können:

Fehlercode	Beschreibung	Clientaktion
invalid_request	Protokollfehler, z. B. ein fehlender erforderlicher Parameter.	Korrigieren Sie die Anforderung, und senden Sie sie erneut. Dieser Entwicklungsfehler sollte bei den Anwendungstests auffallen und behoben werden.
unauthorized_client	Die Clientanwendung darf keinen Autorisierungscode anfordern.	Dieser Fehler kann auftreten, wenn die Clientanwendung nicht in Microsoft Entra ID registriert ist oder dem Microsoft Entra-Mandanten des Benutzers nicht hinzugefügt wurde. Die Anwendung kann den Benutzer zum Installieren der Anwendung und zum Hinzufügen zu Microsoft Entra ID auffordern.
access_denied	Der Ressourcenbesitzer hat die Zustimmung verweigert.	Die Clientanwendung kann den Benutzer benachrichtigen, dass sie ohne Zustimmung des Benutzers nicht fortfahren kann.
unsupported_response_type	Der Autorisierungsserver unterstützt den Antworttyp in der Anforderung nicht.	Korrigieren Sie die Anforderung, und senden Sie sie erneut. Dieser Entwicklungsfehler sollte bei den Anwendungstests auffallen und behoben werden.
server_error	Der Server hat einen unerwarteten Fehler erkannt.	Wiederholen Sie die Anforderung. Diese Fehler werden durch temporäre Bedingungen verursacht. Die Clientanwendung kann dem Benutzer erklären, dass ihre Antwort aufgrund eines temporären Fehlers verzögert ist.
temporarily_unavailable	Der Server ist vorübergehend überlastet und kann die Anforderung nicht verarbeiten.	Wiederholen Sie die Anforderung. Die Clientanwendung kann dem Benutzer erklären, dass ihre Antwort aufgrund einer temporären Bedingung verzögert ist.
invalid_resource	Die Zielressource ist ungültig, da sie entweder nicht vorhanden ist, von Microsoft Entra ID nicht gefunden werden kann oder nicht ordnungsgemäß konfiguriert ist.	Dieser Fehler gibt an, dass die Ressource (falls vorhanden) im Mandanten nicht konfiguriert wurde. Die Anwendung kann den Benutzer zum Installieren der Anwendung und zum Hinzufügen zu Microsoft Entra ID auffordern.

Überprüfen des ID-Tokens

Der Empfang eines ID-Tokens in Ihrer App reicht möglicherweise nicht immer aus, um den Benutzer vollständig zu authentifizieren. Sie müssen möglicherweise auch die Signatur des ID-Tokens validieren und die Ansprüche im Token gemäß den Anforderungen Ihrer App überprüfen. Wie bei allen OpenID-Anbietern sind auch die ID-Token von Microsoft Identity Platform JSON-Webtoken (JWTs), die mithilfe der Verschlüsselung mit öffentlichem Schlüssel signiert werden.

Web-Apps und Web-APIs, die ID-Token für die Autorisierung verwenden, müssen diese validieren, da derartige Anwendungen Zugriff auf Daten haben. Andere Anwendungstypen profitieren jedoch möglicherweise nicht von der ID-Tokenvalidierung. Native und einseitige Anwendungen (SPA) beispielsweise profitieren nur selten von der ID-Token-Validierung, da jede Entität mit physischem Zugriff auf das Gerät oder den Browser die Validierung potenziell umgehen kann.

Zwei Beispiele für eine Umgehung der Tokenvalidierung:

• Bereitstellen gefälschter Token oder Schlüssel durch Ändern des Netzwerkdatenverkehrs zum Gerät
• Debuggen der Anwendung und Umgehen der Validierungslogik bei der Programmausführung.

Wenn Sie ID-Token in Ihrer Anwendung validieren, empfehlen wir, diese Aufgabe nicht manuell auszuführen. Verwenden Sie stattdessen eine Tokenvalidierungsbibliothek, um Token zu analysieren und zu validieren. Tokenvalidierungsbibliotheken sind für die meisten Programmiersprachen, Frameworks und Plattformen verfügbar.

Was soll in einem ID-Token validiert werden?

Neben der Validierung der Signatur des ID-Tokens sollten Sie mehrere der enthaltenen Ansprüche validieren, wie in Validieren eines ID-Tokens beschrieben. Lesen Sie auch Wichtige Informationen zum Rollover von Signaturschlüsseln.

Es gibt auch noch mehrere andere Validierungen, die häufig verwendet werden und je nach Anwendungsszenario variieren. Dazu zählen:

• Sicherstellen, dass sich der Benutzer/die Organisation für die App angemeldet hat.
• Sicherstellen, dass der Benutzer über eine ordnungsgemäße Autorisierung und Berechtigungen verfügt.
• Sicherstellen, dass eine bestimmte Authentifizierungsmethode verwendet wird, z. B. die Multi-Faktor-Authentifizierung.

Nachdem Sie das ID-Token validiert haben, können Sie eine Sitzung mit dem Benutzer beginnen und die Informationen in den Tokenansprüchen für die App-Personalisierung, die Anzeige oder zum Speichern ihrer Daten verwenden.

Protokolldiagramm: Zugriffstokenbeschaffung

Viele Anwendungen müssen nicht nur einen Benutzer anmelden, sondern auch im Namen des Benutzers auf eine geschützte Ressource wie eine Web-API zugreifen. Bei diesem Szenario werden OpenID Connect (zum Abrufen eines ID-Tokens für die Authentifizierung des Benutzers) und OAuth 2.0 (zum Abrufen eines Zugriffstokens für eine geschützte Ressource) kombiniert.

Der vollständige OpenID Connect-Anmelde- und Tokenbeschaffungsflow ähnelt der Darstellung in diesem Diagramm:

Abrufen eines Zugriffstokens für den UserInfo-Endpunkt

Neben dem ID-Token werden auch die Informationen des authentifizierten Benutzers dem OIDC-UserInfo-Endpunkt zur Verfügung gestellt.

Um ein Zugriffstoken für den OIDC-UserInfo-Endpunkt abzurufen, ändern Sie die Anmeldeanforderung wie im Folgenden beschrieben:

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444        // Your app registration's Application (client) ID
&response_type=id_token%20token                       // Requests both an ID token and access token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F       // Your application's redirect URI (URL-encoded)
&response_mode=form_post                              // 'form_post' or 'fragment'
&scope=openid+profile+email                           // 'openid' is required; 'profile' and 'email' provide information in the UserInfo endpoint as they do in an ID token. 
&state=12345                                          // Any value - provided by your app
&nonce=678910                                         // Any value - provided by your app

Anstelle von response_type=token können Sie den Autorisierungscodeflow, den Gerätecodeflow oder ein Aktualisierungstoken verwenden, um ein Zugriffstoken für Ihre App abzurufen.

Erfolgreiche Tokenantwort

Eine erfolgreiche Antwort bei Verwendung von response_mode=form_post:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
 access_token=eyJ0eXAiOiJKV1QiLCJub25jZSI6I....
 &token_type=Bearer
 &expires_in=3598
 &scope=email+openid+profile
 &id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI....
 &state=12345

Unabhängig vom Datenfluss beim Abrufen haben Antwortparameter immer die gleiche Bedeutung.

Parameter	Beschreibung
access_token	Das Token, das für den Aufruf des UserInfo-Endpunkts verwendet wird.
token_type	Immer „Bearer“
expires_in	Gibt die Dauer bis zum Ablauf des Zugriffstokens an (in Sekunden).
scope	Die Berechtigungen, die für das Zugriffstoken gewährt wurden. Da der UserInfo-Endpunkt in Microsoft Graph gehostet wird, enthält scope möglicherweise andere Berechtigungen, die der Anwendung zuvor gewährt wurden (z. B. User.Read).
id_token	Das ID-Token, das die App angefordert hat. Sie können mit dem ID-Token die Identität des Benutzers überprüfen und eine Sitzung mit dem Benutzer beginnen. Weitere Details zu ID-Token und deren Inhalt finden Sie in der Referenz zu ID-Token.
state	Wenn ein Statusparameter in der Anforderung enthalten ist, sollte der gleiche Wert in der Antwort angezeigt werden. Die Anwendung sollte überprüfen, ob die Statuswerte in der Anforderung und in der Antwort identisch sind.

Warnung

Versuchen Sie nicht, Token für eine API zu überprüfen oder zu lesen, die Sie nicht besitzen, einschließlich der Token in Ihrem Code in diesem Beispiel. Token für Microsoft-Dienste können ein spezielles Format verwenden, das nicht als JWT überprüft und auch für Consumerbenutzer (Microsoft-Konto) verschlüsselt werden kann. Das Lesen von Token ist zwar ein nützliches Debug- und Lerntool, aber integrieren Sie weder Abhängigkeiten davon in Ihren Code noch setzen Sie Einzelheiten über Token voraus, die nicht für eine von Ihnen kontrollierte API gelten.

Fehlerantwort

Fehlerantworten können auch an den Umleitungs-URI gesendet werden, damit die App diese angemessen behandeln kann:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

Parameter	BESCHREIBUNG
error	Eine Fehlercodezeichenfolge, die verwendet werden kann, um unterschiedliche Arten auftretender Fehler zu klassifizieren und um auf Fehler zu reagieren.
error_description	Eine spezifische Fehlermeldung, mit der Sie die Hauptursache eines Authentifizierungsfehlers identifizieren können.

Eine Beschreibung der möglichen Fehlercodes und der jeweils empfohlenen Clientantwort finden Sie unter Fehlercodes beim Autorisierungsendpunktfehler.

Nachdem Sie einen Autorisierungscode und ein ID-Token erhalten haben, können Sie den Benutzer anmelden und Zugriffstoken in seinem Namen abrufen. Um den Benutzer anzumelden, müssen Sie, wie beschrieben, das ID-Token wie unter Überprüfen von Token überprüfen. Führen Sie zum Abrufen von Zugriffstoken die in der Dokumentation zum OAuth-Codefluss beschriebenen Schritte aus.

Aufrufen des UserInfo-Endpunkts

Die UserInfo-Dokumentation enthält Informationen dazu, wie der UserInfo-Endpunkt mit diesem Token aufgerufen wird.

Senden einer Abmeldeanforderung

Führen Sie die beiden folgenden Vorgänge aus, um eine Benutzerin oder einen Benutzer abzumelden:

1. Umleiten des Benutzer-Agents der Benutzerin oder des Benutzers an den Abmelde-URI von Microsoft Identity Platform
2. Löschen Sie die Cookies Ihrer App, oder beenden Sie die Benutzersitzung in Ihrer Anwendung.

Wenn Sie keinen dieser Vorgänge ausführen können, bleibt die Benutzerin oder der Benutzer möglicherweise authentifiziert und wird beim nächsten Verwenden Ihrer App nicht aufgefordert, sich anzumelden.

Leiten Sie den Benutzer-Agent, wie im OpenID Connect-Konfigurationsdokument dargestellt, an den end_session_endpoint um. Der end_session_endpoint unterstützt sowohl HTTP GET- als auch POST-Anforderungen.

GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F

Parameter	Condition	BESCHREIBUNG
post_logout_redirect_uri	Empfohlen	Die URL, an die der Benutzer nach erfolgreicher Abmeldung umgeleitet wird. Wenn der Parameter nicht enthalten ist, wird dem Benutzer eine generische Meldung angezeigt, die von Microsoft Identity Platform generiert wird. Diese URL muss mit einem der Umleitungs-URIs übereinstimmen, die im App-Registrierungsportal für Ihre Anwendung registriert wurden.
logout_hint	Optional	Ermöglicht die Abmeldung, ohne dass der Benutzer aufgefordert wird, ein Konto auszuwählen. Um logout_hint zu verwenden, aktivieren Sie in Ihrer Clientanwendung den optionalen Anspruch login_hint und verwenden den Wert login_hint des optionalen Anspruchs als logout_hint-Parameter. Verwenden Sie keine Benutzerprinzipalnamen oder Telefonnummern als Wert für den Parameter logout_hint.

Hinweis

Nach erfolgreicher Abmeldung werden die aktiven Sitzungen auf inaktiv festgelegt. Wenn ein gültiges Primary Refresh Token (PRT) für den abgemeldeten Benutzer existiert und eine neue Anmeldung durchgeführt wird, wird die einmalige Abmeldung unterbrochen und der Benutzer sieht eine Eingabeaufforderung mit einem Kontopicker. Wenn es sich bei der ausgewählten Option um das verbundene Konto handelt, das auf das PRT verweist, wird die Anmeldung automatisch fortgesetzt, ohne dass neue Anmeldeinformationen eingefügt werden müssen.

Einmaliges Abmelden

Wenn Sie den Benutzer in einer Anwendung auf end_session_endpoint umleiten, beendet die Microsoft Identitätsplattform die Benutzersitzung für diese Anwendung. Der Benutzer kann jedoch weiterhin bei anderen Anwendungen angemeldet sein, die dieselben Microsoft-Konten zur Authentifizierung verwenden.

Wenn sich ein Benutzender bei mehreren in diesem Verzeichnis registrierten Web- oder SPA-Anwendungen angemeldet hat (auch als Mandant bezeichnet), ermöglicht Single Sign-Out diesem Benutzenden die sofortige Abmeldung aus allen Anwendungen, indem er sich in einer der Anwendungen abmeldet.

Um eine einmalige Abmeldung für Ihre Entra-Anwendung zu ermöglichen, sollten Sie die OpenID Connect Front Channel Logout-Funktion verwenden. Mit dieser Funktion kann eine Anwendung andere Anwendungen benachrichtigen, dass der Benutzende sich abgemeldet hat. Wenn sich der Benutzende bei einer Anwendung abmeldet, sendet die Microsoft-Identitätsplattform eine HTTP-GET-Anforderung an die Front-Channel-Logout-URL jeder Anwendung, bei der der Benutzende momentan angemeldet ist.

Diese Anwendungen müssen auf diese Anforderung reagieren, indem die folgenden beiden Aktionen ausgeführt werden, damit die einmalige Abmeldung erfolgreich ist:

1. Löschen Sie jede Sitzung, die den Benutzenden identifiziert.
2. Anwendungen müssen auf diese Anforderung antworten, indem sie alle Sitzungen löschen, mit denen der Benutzer identifiziert wird, und eine 200-Antwort zurückgeben.

Was ist eine URL für Front-Channel-Abmeldung?

Eine Front-Channel-Logout-URL ist der Ort, an dem Ihre Web- oder SPA-Anwendung die Abmeldeanforderung vom Entra-Authentifizierungsserver empfängt und die Single-Sign-Out-Funktion ausführt. Jede Anwendung verfügt über eine URL für Front-Channel-Abmeldung.

Wann sollten Sie eine URL für Front-Channel-Abmeldung festlegen?

Wenn Sie oder Ihr Entwicklender festgestellt hat, dass die einmalige Abmeldung für eine Anwendung erforderlich ist, müssen Sie die Abmelde-URL des Front-Channels für die App-Registrierung dieser Anwendung festlegen. Sobald die Front-Channel-Logout-URL für die App-Registrierung dieser Anwendung festgelegt ist, sendet die Microsoft-Identitätsplattform eine HTTP-GET-Anforderung an die Front-Channel-Logout-URL dieser Anwendung, wenn sich der angemeldete Benutzende bei einer anderen Anwendung abgemeldet hat.

So richten Sie einmaliges Abmelden mithilfe der Front-Channel-Abmeldefunktion ein

Um das Feature zum Abmelden des Front-Channels für eine Reihe von Anwendungen zu verwenden, müssen Sie die folgenden beiden Aufgaben ausführen:

• Legen Sie die Abmelde-URL des Front-Channels im Microsoft Entra Admin Center für alle Anwendungen fest, die gleichzeitig abgemeldet werden sollen. Jede Anwendung hat in der Regel eine eigene Abmelde-URL für den Front-Channel.
• Bearbeiten Sie den Code der Anwendungen so, dass sie auf eine HTTP-GET-Anforderung warten, die von der Microsoft-Identitätsplattform an die Front-Channel-Abmelde-URL gesendet wird, und auf diese Anforderung reagieren, indem sie alle Sitzungen löschen, die den Benutzenden identifizieren, und eine 200-Antwort zurückgeben.

So wählen Sie eine Front-Channel-Abmelde-URL aus

Die Front-Channel-Abmelde-URL sollte eine URL sein, die HTTP-GET-Anfragen empfangen und beantworten kann und in der Lage ist, jede Sitzung zu reinigen, die den Benutzenden identifiziert. Beispiele für eine Front-Channel-Logout-URL könnten sein, sind aber nicht beschränkt auf die folgenden:

• https://example.com/frontchannel_loout
• https://example.com/signout
• https://example.com/logout

Nächste Schritte

• Lesen Sie die Dokumentation zum UserInfo-Endpunkt.
• Verwenden von Daten aus lokalen Systemen als Anspruchswerte in einem Token.
• Aufnehmen eigener Ansprüche in Token.