Microsoft Identity Platform und das OpenID Connect-ProtokollMicrosoft identity platform and OpenID Connect protocol

OpenID Connect (OIDC) ist ein Authentifizierungsprotokoll auf Grundlage von OAuth 2.0, mit dem Benutzer sicher bei einer Anwendung angemeldet werden können.OpenID Connect (OIDC) is an authentication protocol built on OAuth 2.0 that you can use to securely sign in a user to an application. Die Implementierung von OpenID Connect im Microsoft Identity Platform-Endpunkt ermöglicht es Ihnen, Anmeldungen und API-Zugriff für Ihre Apps hinzuzufügen.When you use the Microsoft identity platform endpoint's implementation of OpenID Connect, you can add sign-in and API access to your apps. In diesem Artikel wird beschrieben, wie dies sprachunabhängig funktioniert. Außerdem wird beschrieben, wie HTTP-Nachrichten gesendet und empfangen werden, ohne Open Source-Bibliotheken von Microsoft zu verwenden.This article shows how to do this independent of language and describes how to send and receive HTTP messages without using any Microsoft open-source libraries.

Mit OpenID Connect wird das OAuth 2.0-Autorisierungsprotokoll auf die Nutzung als Authentifizierungsprotokoll erweitert, damit einmaliges Anmelden per OAuth funktioniert.OpenID Connect extends the OAuth 2.0 authorization protocol for use as an authentication protocol, so that you can do single sign-on using OAuth. OpenID Connect führt das Konzept eines ID-Tokens ein. Hierbei handelt es sich um ein Sicherheitstoken, mit dem der Client die Identität des Benutzers überprüfen kann.OpenID Connect introduces the concept of an ID token, which is a security token that allows the client to verify the identity of the user. Ferner ruft das ID-Token auch Basisprofilinformationen über den Benutzer ab.The ID token also gets basic profile information about the user. Darüber hinaus wird der UserInfo-Endpunkt eingeführt. Hierbei handelt es sich um eine API, die Informationen zum Benutzer zurückgibt.It also introduces the UserInfo endpoint, an API that returns information about the user.

Protokolldiagramm: AnmeldungProtocol diagram: Sign-in

Der grundlegende Anmeldefluss besteht aus den in der nächsten Abbildung gezeigten Schritten.The most basic sign-in flow has the steps shown in the next diagram. Jeder Schritt wird in diesem Artikel detailliert beschrieben.Each step is described in detail in this article.

OpenID Connect-Protokoll: Anmeldung

Abrufen des OpenID Connect-MetadatendokumentsFetch the OpenID Connect metadata document

OpenID Connect beschreibt ein Metadatendokument (RFC), das den Großteil der Informationen enthält, die für eine App zum Durchführen einer Anmeldung erforderlich sind.OpenID Connect describes a metadata document (RFC) that contains most of the information required for an app to do sign in. Hierzu gehören Informationen wie z.B. die zu verwendenden URLs und der Speicherort der öffentlichen Signaturschlüssel des Dienstes.This includes information such as the URLs to use and the location of the service's public signing keys. Sie können auf dieses Dokument zugreifen, indem Sie den Ermittlungsdokumentpfad an die Autoritäts-URL anfügen:You can find this document by appending the discovery document path to the authority URL:

Ermittlungsdokumentpfad: /.well-known/openid-configurationDiscovery document path: /.well-known/openid-configuration

Autorität: https://login.microsoftonline.com/{tenant}/v2.0Authority: https://login.microsoftonline.com/{tenant}/v2.0

Der {tenant} kann einen von vier möglichen Werten annehmen:The {tenant} can take one of four values:

WertValue BESCHREIBUNGDescription
common Benutzer mit einem persönlichen Microsoft-Konto und einem Geschäfts-, Schul- oder Unikonto aus Azure AD können sich bei der Anwendung anmelden.Users with both a personal Microsoft account and a work or school account from Azure AD can sign in to the application.
organizations Nur Benutzer mit Geschäfts-, Schul- oder Unikonten aus Azure AD können sich bei der Anwendung anmelden.Only users with work or school accounts from Azure AD can sign in to the application.
consumers Nur Benutzer mit einem persönlich Microsoft-Konto können sich bei der Anwendung anmelden.Only users with a personal Microsoft account can sign in to the application.
8eaef023-2b34-4da1-9baa-8bc8c9d6a490 oder contoso.onmicrosoft.com8eaef023-2b34-4da1-9baa-8bc8c9d6a490 or contoso.onmicrosoft.com Nur Benutzer eines bestimmten Azure AD-Mandanten können sich bei der Anwendung anmelden. (Dabei macht es keinen Unterschied, ob es sich um Mitglieder im Verzeichnis mit einem Geschäfts-, Schul- oder Unikonto oder um Gäste im Verzeichnis mit einem persönlichen Microsoft-Konto handelt.)Only users from a specific Azure AD tenant (whether they are members in the directory with a work or school account, or they are guests in the directory with a personal Microsoft account) can sign in to the application. Dabei kann entweder der Anzeigename der Domäne des Azure AD-Mandanten oder der GUID-Bezeichner des Mandanten verwendet werden.Either the friendly domain name of the Azure AD tenant or the tenant's GUID identifier can be used. Sie können auch den Consumermandanten 9188040d-6c67-4c5b-b112-36a304b66dad anstelle des Mandanten consumers verwenden.You can also use the consumer tenant, 9188040d-6c67-4c5b-b112-36a304b66dad, in place of the consumers tenant.

Die Autorität variiert je nach der verwendeten nationalen Cloud, z. B. https://login.microsoftonline.de für die Instanz „Azure AD Deutschland“.The authority differs across national clouds - e.g. https://login.microsoftonline.de for the Azure AD Germany instance. Falls Sie nicht die öffentliche Cloud nutzen, helfen Ihnen die Informationen unter Azure AD-Authentifizierungsendpunkte bei der Wahl einer passenden Cloud.If you do not use the public cloud, please review the national cloud endpoints to find the appropriate one for you. Stellen Sie sicher, dass Ihre Anforderung den Mandanten und /v2.0/ enthält, damit Sie Version 2.0 des Endpunkts verwenden können.Ensure that the tenant and /v2.0/ are present in your request so you can use the v2.0 version of the endpoint.

Tipp

TestenTry it! Klicken Sie auf https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration, um die common -Konfiguration anzuzeigen.Click https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration to see the common configuration.

Beispiel für eine AnforderungSample request

Gehen Sie wie folgt vor, um den UserInfo-Endpunkt für die common-Autorität in der öffentlichen Cloud aufzurufen:To call the userinfo endpoint for the common authority on the public cloud, use the following:

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

Beispiel für eine AntwortSample response

Bei den Metadaten handelt es sich um ein einfaches JavaScript Object Notation-Dokument (JSON).The metadata is a simple JavaScript Object Notation (JSON) document. Die folgenden Codeausschnitte zeigen Beispiele.See the following snippet for an example. Die vollständigen Inhalte sind in der OpenID Connect-Spezifikation beschrieben.The contents are fully described in the OpenID Connect specification.

{
  "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"
  ],
  ...

}

Wenn Ihre App durch die Verwendung der Funktion Anspruchszuordnung über benutzerdefinierte Signaturschlüssel verfügt, müssen Sie einen appid-Abfrageparameter mit der App-ID anfügen, um einen jwks_uri abzurufen, der auf die Signaturschlüsselinformationen Ihrer App verweist.If your app has custom signing keys as a result of using the claims-mapping feature, you must append an appid query parameter containing the app ID in order to get a jwks_uri pointing to your app's signing key information. Beispiel: https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e enthält einen jwks_uri von https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.For example: https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contains a jwks_uri of https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

In der Regel verwenden Sie dieses Metadatendokument zum Konfigurieren einer OpenID Connect-Bibliothek oder eines SDKs; die Bibliothek führt ihre Aufgaben mithilfe der Metadaten durch.Typically, you would use this metadata document to configure an OpenID Connect library or SDK; the library would use the metadata to do its work. Wenn Sie jedoch keine OpenID Connect-Prä-Build-Bibliothek verwenden, können Sie die Schritte weiter unten in diesem Artikel ausführen, um die Anmeldung bei einer Web-App mithilfe des Microsoft Identity Platform-Endpunkts durchzuführen.However, if you're not using a pre-built OpenID Connect library, you can follow the steps in the remainder of this article to do sign-in in a web app by using the Microsoft identity platform endpoint.

Senden der AnmeldeanforderungSend the sign-in request

Wenn die Web-App den Benutzer authentifizieren muss, kann sie ihn direkt an den /authorize -Endpunkt weiterleiten.When your web app needs to authenticate the user, it can direct the user to the /authorize endpoint. Diese Anforderung ähnelt dem ersten Abschnitt des OAuth 2.0-Autorisierungscodeflusses, allerdings mit einigen wichtigen Unterschieden:This request is similar to the first leg of the OAuth 2.0 authorization code flow, with these important distinctions:

  • Die Anforderung muss im scope-Parameter den openid-Bereich enthalten.The request must include the openid scope in the scope parameter.
  • Der response_type-Parameter muss id_token enthalten.The response_type parameter must include id_token.
  • Die Anforderung muss den nonce -Parameter enthalten.The request must include the nonce parameter.

Wichtig

Zur erfolgreichen Anforderung eines ID-Tokens vom Endpunkt „/authorization“ muss für die App-Registrierung im Registrierungsportal auf der Registerkarte „Authentifizierung“ die implizite Genehmigung von „id_tokens“ aktiviert sein (dadurch wird das Flag oauth2AllowIdTokenImplicitFlow im Anwendungsmanifest auf true festgelegt).In order to successfully request an ID token from the /authorization endpoint, the app registration in the registration portal must have the implicit grant of id_tokens enabled in the Authentication tab (which sets the oauth2AllowIdTokenImplicitFlow flag in the application manifest to true). Wenn sie nicht aktiviert ist, wird ein unsupported_response-Fehler zurückgegeben: „The provided value for the input parameter 'response_type' isn't allowed for this client.If it isn't enabled, an unsupported_response error will be returned: "The provided value for the input parameter 'response_type' isn't allowed for this client. Expected value is ‚code‘“. (Der angegebene Wert für den Eingabeparameter ‚response_type‘ ist für diesen Client nicht zulässig. Erwarteter Wert: ‚code‘.)Expected value is 'code'"

Beispiel:For example:

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=form_post
&scope=openid
&state=12345
&nonce=678910
ParameterParameter BedingungCondition BESCHREIBUNGDescription
tenant ErforderlichRequired Mit dem {tenant}-Wert im Pfad der Anforderung kann festgelegt werden, welche Benutzer sich bei der Anwendung anmelden können.You can use the {tenant} value in the path of the request to control who can sign in to 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 Protokollgrundlagen.For more information, see protocol basics.
client_id ErforderlichRequired Die Anwendungs-ID (Client-ID) , die Ihrer App im Azure-Portal auf der Seite „App-Registrierungen“ zugewiesen wurde.The Application (client) ID that the Azure portal – App registrations experience assigned to your app.
response_type ErforderlichRequired Muss das id_token für die OpenID Connect-Anmeldung enthalten.Must include id_token for OpenID Connect sign-in. Es kann auch andere response_type-Werte enthalten, z.B. code.It might also include other response_type values, such as code.
redirect_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 that it must be URL encoded. Wenn dieser Parameter nicht vorhanden ist, wählt der Endpunkt nach dem Zufallsprinzip einen registrierten Umleitungs-URI aus, der an den Benutzer zurückgesendet wird.If not present, the endpoint will pick one registered redirect_uri at random to send the user back to.
scope 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. Sie können in diese Anforderung auch andere Bereiche für das Anfordern der Zustimmung aufnehmen.You might also include other scopes in this request for requesting consent.
nonce ErforderlichRequired Ein Wert in der Anforderung, der von der App erzeugt wird und im resultierenden ID-Tokenwert als Anspruch enthalten ist.A value included in the request, generated by the app, that will be included in the resulting id_token value as a claim. Die App kann diesen Wert überprüfen, um die Gefahr von Tokenwiedergabeangriffen zu reduzieren.The app can 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 typically is a randomized, unique string that can be used to identify the origin of the request.
response_mode EmpfohlenRecommended Gibt die Methode an, die zum Senden des resultierenden Autorisierungscodes zurück an Ihre App verwendet werden soll.Specifies the method that should be used to send the resulting authorization code back to your app. Kann form_post oder fragment sein.Can be form_post or fragment. Bei Webanwendungen empfiehlt sich die Verwendung von response_mode=form_post, um eine möglichst sichere Tokenübertragung an die Anwendung zu gewährleisten.For web applications, we recommend using response_mode=form_post, to ensure the most secure transfer of tokens to your application.
state EmpfohlenRecommended Ein in der Anforderung enthaltener Wert, der auch in der Tokenantwort zurückgegeben wird.A value included in the request that also will 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 you want. Normalerweise wird ein zufällig generierter eindeutiger Wert verwendet, um websiteübergreifende Anforderungsfälschungsangriffe zu verhindern.A randomly generated unique value typically is used to prevent cross-site request forgery attacks. 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.The state also is used to encode information about the user's state in the app before the authentication request occurred, such as the page or view the user was on.
prompt OptionalOptional Gibt den Typ der erforderlichen Benutzerinteraktion an.Indicates the type of user interaction that is required. Die einzigen gültigen Werte sind gegenwärtig login, none und consent.The only valid values at this time are login, none, and consent. Der Anspruch prompt=login zwingt den Benutzer, seine Anmeldeinformationen bei dieser Anforderung einzugeben. Einmaliges Anmelden ist dadurch nicht möglich.The prompt=login claim forces the user to enter their credentials on that request, which negates single sign-on. Der Anspruch prompt=none verhält sich genau entgegengesetzt.The prompt=none claim is the opposite. Dieser Anspruch stellt sicher, dass dem Benutzer keine interaktive Eingabeaufforderung angezeigt wird.This claim ensures that the user isn't presented with any interactive prompt at. Wenn die Anforderung nicht über einmaliges Anmelden im Hintergrund abgeschlossen werden kann, gibt der Microsoft Identity Platform-Endpunkt einen Fehler zurück.If the request can't be completed silently via single sign-on, the Microsoft identity platform endpoint returns an error. Der Anspruch prompt=consent löst das OAuth-Zustimmungsdialogfeld aus, sobald sich der Benutzer angemeldet hat.The prompt=consent claim triggers the OAuth consent dialog after the user signs in. Das Dialogfeld fordert den Benutzer zum Erteilen von Berechtigungen für die App auf.The dialog asks the user to grant permissions to the app.
login_hint OptionalOptional Sie können diesen Parameter verwenden, um das Feld für den Benutzernamen und die E-Mail-Adresse auf der Anmeldeseite vorab für den Benutzer auszufüllen, wenn dessen Benutzername im Vorfeld bekannt ist.You can use this parameter to pre-fill the username and email address field of the sign-in page for the user, if you know the username ahead of time. Apps verwenden diesen Parameter häufig für die erneute Authentifizierung, nachdem sie den Benutzernamen bereits aus einer vorherigen Anmeldung mithilfe des preferred_username-Anspruchs extrahiert haben.Often, apps use this parameter during reauthentication, after already extracting the username from an earlier sign-in by using the preferred_username claim.
domain_hint OptionalOptional Der Bereich des Benutzers in einem Verbundverzeichnis.The realm of the user in a federated directory. Mit diesem Parameter wird der E-Mail-basierte Ermittlungsvorgang übersprungen, den der Benutzer auf der Anmeldeseite durchläuft, was die Benutzerfreundlichkeit verbessert.This skips the email-based discovery process that the user goes through on the sign-in page, for a slightly more streamlined user experience. 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.For tenants that are federated through an on-premises directory like AD FS, this often results in a seamless sign-in because of the existing login session.

An dieser Stelle wird der Benutzer dazu aufgefordert, seine Anmeldeinformationen einzugeben und die Authentifizierung abzuschließen.At this point, the user is prompted to enter their credentials and complete the authentication. Der Microsoft Identity Platform-Endpunkt überprüft, ob der Benutzer den Berechtigungen zugestimmt hat, die im scope-Abfrageparameter angegeben sind.The Microsoft identity platform endpoint verifies that the user has consented to the permissions indicated in the scope query parameter. Wenn der Benutzer keiner dieser Berechtigungen zugestimmt hat, wird er vom Microsoft Identity Platform-Endpunkt aufgefordert, den erforderlichen Berechtigungen zuzustimmen.If the user hasn't consented to any of those permissions, the Microsoft identity platform endpoint prompts the user to consent to the required permissions. Lesen Sie mehr über Berechtigungen, die Zustimmung und mehrinstanzenfähige Apps.You can read more about permissions, consent, and multi-tenant apps.

Sobald der Benutzer authentifiziert wurde und seine Zustimmung erteilt hat, gibt der Microsoft Identity Platform-Endpunkt mithilfe der im Parameter response_mode festgelegten Methode eine Antwort über den angegebenen Umleitungs-URI an Ihre App zurück.After the user authenticates and grants consent, the Microsoft identity platform endpoint returns a response to your app at the indicated redirect URI by using the method specified in the response_mode parameter.

Erfolgreiche AntwortSuccessful response

Bei Verwendung von response_mode=form_post sieht eine erfolgreiche Antwort wie folgt aus:A successful response when you use response_mode=form_post looks like this:

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

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345
ParameterParameter BESCHREIBUNGDescription
id_token Das ID-Token, das die App angefordert hat.The ID token that the app requested. Sie können mit dem Parameter id_token die Identität des Benutzers überprüfen und eine Sitzung mit dem Benutzer beginnen.You can use the id_token parameter 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 id_tokens-Referenz.For more information about ID tokens and their contents, see the id_tokens reference.
state Wenn ein Parameter state 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 Umleitungs-URI gesendet werden, damit die App diese angemessen behandeln kann.Error responses might also be sent to the redirect URI so that the app can handle them. Eine Fehlerantwort sieht wie folgt aus:An error response looks like this:

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

error=access_denied&error_description=the+user+canceled+the+authentication
ParameterParameter BESCHREIBUNGDescription
error Eine Fehlercodezeichenfolge, die verwendet werden kann, um unterschiedliche Arten auftretender Fehler zu klassifizieren und um auf Fehler zu reagieren.An error code string that you can use to classify types of errors that occur, and to react to errors.
error_description Eine spezifische Fehlermeldung, mit der Sie die Hauptursache eines Authentifizierungsfehlers identifizieren können.A specific error message that can help you identify the root cause of an authentication error.

Fehlercodes beim AutorisierungsendpunktfehlerError codes for authorization endpoint errors

Die folgende Tabelle beschreibt die Fehlercodes, die im Parameter error der Fehlerantwort zurückgegeben werden können:The following table describes error codes that can be returned in the error parameter of the error response:

FehlercodeError code BESCHREIBUNGDescription ClientaktionClient action
invalid_request Protokollfehler, z.B. ein fehlender erforderlicher Parameter.Protocol error, such as a missing, required parameter. Korrigieren Sie die Anforderung, und senden Sie sie erneut.Fix and resubmit the request. Dies ist ein Entwicklungsfehler, der in der Regel bei den Eingangstests festgestellt wird.This is a development error that typically is caught during initial testing.
unauthorized_client Die Clientanwendung darf keinen Autorisierungscode anfordern.The client application can't request an authorization code. Dies tritt in der Regel auf, wenn die Clientanwendung nicht in Azure AD registriert ist oder dem Azure AD-Mandanten des Benutzers nicht hinzugefügt wird.This usually occurs when the client application isn't registered in Azure AD or isn't added to the user's Azure AD tenant. Die Anwendung kann den Benutzer zum Installieren der Anwendung und zum Hinzufügen zu Azure AD auffordern.The application can prompt the user with instructions to install the application and add it to Azure AD.
access_denied Der Ressourcenbesitzer hat die Zustimmung verweigert.The resource owner denied consent. Die Clientanwendung kann den Benutzer benachrichtigen, dass sie ohne Zustimmung des Benutzers nicht fortfahren kann.The client application can notify the user that it can't proceed unless the user consents.
unsupported_response_type Der Autorisierungsserver unterstützt den Antworttyp in der Anforderung nicht.The authorization server does not support the response type in the request. Korrigieren Sie die Anforderung, und senden Sie sie erneut.Fix and resubmit the request. Dies ist ein Entwicklungsfehler, der in der Regel bei den Eingangstests festgestellt wird.This is a development error that typically is caught during initial testing.
server_error Der Server hat einen unerwarteten Fehler erkannt.The server encountered an unexpected error. Wiederholen Sie die Anforderung.Retry the request. Diese Fehler werden durch temporäre Bedingungen verursacht.These errors can result from temporary conditions. Die Clientanwendung kann dem Benutzer erklären, dass ihre Antwort aufgrund eines temporären Fehlers verzögert ist.The client application might explain to the user that its response is delayed because of a temporary error.
temporarily_unavailable Der Server ist vorübergehend überlastet und kann die Anforderung nicht verarbeiten.The server is temporarily too busy to handle the request. Wiederholen Sie die Anforderung.Retry the request. Die Clientanwendung kann dem Benutzer erklären, dass ihre Antwort aufgrund einer temporären Bedingung verzögert ist.The client application might explain to the user that its response is delayed because of a temporary condition.
invalid_resource Die Zielressource ist ungültig, da sie nicht vorhanden ist, Azure AD sie nicht findet oder sie nicht ordnungsgemäß konfiguriert wurde.The target resource is invalid because either it does not exist, Azure AD can't find it, or it isn't correctly configured. Dies zeigt an, dass die Ressource, sofern vorhanden, nicht im Mandanten konfiguriert wurde.This indicates that the resource, if it exists, hasn't been configured in the tenant. Die Anwendung kann den Benutzer zum Installieren der Anwendung und zum Hinzufügen zu Azure AD auffordern.The application can prompt the user with instructions for installing the application and adding it to Azure AD.

Überprüfen des ID-TokensValidate the ID token

Das Empfangen eines ID-Tokens (id_token) allein reicht nicht immer aus, um den Benutzer zu authentifizieren. Unter Umständen müssen Sie auch die Signatur des ID-Tokens validieren und die Ansprüche im Token anhand der App-Anforderungen überprüfen.Just receiving an id_token isn't always sufficient to authenticate the user; you may also need to validate the id_token's signature and verify the claims in the token per your app's requirements. Wie bei allen OIDC-Plattformen gilt Folgendes: Der Microsoft Identity Platform-Endpunkt verwendet JSON-Webtoken (JWTs) und die Verschlüsselung mit öffentlichem Schlüssel, um ID-Token zu signieren und deren Gültigkeit zu überprüfen.Like all OIDC platforms, the Microsoft identity platform endpoint uses JSON Web Tokens (JWTs) and public key cryptography to sign ID tokens and verify that they're valid.

Nicht alle Apps profitieren von der Überprüfung des ID-Tokens. Für native Apps und Einzelseiten-Apps ergeben sich aus der Überprüfung des ID-Tokens nur selten Vorteile.Not all apps benefit from verifying the ID token - native apps and single page apps, for instance, rarely benefit from validating the ID token. Personen mit physischem Zugang zum Gerät (oder Browser) können die Überprüfung auf unterschiedliche Arten umgehen. Beispiele hierfür sind die Bearbeitung des Webdatenverkehrs für das Gerät, um falsche Token und Schlüssel bereitzustellen, oder das simple Debuggen der Anwendung, um die Überprüfungslogik zu überspringen.Someone with physical access to the device (or browser) can bypass the validation in many ways - from editing the web traffic to the device to provide fake tokens and keys to simply debugging the application to skip the validation logic. Andererseits muss das ID-Token von Web-Apps und APIs, die dieses für Autorisierungszwecke nutzen, sorgfältig überprüft werden, weil sie die Kontrolle des Zugriffs auf Daten durchführen müssen.On the other hand, web apps and APIs using an ID token to authorization must validate the ID token carefully since they are gating access to data.

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'll be required to verify. Weitere Informationen finden Sie in der id_token-Referenz. Dort finden Sie auch Einzelheiten zum Überprüfen von Token und Wichtige Informationen zum Rollover von Signaturschlüsseln.See the id_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 Authentifizierungsmethode verwendet wird, z. B. die mehrstufige Authentifizierung.Ensuring a certain strength of authentication has occurred, such as multi-factor authentication.

Nachdem Sie das ID-Token ü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 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 können für die Anzeige, für Datensätze, für die Personalisierung usw. verwendet werden.This information can be used for display, records, personalization, etc.

Protokolldiagramm: ZugriffstokenbeschaffungProtocol diagram: Access token acquisition

Viele Web-Apps müssen nicht nur den Benutzer anmelden, sondern auch mithilfe von OAuth im Namen dieses Benutzers auf einen Webdienst zugreifen.Many web apps need to not only sign the user in, but also to access a web service on behalf of the user by using OAuth. Dieses Szenario kombiniert OpenID Connect für die Benutzerauthentifizierung und ruft gleichzeitig einen Autorisierungscode ab, der mithilfe des OAuth-Autorisierungscodeflusses Zugriffstoken abrufen kann.This scenario combines OpenID Connect for user authentication while simultaneously getting an authorization code that you can use to get access tokens if you are using the OAuth authorization code flow.

Der vollständige Ablauf für die Anmeldung mit OpenID Connect und den Abruf von Token sieht etwa wie folgt aus.The full OpenID Connect sign-in and token acquisition flow looks similar to the next diagram. Die einzelnen Schritte werden in den nächsten Abschnitten dieses Artikels im Detail beschrieben.We describe each step in detail in the next sections of the article.

OpenID Connect-Protokoll: Tokenbeschaffung

Abrufen eines Zugriffstokens zum Aufrufen von UserInfoGet an access token to call UserInfo

Ändern Sie die Anmeldeanforderung, um ein Token für den OIDC-UserInfo-Endpunkt abzurufen:To acquire a token for the OIDC UserInfo endpoint, modify the sign-in request:

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e        // Your registered Application ID
&response_type=id_token%20token                       // this will return both an id_token and an access token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F       // Your registered redirect URI, URL encoded
&response_mode=form_post                              // 'form_post' or 'fragment'
&scope=openid+profile+email                           // `openid` is required.  `profile` and `email` provide additional information in the UserInfo endpoint the same way 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 auch den Autorisierungscodefluss, den Gerätecodefluss oder ein Aktualisierungstoken anstelle von response_type=token verwenden, um ein Token für Ihre App abzurufen.You can also use the authorization code flow, the device code flow, or a refresh token in place of response_type=token to get a token for your app.

Tipp

Klicken Sie auf den folgenden Link, um diese Anforderung auszuführen.Click the following link to execute this request. Nachdem Sie sich angemeldet haben, wird Ihr Browser mit einem ID-Token und einem Token in der Adressleiste an https://localhost/myapp/ weitergeleitet.After you sign in, your browser is redirected to https://localhost/myapp/, with an ID token and a token in the address bar. Beachten Sie, dass bei dieser Anforderung response_mode=fragment nur zu Demonstrationszwecken verwendet wird. Für eine Web-App empfehlen wir Ihnen nach Möglichkeit die Nutzung von form_post, um die Sicherheit zu erhöhen.Note that this request uses response_mode=fragment for demonstration purposes only - for a webapp we recommend using form_post for additional security where possible. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

Erfolgreiche TokenantwortSuccessful token response

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

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.Response parameters mean the same thing regardless of the flow used to acquire them.

ParameterParameter BESCHREIBUNGDescription
access_token Das Token, das zum Aufrufen des UserInfo-Endpunkts verwendet wird.The token that will be used to call the UserInfo endpoint.
token_type Immer „Bearer“Always "Bearer"
expires_in Gibt die Dauer bis zum Ablauf des Zugriffstokens an (in Sekunden).How long until the access token expires, in seconds.
scope Die Berechtigungen, die für das Zugriffstoken gewährt wurden.The permissions granted on the access token. Beachten Sie Folgendes: Da der UserInfo-Endpunkt unter MS Graph gehostet wird, sind hier ggf. weitere Graph-Bereiche aufgelistet (z. B. „user.read“), falls diese für die App zuvor gewährt wurden.Note that since the UserInfo endpoint is hosted on MS Graph, there may be additional Graph scopes listed here (e.g. user.read) if they were previously granted to the app. Der Grund ist, dass ein Token für eine bestimmte Ressource immer alle gewährten Berechtigungen umfasst, über die der Client derzeit verfügt.That's because a token for a given resource always includes every permission currently granted to the client.
id_token Das ID-Token, das die App 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 id_tokens-Referenz.You'll find more details about ID tokens and their contents in the id_tokens reference.
state 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 Umleitungs-URI gesendet werden, damit die App diese angemessen behandeln kann.Error responses might also be sent to the redirect URI so that the app can handle them appropriately. Eine Fehlerantwort sieht wie folgt aus:An error response looks like this:

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

error=access_denied&error_description=the+user+canceled+the+authentication
ParameterParameter BESCHREIBUNGDescription
error Eine Fehlercodezeichenfolge, die verwendet werden kann, um unterschiedliche Arten auftretender Fehler zu klassifizieren und um auf Fehler zu reagieren.An error code string that you can use to classify types of errors that occur, and to react to errors.
error_description Eine spezifische Fehlermeldung, mit der Sie die Hauptursache eines Authentifizierungsfehlers identifizieren können.A specific error message that can help you identify the root cause of an authentication error.

Eine Beschreibung der möglichen Fehlercodes und der jeweils empfohlenen Clientantwort finden Sie unter Fehlercodes beim Autorisierungsendpunktfehler.For a description of possible error codes and recommended client responses, see Error codes for authorization endpoint errors.

Nachdem Sie einen Autorisierungscode und ein ID-Token erhalten haben, können Sie den Benutzer anmelden und Zugriffstoken in seinem Namen abrufen.When you have an authorization code and an ID token, you can sign the user in and get access tokens on their behalf. Zum Anmelden des Benutzers müssen Sie das ID-Token genau wie beschrieben überprüfen.To sign the user in, you must validate the ID token exactly as described. Führen Sie zum Abrufen von Zugriffstoken die in der Dokumentation zum OAuth-Codefluss beschriebenen Schritte aus.To get access tokens, follow the steps described in OAuth code flow documentation.

Aufrufen des UserInfo-EndpunktsCalling the UserInfo endpoint

Die UserInfo-Dokumentation enthält Informationen dazu, wie der UserInfo-Endpunkt mit diesem Token aufgerufen wird.Review the UserInfo documentation to look over how the call the UserInfo endpoint with this token.

Senden einer AbmeldeanforderungSend a sign-out request

Wenn Sie den Benutzer bei der App abmelden möchten, reicht es nicht, die Cookies der App zu löschen oder die Sitzung des Benutzers auf andere Weise zu beenden.When you want to sign out the user from your app, it isn't sufficient to clear your app's cookies or otherwise end the user's session. Sie müssen den Benutzer für die Abmeldung außerdem an den Microsoft Identity Platform-Endpunkt umleiten. Andernfalls kann sich der Benutzer erneut für Ihre App authentifizieren, ohne die Anmeldeinformationen erneut einzugeben, da der Benutzer nach wie vor über eine gültige SSO-Sitzung (Single Sign-On, Einmaliges Anmelden) beim Microsoft Identity Platform-Endpunkt verfügt.You must also redirect the user to the Microsoft identity platform endpoint to sign out. If you don't do this, the user reauthenticates to your app without entering their credentials again, because they will have a valid single sign-in session with the Microsoft identity platform endpoint.

Sie können den Benutzer an den end_session_endpoint umleiten, der im OpenID Connect-Metadatendokument aufgeführt wird:You can redirect the user to the end_session_endpoint listed in the OpenID Connect metadata document:

GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
ParameterParameter BedingungCondition BESCHREIBUNGDescription
post_logout_redirect_uri EmpfohlenRecommended 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 vom Microsoft Identity Platform-Endpunkt generiert wird.The URL that the user is redirected to after successfully signing out. If the parameter isn't included, the user is shown a generic message that's generated by the Microsoft identity platform endpoint. Diese URL muss mit einem der Umleitungs-URIs übereinstimmen, die im App-Registrierungsportal für Ihre Anwendung registriert wurden.This URL must match one of the redirect URIs registered for your application in the app registration portal.

Einmaliges AbmeldenSingle sign-out

Wenn Sie den Benutzer an end_session_endpoint umleiten, löscht der Microsoft Identity Platform-Endpunkt die Sitzung des Benutzers aus dem Browser.When you redirect the user to the end_session_endpoint, the Microsoft identity platform endpoint clears the user's session from the browser. Allerdings kann der Benutzer weiterhin bei anderen Anwendungen angemeldet sein, die Microsoft-Konten für die Authentifizierung verwenden.However, the user may still be signed in to other applications that use Microsoft accounts for authentication. Damit diese Anwendungen den Benutzer gleichzeitig abmelden können, sendet der Microsoft Identity Platform-Endpunkt eine HTTP GET-Anforderung an die registrierte LogoutUrl aller Anwendungen, bei denen der Benutzer zurzeit angemeldet ist.To enable those applications to sign the user out simultaneously, the Microsoft identity platform endpoint sends an HTTP GET request to the registered LogoutUrl of all the applications that the user is currently signed in to. 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.Applications must respond to this request by clearing any session that identifies the user and returning a 200 response. Wenn Sie das einmalige Abmelden in Ihrer Anwendung unterstützen möchten, müssen Sie eine solche LogoutUrl im Code Ihrer Anwendung implementieren.If you wish to support single sign-out in your application, you must implement such a LogoutUrl in your application's code. Sie können die LogoutUrl über das App-Registrierungsportal festlegen.You can set the LogoutUrl from the app registration portal.

Nächste SchritteNext steps