v2.0-Protokolle – SPAs unter Verwendung des impliziten Flusses

Mit dem v2.0-Endpunkt können Sie Benutzer sowohl mit persönlichen Konten als auch mit Geschäfts-, Schul- oder Unikonten von Microsoft bei Apps mit einer Seite anmelden. Bei einseitigen Apps und anderen JavaScript-Apps, die hauptsächlich im Browser ausgeführt werden, gibt es in Bezug auf die Authentifizierung einige interessante Herausforderungen:

  • Die Sicherheitsmerkmale dieser Apps unterscheiden sich grundlegend von herkömmlichen serverbasierten Webanwendungen.
  • Zahlreiche Autorisierungsserver und Identitätsanbieter unterstützen keine CORS-Anforderungen.
  • Umleitungen auf ganzseitige Browserseiten stören die Benutzererfahrung erheblich.

Bei diesen Anwendungen (wie etwa AngularJS, Ember.js, React.js usw.) unterstützt Azure AD den Fluss für die implizite OAuth 2.0-Gewährung. Der implizite Fluss wird in der OAuth 2.0-Spezifikation beschrieben. Der größte Vorteil besteht darin, dass die App Token aus Azure AD abrufen kann, ohne dass die Anmeldeinformationen für den Back-End-Server ausgetauscht werden müssen. Dadurch kann die App den Benutzer anmelden, die Sitzung aufrechterhalten und Token für andere Web-APIs abrufen. All dies geschieht innerhalb des Client-JavaScript-Codes. Bei der Verwendung des impliziten Flusses gibt es einige wichtige Sicherheitsaspekte zu beachten, insbesondere in Bezug auf Clients und Identitätsvortäuschung.

Wenn Sie mit dem impliziten Fluss und Azure AD Ihrer JavaScript-App eine Authentifizierungsmöglichkeit hinzufügen möchten, sollten Sie unsere Open Source-JavaScript-Bibliothek adal.jsverwenden. Hier finden Sie einige AngularJS-Tutorials für die ersten Schritte.

Wenn Sie jedoch in Ihrer einseitigen App keine Bibliothek verwenden und Protokollmeldungen selbst senden möchten, führen Sie die folgenden allgemeinen Schritte aus.

Hinweis

Nicht alle Szenarien und Funktionen von Azure Active Directory werden vom v2.0-Endpunkt unterstützt. Lesen Sie die Informationen zu den Einschränkungen des v2.0-Endpunkts, um zu bestimmen, ob Sie den v2.0-Endpunkt verwenden sollten.

Protokolldiagramm

Der vollständige implizite Anmeldevorgang sieht in etwa wie folgt aus. Die einzelnen Schritte werden unten im Detail beschrieben.

OpenId Connect-Verantwortlichkeitsbereiche

Senden der Anmeldeanforderung

Zur anfänglichen Anmeldung des Benutzers bei Ihrer App können Sie eine OpenID Connect-Autorisierungsanforderung senden und ein id_token vom v2.0-Endpunkt abrufen:

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token+token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid%20https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&response_mode=fragment
&state=12345
&nonce=678910
Tipp

Klicken Sie auf den Link unten, um diese Anforderung auszuführen. Nach der Anmeldung sollte der Browser mit einem id_token in der Adressleiste zu https://localhost/myapp/ umgeleitet werden. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

Parameter Beschreibung
Mandant 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 Grundlagen zu Protokollen.
client_id erforderlich Die Anwendungs-ID, die das Registrierungsportal (apps.dev.microsoft.com) Ihrer Anwendung zugewiesen hat.
response_type erforderlich Muss das id_token für die OpenID Connect-Anmeldung enthalten. Kann auch den Antworttyp token enthalten. Mithilfe von token kann Ihre App ein Zugriffstoken direkt vom Autorisierungsendpunkt abrufen, ohne dass eine zweite Anforderung an den Autorisierungsendpunkt erforderlich ist. Wenn Sie den Antworttyp token verwenden, muss der scope-Parameter einen Bereich enthalten, der angibt, für welche Ressource das Token ausgestellt wird.
redirect_uri empfohlen Der Umleitungs-URI der App, in dem Authentifizierungsantworten gesendet und von der App empfangen werden können. Er muss genau mit einer der Umleitungs-URIs übereinstimmen, die Sie im Portal registriert haben, mit dem Unterschied, dass er URL-codiert sein muss.
Bereich erforderlich Eine durch Leerzeichen getrennte Liste von Bereichen. Für OpenID Connect muss der Bereich openidenthalten sein, der auf der Zustimmungsbenutzeroberfläche die Anmeldeberechtigung ergibt. Schließen Sie gegebenenfalls auch die Bereiche email oder profile mit ein, um Zugriff auf zusätzliche Benutzerdaten zu erhalten. Sie können in diese Anforderung auch andere Bereiche aufnehmen, um die Zustimmung für verschiedene Ressourcen anzufordern.
response_mode empfohlen Gibt die Methode an, die zum Senden des resultierenden Tokens zurück an Ihre App verwendet werden soll. Muss für den impliziten Fluss fragment sein.
state empfohlen Ein in der Anforderung enthaltener Wert, der auch in der Antwort zurückgegeben wird. Es kann sich um eine Zeichenfolge mit jedem beliebigen Inhalt handeln. Ein zufällig generierter eindeutiger Wert wird normalerweise verwendet, um websiteübergreifende Anforderungsfälschungsangriffe zu verhindern. Der Status wird auch 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.
nonce erforderlich Ein Wert in der Anforderung, der von der App erzeugt wird und im resultierenden ID-Token als Anspruch enthalten sein wird. Die App kann diesen Wert dann überprüfen, um die Gefahr von Tokenwiedergabeangriffen zu vermindern. Der Wert ist in der Regel eine zufällige, eindeutige Zeichenfolge, die verwendet werden kann, um den Ursprung der Anforderung zu identifizieren.
Eingabeaufforderung optional Gibt den Typ der erforderlichen Benutzerinteraktion an. Zu diesem Zeitpunkt sind die einzigen gültigen Werte „login“, „none“ und „consent“. prompt=login zwingt den Benutzer, die Anmeldeinformationen bei dieser Anforderung einzugeben. Einmaliges Anmelden ist dadurch nicht möglich. prompt=none ist genau das Gegenteil: Dieser Wert stellt sicher, dass dem Benutzer keine interaktive Eingabeaufforderung angezeigt wird. Wenn die Anforderung nicht über einmaliges Anmelden im Hintergrund abgeschlossen werden kann, gibt der v2.0-Endpunkt einen Fehler zurück. prompt=consent löst nach der Anmeldung des Benutzers das OAuth-Zustimmungsdialogfeld aus, in dem der Benutzer aufgefordert wird, der App Berechtigungen zu gewähren.
login_hint optional Dieser Wert kann verwendet werden, um das Feld für den Benutzernamen oder die E-Mail-Adresse auf der Anmeldeseite vorab für den Benutzer auszufüllen, wenn dessen Benutzername im Vorfeld bekannt ist. Apps verwenden diesen Parameter häufig für die wiederholte Authentifizierung, nachdem sie den Benutzernamen aus einer vorherigen Anmeldung mithilfe des Anspruchs preferred_username extrahiert haben.
domain_hint optional Kann consumers oder organizations sein. Wenn dieser Parameter vorhanden ist, wird der E-Mail-basierte Ermittlungsvorgang übersprungen, den der Benutzer auf der v2.0-Anmeldeseite durchläuft, was die Benutzerfreundlichkeit verbessert. Apps verwenden diesen Parameter häufig für die wiederholte Authentifizierung, indem sie den Anspruch tid aus dem ID-Token extrahieren. Verwenden Sie domain_hint=consumers, wenn der Anspruch tid den Wert 9188040d-6c67-4c5b-b112-36a304b66dad hat. Verwenden Sie andernfalls domain_hint=organizations.

Zu diesem Zeitpunkt wird der Benutzer dazu aufgefordert, seine Anmeldeinformationen einzugeben und die Authentifizierung abzuschließen. Der V2.0-Endpunkt stellt auch sicher, dass der Benutzer den Berechtigungen zugestimmt hat, die im scope -Abfrageparameter angegeben sind. Wenn der Benutzer keiner Berechtigung zugestimmt hat, wird er dazu aufgefordert, den erforderlichen Berechtigungen zuzustimmen. Nähere Einzelheiten zu Berechtigungen, Zustimmung und mehrinstanzenfähigen Apps erhalten Sie hier.

Sobald der Benutzer authentifiziert ist und seine Zustimmung erteilt hat, gibt der v2.0-Endpunkt mithilfe der Methode im festgelegten response_mode-Parameter eine Antwort auf dem angegebenen redirect_uri an Ihre App zurück.

Erfolgreiche Antwort

Eine erfolgreiche Antwort mithilfe von response_mode=fragment und response_type=id_token+token sieht wie folgt aus, wobei die Zeilenumbrüche der Lesbarkeit dienen:

GET https://localhost/myapp/#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&token_type=Bearer
&expires_in=3599
&scope=https%3a%2f%2fgraph.microsoft.com%2fmail.read 
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
Parameter Beschreibung
access_token Ist enthalten, wenn token in response_type enthalten ist. Das von der Anwendung angeforderte Zugriffstoken, in diesem Fall für Microsoft Graph. Das Zugriffstoken sollte nicht decodiert oder anderweitig untersucht werden, es kann als nicht transparente Zeichenfolge behandelt werden.
token_type Ist enthalten, wenn token in response_type enthalten ist. Ist immer Bearer.
expires_in Ist enthalten, wenn token in response_type enthalten ist. Gibt für die Zwischenspeicherung den Gültigkeitszeitraum des Tokens in Sekunden an.
Bereich Ist enthalten, wenn token in response_type enthalten ist. Gibt die Bereiche an, für die das Zugriffstoken gültig ist.
id_token Das ID-Token, das die Anwendung angefordert hat. Sie können mit dem 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 für den v2.0-Endpunkttoken.
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.

Fehlerantwort

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

GET https://localhost/myapp/#
error=access_denied
&error_description=the+user+canceled+the+authentication
-Parameter enthalten. Beschreibung
Fehler 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 Entwickler die Hauptursache eines Authentifizierungsfehlers identifizieren können.

Überprüfen des ID-Tokens

Das Empfangen eines ID-Tokens allein reicht nicht aus, um den Benutzer zu authentifizieren. Sie müssen die Signatur des ID-Tokens validieren und die Ansprüche im Token gemäß der App-Anforderungen überprüfen. Der v2.0-Endpunkt verwendet JSON-Webtoken (JSTs) und die Verschlüsselung mit öffentlichem Schlüssel, um Token zu signieren und deren Gültigkeit zu überprüfen.

Sie können id_token auch im Clientcode überprüfen. Es ist jedoch eine bewährte Methode, id_token an einen Back-End-Server zu senden und die Überprüfung dort auszuführen. Nachdem Sie die Signatur des ID-Tokens validiert haben, müssen Sie noch einige Ansprüche überprüfen. Weitere Informationen finden Sie in der v2.0-Tokenreferenz. Dort finden Sie auch Einzelheiten zum Überprüfen von Token und wichtige Informationen zum Signaturschlüsselrollover (Überprüfen der Signatur). Wir empfehlen, zum Analysieren und Überprüfen von Token eine Bibliothek zu verwenden. Für die meisten Sprachen und Plattformen ist mindestens eine Bibliothek verfügbar.

Sie können je nach Szenario auch zusätzliche Ansprüche überprüfen. Einige allgemeinen Überprüfungen umfassen:

  • 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 Stärke der Authentifizierung aufgetreten ist, z.B. die mehrstufige Authentifizierung.

Weitere Informationen zu den Ansprüchen in einem ID-Token finden Sie in der Tokenreferenz zum v2.0-Endpunkt.

Nachdem Sie das ID-Token vollständig überprüft haben, können Sie mit dem Benutzer eine Sitzung beginnen und die Ansprüche im ID-Token zum Abrufen von Informationen über den Benutzer in der App verwenden. Diese Informationen kann für die Anzeige, für Datensätze, für die Autorisierung usw. verwendet werden.

Abrufen von Zugriffstoken

Nachdem Sie den Benutzer bei der einseitigen App angemeldet haben, können Sie Zugriffstoken zum Aufrufen der von Azure AD gesicherten Web-APIs abrufen, etwa Microsoft Graph. Auch wenn Sie mithilfe des Antworttyps token bereits ein Token erhalten haben, können Sie diese Methode zum Abrufen von Token für zusätzliche Ressourcen verwenden, ohne den Benutzer zur erneuten Anmeldung umzuleiten.

Im herkömmlichen OpenID Connect/OAuth-Fluss senden Sie dazu eine Anforderung an den v2.0-Endpunkt /token . Der v2.0-Endpunkt unterstützt jedoch keine CORS-Anforderungen, daher kommen AJAX-Aufrufe zum Abrufen und Aktualisieren von Token nicht infrage. Stattdessen können Sie den impliziten Fluss in einem ausgeblendeten IFrame verwenden, um neue Token für andere Web-APIs zu erhalten:

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read&response_mode=fragment
&state=12345&nonce=678910
&prompt=none
&domain_hint=organizations
&login_hint=myuser@mycompany.com
Tipp

Kopieren und fügen Sie die folgende Anforderung in eine Browserregisterkarte ein. (Vergessen Sie dabei nicht, die Werte domain_hint und login_hint durch die richtigen Werte für den entsprechenden Benutzer zu ersetzen.)

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=6731de76-14a6-49ae-97bc-6eba6914391e&response_type=token&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read&response_mode=fragment&state=12345&nonce=678910&prompt=none&domain_hint={{consumers-or-organizations}}&login_hint={{your-username}}
Parameter Beschreibung
Mandant 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 Grundlagen zu Protokollen.
client_id erforderlich Die Anwendungs-ID, die das Registrierungsportal (apps.dev.microsoft.com) Ihrer Anwendung zugewiesen hat.
response_type erforderlich Muss das id_token für die OpenID Connect-Anmeldung enthalten. Es können auch andere Antworttypen enthalten sein, z. B. code.
redirect_uri empfohlen Der Umleitungs-URI der App, in dem Authentifizierungsantworten gesendet und von der App empfangen werden können. Er muss genau mit einer der Umleitungs-URIs übereinstimmen, die Sie im Portal registriert haben, mit dem Unterschied, dass er URL-codiert sein muss.
Bereich erforderlich Eine durch Leerzeichen getrennte Liste von Bereichen. Beziehen Sie zum Abrufen von Token alle Bereiche ein, die für die entsprechende Ressource erforderlich sind.
response_mode empfohlen Gibt die Methode an, die zum Senden des resultierenden Tokens zurück an Ihre App verwendet werden soll. Kann query, form_post oder fragment sein.
state empfohlen Ein in der Anforderung enthaltener Wert, der auch in der Antwort zurückgegeben wird. Es kann sich um eine Zeichenfolge mit jedem beliebigen Inhalt handeln. Ein zufällig generierter eindeutiger Wert wird normalerweise verwendet, um websiteübergreifende Anforderungsfälschungsangriffe zu verhindern. Der Status wird auch 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.
nonce erforderlich Ein Wert in der Anforderung, der von der App erzeugt wird und im resultierenden ID-Token als Anspruch enthalten sein wird. Die App kann diesen Wert dann überprüfen, um die Gefahr von Tokenwiedergabeangriffen zu vermindern. Der Wert ist in der Regel eine zufällige, eindeutige Zeichenfolge, die verwendet werden kann, um den Ursprung der Anforderung zu identifizieren.
Eingabeaufforderung erforderlich Verwenden Sie prompt=none zum Aktualisieren und Abrufen von Token in einem ausgeblendeten IFrame, um sicherzustellen, dass das IFrame auf der V2.0-Anmeldeseite nicht hängt und direkt zurückgegeben wird.
login_hint erforderlich Beziehen Sie zum Aktualisieren und Abrufen von Token in einem ausgeblendete IFrame den Benutzernamen des Benutzers in diesem Hinweis mit ein, damit zwischen verschiedenen Sitzungen, die der Benutzer möglicherweise ausführt, unterschieden werden kann. Sie können den Benutzernamen aus einer vorherigen Anmeldung mithilfe des Anspruchs preferred_username extrahieren.
domain_hint erforderlich Kann consumers oder organizations sein. Schließen Sie zum Aktualisieren und Abrufen von Token in einem ausgeblendete IFrame „domain_hint“ in die Anforderung mit ein. Extrahieren Sie den Anspruch tid aus dem ID-Token einer früheren Anmeldung, um festzulegen, welcher Wert verwendet werden soll. Verwenden Sie domain_hint=consumers, wenn der Anspruch tid den Wert 9188040d-6c67-4c5b-b112-36a304b66dad hat. Verwenden Sie andernfalls domain_hint=organizations.

Dank des Parameters prompt=none ist diese Anforderung entweder erfolgreich oder sie schlägt direkt fehl und kehrt zu Ihrer Anwendung zurück. Eine erfolgreiche Antwort wird an Ihre App an den angegebenen Umleitungs-URI (redirect_uri) gesendet. Dabei wird die im Parameter response_mode angegebene Methode verwendet.

Erfolgreiche Antwort

Eine erfolgreiche Antwort mit response_mode=fragment sieht wie folgt aus:

GET https://localhost/myapp/#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
&token_type=Bearer
&expires_in=3599
&scope=https%3A%2F%2Fgraph.windows.net%2Fdirectory.read
-Parameter enthalten. Beschreibung
access_token Das von der App angeforderte Token
token_type Ist immer Bearer.
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.
expires_in Gibt an, wie lange das Zugriffstoken (in Sekunden) gültig ist.
Bereich Die Bereiche, für die das Zugriffstoken gültig ist.

Fehlerantwort

Fehlerantworten können auch an den redirect_uri gesendet werden, damit die App diese angemessen behandeln kann: Im Fall von prompt=none wird folgender Fehler erwartet:

GET https://localhost/myapp/#
error=user_authentication_required
&error_description=the+request+could+not+be+completed+silently
Parameter Beschreibung
Fehler 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 Entwickler die Hauptursache eines Authentifizierungsfehlers identifizieren können.

Wenn Sie diesen Fehler in der IFrame-Anforderung erhalten, muss sich der Benutzer erneut anmelden, um ein neues Token abzurufen. Diesen Fall können Sie so behandeln, wie es für Ihre Anwendung am sinnvollsten ist.

Aktualisieren von Token

id_tokens und access_tokens laufen nach kurzer Zeit ab. Ihre App muss daher diese Token in regelmäßigen Abständen aktualisieren. Zum Aktualisieren beider Tokentypen können Sie die oben erwähnte verborgene IFrame-Anforderung unter Verwendung des Parameters prompt=none ausführen, um das Verhalten von Azure AD zu steuern. Wenn Sie ein neues id_token erhalten möchten, verwenden Sie unbedingt response_type=id_token und scope=openid, sowie den Parameter nonce.

Senden einer Abmeldungsanforderung

Die OpenIdConnect end_session_endpoint ermöglicht Ihrer App das Senden einer Anforderung an den v2.0-Endpunkt zum Beenden der Sitzung eines Benutzers und zum Löschen von Cookies, die vom v2.0-Endpunkt festgelegt wurden. Um einen Benutzer vollständig von einer Webanwendung abzumelden, muss Ihre App ihre eigene Sitzung mit dem Benutzer beenden (in der Regel durch Löschen eines Tokencaches oder von Cookies) und dann den Browser zu folgender Adresse umleiten:

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/logout?post_logout_redirect_uri=https://localhost/myapp/
Parameter Beschreibung
Mandant 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 Grundlagen zu Protokollen.
post_logout_redirect_uri empfohlen Die URL, zu der der Benutzer nach erfolgreicher Abmeldung umgeleitet werden soll. Dieser Wert muss einem der Umleitung-URIs entsprechen, die für die Anwendung registriert sind. Wenn keine Angabe erfolgt, wird dem Benutzer vom v2.0-Endpunkt eine allgemeine Meldung angezeigt.