v2.0-Protokolle – SPAs unter Verwendung des impliziten Flussesv2.0 Protocols - SPAs using the implicit flow

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.With the v2.0 endpoint, you can sign users into your single page apps with both personal and work/school accounts from Microsoft. 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:Single page and other JavaScript apps that run primarily in a browser face a few interesting challenges when it comes to authentication:

  • Die Sicherheitsmerkmale dieser Apps unterscheiden sich grundlegend von herkömmlichen serverbasierten Webanwendungen.The security characteristics of these apps are significantly different from traditional server based web applications.
  • Zahlreiche Autorisierungsserver und Identitätsanbieter unterstützen keine CORS-Anforderungen.Many authorization servers & identity providers do not support CORS requests.
  • Umleitungen auf ganzseitige Browserseiten stören die Benutzererfahrung erheblich.Full page browser redirects away from the app become particularly invasive to the user experience.

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.For these applications (think: AngularJS, Ember.js, React.js, etc) Azure AD supports the OAuth 2.0 Implicit Grant flow. Der implizite Fluss wird in der OAuth 2.0-Spezifikation beschrieben.The implicit flow is described in the OAuth 2.0 Specification. 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.Its primary benefit is that it allows the app to get tokens from Azure AD without performing a backend server credential exchange. 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.This allows the app to sign in the user, maintain session, and get tokens to other web APIs all within the client JavaScript code. Bei der Verwendung des impliziten Flusses gibt es einige wichtige Sicherheitsaspekte zu beachten, insbesondere in Bezug auf Clients und Identitätsvortäuschung.There are a few important security considerations to take into account when using the implicit flow - specifically around client and user impersonation.

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.If you want to use the implicit flow and Azure AD to add authentication to your JavaScript app, we recommend you use our open source JavaScript library, adal.js. Hier finden Sie einige AngularJS-Tutorials für die ersten Schritte.There are few AngularJS tutorials available here to help you get started.

Wenn Sie jedoch in Ihrer einseitigen App keine Bibliothek verwenden und Protokollmeldungen selbst senden möchten, führen Sie die folgenden allgemeinen Schritte aus.However, if you would prefer not to use a library in your single page app and send protocol messages yourself, follow the general steps below.

Hinweis

Nicht alle Szenarien und Funktionen von Azure Active Directory werden vom v2.0-Endpunkt unterstützt.Not all Azure Active Directory scenarios & features are supported by the v2.0 endpoint. Lesen Sie die Informationen zu den Einschränkungen des v2.0-Endpunkts, um zu bestimmen, ob Sie den v2.0-Endpunkt verwenden sollten.To determine if you should use the v2.0 endpoint, read about v2.0 limitations.

ProtokolldiagrammProtocol diagram

Der vollständige implizite Anmeldevorgang sieht in etwa wie folgt aus. Die einzelnen Schritte werden unten im Detail beschrieben.The entire implicit sign in flow looks something like this - each of the steps are described in detail below.

OpenId Connect-Verantwortlichkeitsbereiche

Senden der AnmeldeanforderungSend the sign-in request

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:To initially sign the user into your app, you can send an OpenID Connect authorization request and get an id_token from the v2.0 endpoint:

// 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.Click the link below to execute this request! Nach der Anmeldung sollte der Browser mit einem id_token in der Adressleiste zu https://localhost/myapp/ umgeleitet werden.After signing in, your browser should be redirected to https://localhost/myapp/ with a id_token in the address bar. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

ParameterParameter BeschreibungDescription
tenanttenant erforderlichrequired Mit dem {tenant} -Wert im Pfad der Anforderung kann festgelegt werden, welche Benutzer sich bei der Anwendung anmelden können.The {tenant} value in the path of the request can be used to control who can sign into the application. Zulässige Werte sind common, organizations, consumers und Mandantenbezeichner.The allowed values are common, organizations, consumers, and tenant identifiers. Weitere Informationen finden Sie in den Grundlagen zu Protokollen.For more detail, see protocol basics.
client_idclient_id erforderlichrequired Die Anwendungs-ID, die das Registrierungsportal (apps.dev.microsoft.com) Ihrer Anwendung zugewiesen hat.The Application Id that the registration portal (apps.dev.microsoft.com) assigned your app.
response_typeresponse_type erforderlichrequired Muss das id_token für die OpenID Connect-Anmeldung enthalten.Must include id_token for OpenID Connect sign-in. Kann auch den Antworttyp token enthalten.It may also include the response_type token. Mithilfe von token kann Ihre App ein Zugriffstoken direkt vom Autorisierungsendpunkt abrufen, ohne dass eine zweite Anforderung an den Autorisierungsendpunkt erforderlich ist.Using token here will allow your app to receive an access token immediately from the authorize endpoint without having to make a second request to the authorize endpoint. Wenn Sie den Antworttyp token verwenden, muss der scope-Parameter einen Bereich enthalten, der angibt, für welche Ressource das Token ausgestellt wird.If you use the token response_type, the scope parameter must contain a scope indicating which resource to issue the token for.
redirect_uriredirect_uri empfohlenrecommended Der Umleitungs-URI der App, in dem Authentifizierungsantworten gesendet und von der App empfangen werden können.The redirect_uri of your app, where authentication responses can be sent and received by your app. Er muss genau mit einer der Umleitungs-URIs übereinstimmen, die Sie im Portal registriert haben, mit dem Unterschied, dass er URL-codiert sein muss.It must exactly match one of the redirect_uris you registered in the portal, except it must be url encoded.
Bereichscope erforderlichrequired Eine durch Leerzeichen getrennte Liste von Bereichen.A space-separated list of scopes. Für OpenID Connect muss der Bereich openidenthalten sein, der auf der Zustimmungsbenutzeroberfläche die Anmeldeberechtigung ergibt.For OpenID Connect, it must include the scope openid, which translates to the "Sign you in" permission in the consent UI. Schließen Sie gegebenenfalls auch die Bereiche email oder profile mit ein, um Zugriff auf zusätzliche Benutzerdaten zu erhalten.Optionally you may also want to include the email or profile scopes for gaining access to additional user data. Sie können in diese Anforderung auch andere Bereiche aufnehmen, um die Zustimmung für verschiedene Ressourcen anzufordern.You may also include other scopes in this request for requesting consent to various resources.
response_moderesponse_mode empfohlenrecommended Gibt die Methode an, die zum Senden des resultierenden Tokens zurück an Ihre App verwendet werden soll.Specifies the method that should be used to send the resulting token back to your app. Muss für den impliziten Fluss fragment sein.Should be fragment for the implicit flow.
statestate empfohlenrecommended Ein in der Anforderung enthaltener Wert, der auch in der Antwort zurückgegeben wird.A value included in the request that will also be returned in the token response. Es kann sich um eine Zeichenfolge mit jedem beliebigen Inhalt handeln.It can be a string of any content that you wish. Ein zufällig generierter eindeutiger Wert wird normalerweise verwendet, um websiteübergreifende Anforderungsfälschungsangriffe zu verhindern.A randomly generated unique value is typically used for preventing cross-site request forgery attacks. 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.The state is also used to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
noncenonce erforderlichrequired Ein Wert in der Anforderung, der von der App erzeugt wird und im resultierenden ID-Token als Anspruch enthalten sein wird.A value included in the request, generated by the app, that will be included in the resulting id_token as a claim. Die App kann diesen Wert dann überprüfen, um die Gefahr von Tokenwiedergabeangriffen zu vermindern.The app can then verify this value to mitigate token replay attacks. Der Wert ist in der Regel eine zufällige, eindeutige Zeichenfolge, die verwendet werden kann, um den Ursprung der Anforderung zu identifizieren.The value is typically a randomized, unique string that can be used to identify the origin of the request.
Eingabeaufforderungprompt optionaloptional Gibt den Typ der erforderlichen Benutzerinteraktion an.Indicates the type of user interaction that is required. Zu diesem Zeitpunkt sind die einzigen gültigen Werte „login“, „none“ und „consent“.The only valid values at this time are 'login', 'none', and 'consent'. prompt=login zwingt den Benutzer, die Anmeldeinformationen bei dieser Anforderung einzugeben. Einmaliges Anmelden ist dadurch nicht möglich.prompt=login will force the user to enter their credentials on that request, negating single-sign on. prompt=none ist genau das Gegenteil: Dieser Wert stellt sicher, dass dem Benutzer keine interaktive Eingabeaufforderung angezeigt wird.prompt=none is the opposite - it will ensure that the user is not presented with any interactive prompt whatsoever. Wenn die Anforderung nicht über einmaliges Anmelden im Hintergrund abgeschlossen werden kann, gibt der v2.0-Endpunkt einen Fehler zurück.If the request cannot be completed silently via single-sign on, the v2.0 endpoint will return an error. 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.prompt=consent will trigger the OAuth consent dialog after the user signs in, asking the user to grant permissions to the app.
login_hintlogin_hint optionaloptional 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.Can be used to pre-fill the username/email address field of the sign in page for the user, if you know their username ahead of time. 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.Often apps will use this parameter during re-authentication, having already extracted the username from a previous sign-in using the preferred_username claim.
domain_hintdomain_hint optionaloptional Kann consumers oder organizations sein.Can be one of consumers or organizations. 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.If included, it will skip the email-based discovery process that user goes through on the v2.0 sign in page, leading to a slightly more streamlined user experience. Apps verwenden diesen Parameter häufig für die wiederholte Authentifizierung, indem sie den Anspruch tid aus dem ID-Token extrahieren.Often apps will use this parameter during re-authentication, by extracting the tid claim from the id_token. Verwenden Sie domain_hint=consumers, wenn der Anspruch tid den Wert 9188040d-6c67-4c5b-b112-36a304b66dad hat.If the tid claim value is 9188040d-6c67-4c5b-b112-36a304b66dad, you should use domain_hint=consumers. Verwenden Sie andernfalls domain_hint=organizations.Otherwise, use domain_hint=organizations.

Zu diesem Zeitpunkt wird der Benutzer dazu aufgefordert, seine Anmeldeinformationen einzugeben und die Authentifizierung abzuschließen.At this point, the user will be asked to enter their credentials and complete the authentication. Der V2.0-Endpunkt stellt auch sicher, dass der Benutzer den Berechtigungen zugestimmt hat, die im scope -Abfrageparameter angegeben sind.The v2.0 endpoint will also ensure that the user has consented to the permissions indicated in the scope query parameter. Wenn der Benutzer keiner Berechtigung zugestimmt hat, wird er dazu aufgefordert, den erforderlichen Berechtigungen zuzustimmen.If the user has not consented to any of those permissions, it will ask the user to consent to the required permissions. Nähere Einzelheiten zu Berechtigungen, Zustimmung und mehrinstanzenfähigen Apps erhalten Sie hier.Details of permissions, consent, and multi-tenant apps are provided here.

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.Once the user authenticates and grants consent, the v2.0 endpoint will return a response to your app at the indicated redirect_uri, using the method specified in the response_mode parameter.

Erfolgreiche AntwortSuccessful response

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:A successful response using response_mode=fragment and response_type=id_token+token looks like the following, with line breaks for legibility:

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
ParameterParameter BeschreibungDescription
access_tokenaccess_token Ist enthalten, wenn token in response_type enthalten ist.Included if response_type includes token. Das von der Anwendung angeforderte Zugriffstoken, in diesem Fall für Microsoft Graph.The access token that the app requested, in this case for the Microsoft Graph. Das Zugriffstoken sollte nicht decodiert oder anderweitig untersucht werden, es kann als nicht transparente Zeichenfolge behandelt werden.The access token should not be decoded or otherwise inspected, it can be treated as an opaque string.
token_typetoken_type Ist enthalten, wenn token in response_type enthalten ist.Included if response_type includes token. Ist immer Bearer.Will always be Bearer.
expires_inexpires_in Ist enthalten, wenn token in response_type enthalten ist.Included if response_type includes token. Gibt für die Zwischenspeicherung den Gültigkeitszeitraum des Tokens in Sekunden an.Indicates the number of seconds the token is valid, for caching purposes.
Bereichscope Ist enthalten, wenn token in response_type enthalten ist.Included if response_type includes token. Gibt die Bereiche an, für die das Zugriffstoken gültig ist.Indicates the scope(s) for which the access_token will be valid.
id_tokenid_token Das ID-Token, das die Anwendung angefordert hat.The id_token that the app requested. Sie können mit dem ID-Token die Identität des Benutzers überprüfen und eine Sitzung mit dem Benutzer beginnen.You can use the id_token to verify the user's identity and begin a session with the user. Weitere Informationen zu ID-Token und deren Inhalt finden Sie in der Referenz für den v2.0-Endpunkttoken.More details on id_tokens and their contents is included in the v2.0 endpoint token reference.
statestate Wenn ein Statusparameter in der Anforderung enthalten ist, sollte der gleiche Wert in der Antwort angezeigt werden.If a state parameter is included in the request, the same value should appear in the response. Die Anwendung sollte überprüfen, ob die Statuswerte in der Anforderung und in der Antwort identisch sind.The app should verify that the state values in the request and response are identical.

FehlerantwortError response

Fehlerantworten können auch an den redirect_uri gesendet werden, damit die App diese angemessen behandeln kann:Error responses may also be sent to the redirect_uri so the app can handle them appropriately:

GET https://localhost/myapp/#
error=access_denied
&error_description=the+user+canceled+the+authentication
-Parameter enthalten.Parameter BeschreibungDescription
errorerror Eine Fehlercodezeichenfolge, die verwendet werden kann, um unterschiedliche Arten auftretender Fehler zu klassifizieren und um auf Fehler zu reagieren.An error code string that can be used to classify types of errors that occur, and can be used to react to errors.
error_descriptionerror_description Eine spezifische Fehlermeldung, mit der Entwickler die Hauptursache eines Authentifizierungsfehlers identifizieren können.A specific error message that can help a developer identify the root cause of an authentication error.

Überprüfen des ID-TokensValidate the id_token

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.Just receiving an id_token is not sufficient to authenticate the user; you must validate the id_token's signature and verify the claims in the token per your app's requirements. 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.The v2.0 endpoint uses JSON Web Tokens (JWTs) and public key cryptography to sign tokens and verify that they are valid.

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.You can choose to validate the id_token in client code, but a common practice is to send the id_token to a backend server and perform the validation there. Nachdem Sie die Signatur des ID-Tokens validiert haben, müssen Sie noch einige Ansprüche überprüfen.Once you've validated the signature of the id_token, there are a few claims you will be required to verify. 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).See the v2.0 token reference for more information, including Validating Tokens and Important Information About Signing Key Rollover. 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.We recommend making use of a library for parsing and validating tokens - there is at least one available for most languages and platforms.

Sie können je nach Szenario auch zusätzliche Ansprüche überprüfen.You may also wish to validate additional claims depending on your scenario. Einige allgemeinen Überprüfungen umfassen:Some common validations include:

  • Sicherstellen, dass sich der Benutzer/die Organisation für die App angemeldet hat.Ensuring the user/organization has signed up for the app.
  • Sicherstellen, dass der Benutzer über eine ordnungsgemäße Autorisierung und Berechtigungen verfügt.Ensuring the user has proper authorization/privileges
  • Sicherstellen, dass eine bestimmte Stärke der Authentifizierung aufgetreten ist, z.B. die mehrstufige Authentifizierung.Ensuring a certain strength of authentication has occurred, such as multi-factor authentication.

Weitere Informationen zu den Ansprüchen in einem ID-Token finden Sie in der Tokenreferenz zum v2.0-Endpunkt.For more information on the claims in an id_token, see the v2.0 endpoint token reference.

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.Once you have completely validated the id_token, you can begin a session with the user and use the claims in the id_token to obtain information about the user in your app. Diese Informationen kann für die Anzeige, für Datensätze, für die Autorisierung usw. verwendet werden.This information can be used for display, records, authorizations, etc.

Abrufen von ZugriffstokenGet access tokens

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.Now that you've signed the user into your single page app, you can get access tokens for calling web APIs secured by Azure AD, such as the 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.Even if you already received a token using the token response_type, you can use this method to acquire tokens to additional resources without having to redirect the user to sign in again.

Im herkömmlichen OpenID Connect/OAuth-Fluss senden Sie dazu eine Anforderung an den v2.0-Endpunkt /token .In the normal OpenID Connect/OAuth flow, you would do this by making a request to the v2.0 /token endpoint. Der v2.0-Endpunkt unterstützt jedoch keine CORS-Anforderungen, daher kommen AJAX-Aufrufe zum Abrufen und Aktualisieren von Token nicht infrage.However, the v2.0 endpoint does not support CORS requests, so making AJAX calls to get and refresh tokens is out of the question. Stattdessen können Sie den impliziten Fluss in einem ausgeblendeten IFrame verwenden, um neue Token für andere Web-APIs zu erhalten:Instead, you can use the implicit flow in a hidden iframe to get new tokens for other web APIs:

// 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.Try copy & pasting the below request into a browser tab! (Vergessen Sie dabei nicht, die Werte domain_hint und login_hint durch die richtigen Werte für den entsprechenden Benutzer zu ersetzen.)(Don't forget to replace the domain_hint and the login_hint values with the correct values for your user)

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}}
ParameterParameter BeschreibungDescription
tenanttenant erforderlichrequired Mit dem {tenant} -Wert im Pfad der Anforderung kann festgelegt werden, welche Benutzer sich bei der Anwendung anmelden können.The {tenant} value in the path of the request can be used to control who can sign into the application. Zulässige Werte sind common, organizations, consumers und Mandantenbezeichner.The allowed values are common, organizations, consumers, and tenant identifiers. Weitere Informationen finden Sie in den Grundlagen zu Protokollen.For more detail, see protocol basics.
client_idclient_id erforderlichrequired Die Anwendungs-ID, die das Registrierungsportal (apps.dev.microsoft.com) Ihrer Anwendung zugewiesen hat.The Application Id that the registration portal (apps.dev.microsoft.com) assigned your app.
response_typeresponse_type erforderlichrequired Muss das id_token für die OpenID Connect-Anmeldung enthalten.Must include id_token for OpenID Connect sign-in. Es können auch andere Antworttypen enthalten sein, z. B. code.It may also include other response_types, such as code.
redirect_uriredirect_uri empfohlenrecommended Der Umleitungs-URI der App, in dem Authentifizierungsantworten gesendet und von der App empfangen werden können.The redirect_uri of your app, where authentication responses can be sent and received by your app. Er muss genau mit einer der Umleitungs-URIs übereinstimmen, die Sie im Portal registriert haben, mit dem Unterschied, dass er URL-codiert sein muss.It must exactly match one of the redirect_uris you registered in the portal, except it must be url encoded.
Bereichscope erforderlichrequired Eine durch Leerzeichen getrennte Liste von Bereichen.A space-separated list of scopes. Beziehen Sie zum Abrufen von Token alle Bereiche ein, die für die entsprechende Ressource erforderlich sind.For getting tokens, include all scopes you require for the resource of interest.
response_moderesponse_mode empfohlenrecommended Gibt die Methode an, die zum Senden des resultierenden Tokens zurück an Ihre App verwendet werden soll.Specifies the method that should be used to send the resulting token back to your app. Kann query, form_post oder fragment sein.Can be one of query, form_post, or fragment.
statestate empfohlenrecommended Ein in der Anforderung enthaltener Wert, der auch in der Antwort zurückgegeben wird.A value included in the request that will also be returned in the token response. Es kann sich um eine Zeichenfolge mit jedem beliebigen Inhalt handeln.It can be a string of any content that you wish. Ein zufällig generierter eindeutiger Wert wird normalerweise verwendet, um websiteübergreifende Anforderungsfälschungsangriffe zu verhindern.A randomly generated unique value is typically used for preventing cross-site request forgery attacks. 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.The state is also used to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
noncenonce erforderlichrequired Ein Wert in der Anforderung, der von der App erzeugt wird und im resultierenden ID-Token als Anspruch enthalten sein wird.A value included in the request, generated by the app, that will be included in the resulting id_token as a claim. Die App kann diesen Wert dann überprüfen, um die Gefahr von Tokenwiedergabeangriffen zu vermindern.The app can then verify this value to mitigate token replay attacks. Der Wert ist in der Regel eine zufällige, eindeutige Zeichenfolge, die verwendet werden kann, um den Ursprung der Anforderung zu identifizieren.The value is typically a randomized, unique string that can be used to identify the origin of the request.
Eingabeaufforderungprompt erforderlichrequired 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.For refreshing & getting tokens in a hidden iframe, you should use prompt=none to ensure that the iframe does not hang on the v2.0 sign in page, and returns immediately.
login_hintlogin_hint erforderlichrequired 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.For refreshing & getting tokens in a hidden iframe, you must include the username of the user in this hint in order to distinguish between multiple sessions the user may have at a given point in time. Sie können den Benutzernamen aus einer vorherigen Anmeldung mithilfe des Anspruchs preferred_username extrahieren.You can extract the username from a previous sign-in using the preferred_username claim.
domain_hintdomain_hint erforderlichrequired Kann consumers oder organizations sein.Can be one of consumers or organizations. Schließen Sie zum Aktualisieren und Abrufen von Token in einem ausgeblendete IFrame „domain_hint“ in die Anforderung mit ein.For refreshing & getting tokens in a hidden iframe, you must include the domain_hint in the request. Extrahieren Sie den Anspruch tid aus dem ID-Token einer früheren Anmeldung, um festzulegen, welcher Wert verwendet werden soll.You should extract the tid claim from the id_token of a previous sign-in to determine which value to use. Verwenden Sie domain_hint=consumers, wenn der Anspruch tid den Wert 9188040d-6c67-4c5b-b112-36a304b66dad hat.If the tid claim value is 9188040d-6c67-4c5b-b112-36a304b66dad, you should use domain_hint=consumers. Verwenden Sie andernfalls domain_hint=organizations.Otherwise, use 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.Thanks to the prompt=none parameter, this request will either succeed or fail immediately and return to your application. 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.A successful response will be sent to your app at the indicated redirect_uri, using the method specified in the response_mode parameter.

Erfolgreiche AntwortSuccessful response

Eine erfolgreiche Antwort mit response_mode=fragment sieht wie folgt aus:A successful response using response_mode=fragment looks like:

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.Parameter BeschreibungDescription
access_tokenaccess_token Das von der App angeforderte TokenThe token that the app requested.
token_typetoken_type Ist immer Bearer.Will always be Bearer.
statestate Wenn ein Statusparameter in der Anforderung enthalten ist, sollte der gleiche Wert in der Antwort angezeigt werden.If a state parameter is included in the request, the same value should appear in the response. Die Anwendung sollte überprüfen, ob die Statuswerte in der Anforderung und in der Antwort identisch sind.The app should verify that the state values in the request and response are identical.
expires_inexpires_in Gibt an, wie lange das Zugriffstoken (in Sekunden) gültig ist.How long the access token is valid (in seconds).
Bereichscope Die Bereiche, für die das Zugriffstoken gültig ist.The scopes that the access token is valid for.

FehlerantwortError response

Fehlerantworten können auch an den redirect_uri gesendet werden, damit die App diese angemessen behandeln kann:Error responses may also be sent to the redirect_uri so the app can handle them appropriately. Im Fall von prompt=none wird folgender Fehler erwartet:In the case of prompt=none, an expected error will be:

GET https://localhost/myapp/#
error=user_authentication_required
&error_description=the+request+could+not+be+completed+silently
ParameterParameter BeschreibungDescription
errorerror Eine Fehlercodezeichenfolge, die verwendet werden kann, um unterschiedliche Arten auftretender Fehler zu klassifizieren und um auf Fehler zu reagieren.An error code string that can be used to classify types of errors that occur, and can be used to react to errors.
error_descriptionerror_description Eine spezifische Fehlermeldung, mit der Entwickler die Hauptursache eines Authentifizierungsfehlers identifizieren können.A specific error message that can help a developer identify the root cause of an authentication error.

Wenn Sie diesen Fehler in der IFrame-Anforderung erhalten, muss sich der Benutzer erneut anmelden, um ein neues Token abzurufen.If you receive this error in the iframe request, the user must interactively sign in again to retrieve a new token. Diesen Fall können Sie so behandeln, wie es für Ihre Anwendung am sinnvollsten ist.You can choose to handle this case in whatever way makes sense for your application.

Aktualisieren von TokenRefreshing tokens

id_tokens und access_tokens laufen nach kurzer Zeit ab. Ihre App muss daher diese Token in regelmäßigen Abständen aktualisieren.Both id_tokens and access_tokens will expire after a short period of time, so your app must be prepared to refresh these tokens periodically. 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.To refresh either type of token, you can perform the same hidden iframe request from above using the prompt=none parameter to control Azure AD's behavior. Wenn Sie ein neues id_token erhalten möchten, verwenden Sie unbedingt response_type=id_token und scope=openid, sowie den Parameter nonce.If you want to receive a new id_token, be sure to use response_type=id_token and scope=openid, as well as a nonce parameter.

Senden einer AbmeldungsanforderungSend a sign out request

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.The OpenIdConnect end_session_endpoint allows your app to send a request to the v2.0 endpoint to end a user's session and clear cookies set by the v2.0 endpoint. 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:To fully sign a user out of a web application, your app should end its own session with the user (usually by clearing a token cache or dropping cookies), and then redirect the browser to:

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/logout?post_logout_redirect_uri=https://localhost/myapp/
ParameterParameter BeschreibungDescription
tenanttenant erforderlichrequired Mit dem {tenant} -Wert im Pfad der Anforderung kann festgelegt werden, welche Benutzer sich bei der Anwendung anmelden können.The {tenant} value in the path of the request can be used to control who can sign into the application. Zulässige Werte sind common, organizations, consumers und Mandantenbezeichner.The allowed values are common, organizations, consumers, and tenant identifiers. Weitere Informationen finden Sie in den Grundlagen zu Protokollen.For more detail, see protocol basics.
post_logout_redirect_uripost_logout_redirect_uri empfohlenrecommended Die URL, zu der der Benutzer nach erfolgreicher Abmeldung umgeleitet werden soll.The URL that the user should be returned to after logout completes. Dieser Wert muss einem der Umleitung-URIs entsprechen, die für die Anwendung registriert sind.This value must match one of the redirect URIs registered for the application. Wenn keine Angabe erfolgt, wird dem Benutzer vom v2.0-Endpunkt eine allgemeine Meldung angezeigt.If not included, the user will be shown a generic message by the v2.0 endpoint.