Freigeben über

OpenID Connect auf Microsoft Identity Platform

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

Die vollständige Spezifikation für OIDC ist auf der OpenID Foundation-Website unter OpenID Connect Core 1.0 Spezifikation 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.

Verantwortlichkeitsspurdiagramm mit dem Anmeldefluss des OpenID Connect-Protokolls.

Aktivieren von ID-Token

Das von OpenID Connect eingeführte ID-Token wird vom Autorisierungsserver, der Microsoft Identity Platform, ausgegeben, wenn die Clientanwendung eine während der Benutzerauthentifizierung 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. Navigieren Sie zu EntraID-App-Registrierungen>><Ihrer Anwendungsauthentifizierung>>.
  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 z. B. "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 Gewährung" und "Hybridflüsse" das Kontrollkästchen "ID-Token" (verwendet für implizite und Hybridflüsse).

Oder:

  1. Wählen Sie Entra>><aus, die Ihr Anwendungsmanifest>>besitzen.
  2. oauth2AllowIdTokenImplicitFlow Im true der App-Registrierung festgelegt.

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

Anfordern eines ID-Tokens durch Angeben einer response_type von id_token wird in "Senden der Anmeldeanforderung" weiter unten im Artikel erläutert.

Abrufen des OpenID-Konfigurationsdokuments

OpenID-Anbieter wie die Microsoft Identity Platform stellen ein OpenID-Anbieterkonfigurationsdokument an einem öffentlich zugänglichen Endpunkt bereit, der die OIDC-Endpunkte des Anbieters, unterstützte Ansprüche und andere Metadaten enthält. 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 der 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 auch 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 die Ressourcenanwendung für die Verwendung oder commonconsumers Autorität für persönliche Microsoft-Konten so konfiguriert werden muss, dass diese Art von Konten gemäß 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. Navigieren Sie zu Entra ID>><Ihrer Anwendung>>Endpunkte.
  2. Suchen Sie den URI unter dem 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-Ermittlungsspezifikation 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 dessen Benutzer-Agent an den /authorize-Endpunkt der Microsoft Identity Platform weiter. Die Anforderung ähnelt dem ersten Schritt des OAuth 2.0-Autorisierungscodeflusses , aber mit diesen Unterschieden:

  • 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 Zustand 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 unter Protokollgrundlagen. Bei Gastszenarien, in denen Sie einen Benutzer von einem Mandanten in einen anderen Mandanten signieren, müssen Sie die Mandanten-ID angeben, um sie ordnungsgemäß beim Ressourcenmandanten anzumelden.
client_id Erforderlich Die Anwendungs-ID (Client) des Microsoft Entra Admin Centers – App-Registrierungen , die Ihrer App zugewiesen wurden.
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 er den Bereich openidenthalten, der in die Berechtigung " Anmelden " in der Zustimmungs-UI übersetzt wird. 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. Ein zufällig generierter eindeutiger Wert wird in der Regel verwendet, um Site-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 Wahlfrei 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 Wahlfrei 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 login_hintbereits aus einer vorherigen Anmeldung extrahiert haben.
domain_hint Wahlfrei 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. Weitere Informationen zu Berechtigungen, Zustimmung und Mehrinstanzen-Apps finden Sie hier.

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 Inhalten finden Sie in der ID-Tokenreferenz.
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 alle OpenID-Anbieter sind die ID-Token der Microsoft Identity Platform JSON-Webtoken (JWTs), die mithilfe der Kryptografie mit öffentlichem Schlüssel signiert sind.

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 überprüfen, wird empfohlen, dies nicht manuell durchzufü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?

Zusätzlich zur Überprüfung der Signatur des ID-Tokens sollten Sie mehrere seiner Ansprüche überprüfen, wie in der Überprüfung eines ID-Tokens beschrieben. Weitere Informationen zum Signieren von Schlüsselrollover finden Sie auch unter "Wichtige Informationen".

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 einer bestimmten Authentifizierungsstärke, z. B. mehrstufige 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:

OpenID Connect-Protokoll: Tokenerwerb

Abrufen eines Zugriffstokens für den UserInfo-Endpunkt

Zusätzlich zum ID-Token werden auch die Informationen des authentifizierten Benutzers am OIDC UserInfo-Endpunkt verfügbar gemacht.

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

Sie können den Autorisierungscodefluss, den Gerätecodefluss oder ein Aktualisierungstoken anstelle eines response_type=token Zugriffstokens für Ihre App verwenden.

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 Inhalten finden Sie in der ID-Tokenreferenz.
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 möglicher Fehlercodes und empfohlener Clientantworten finden Sie unter Fehlercodes für 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 das ID-Token überprüfen, wie in den Überprüfungstoken beschrieben. Führen Sie zum Abrufen von Zugriffstoken die in der OAuth-Codeflussdokumentation beschriebenen Schritte aus.

Aufrufen des UserInfo-Endpunkts

Lesen Sie die UserInfo-Dokumentation , um zu erfahren, wie Sie den UserInfo-Endpunkt mit diesem Token aufrufen.

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 Zustand 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 Wahlfrei 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 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 Anmelde-URL für den Frontkanal 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_logout
  • https://example.com/signout
  • https://example.com/logout

Nächste Schritte