Microsoft Identity Platform: UserInfo-EndpunktMicrosoft identity platform UserInfo endpoint

Der UserInfo-Endpunkt ist Teil des OpenID Connect-Standards (OIDC), der für die Rückgabe von Ansprüchen über den authentifizierenden Benutzer konzipiert ist.The UserInfo endpoint is part of the OpenID Connect standard (OIDC), designed to return claims about the user that authenticated. Für die Microsoft Identity Platform wird der UserInfo-Endpunkt bei Microsoft Graph (https://graph.microsoft.com/oidc/userinfo) gehostet.For the Microsoft identity platform, the UserInfo endpoint is hosted on Microsoft Graph (https://graph.microsoft.com/oidc/userinfo).

Suchen des bekannten Konfigurationsendpunkts (.well-known)Find the .well-known configuration endpoint

Sie können den UserInfo-Endpunkt mithilfe des OpenID Connect-Discovery-Dokuments unter https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration programmgesteuert ermitteln.You can programmatically discover the UserInfo endpoint using the OpenID Connect discovery document, at https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Er ist im Feld userinfo_endpoint aufgeführt. Sie können dieses Muster cloudübergreifend verwenden, um auf den richtigen Endpunkt zu verweisen.It’s listed in the userinfo_endpoint field, and this pattern can be used across clouds to help point to the right endpoint. Es wird nicht empfohlen, den UserInfo-Endpunkt in Ihrer App hart zu codieren. Verwenden Sie stattdessen das OIDC-Discovery-Dokument, um diesen Endpunkt zur Laufzeit zu suchen.We do not recommend hard-coding the UserInfo endpoint in your app – use the OIDC discovery document to find this endpoint at runtime instead.

Als Teil der OpenID Connect-Spezifikation wird der UserInfo-Endpunkt häufig von OIDC-konformen Bibliotheken automatisch aufgerufen, um Informationen zum Benutzer zu erhalten.As part of the OpenID Connect specification, the UserInfo endpoint is often automatically called by OIDC compliant libraries to get information about the user. Ohne das Hosting eines solchen Endpunkts wäre Microsoft Identity Platform nicht standardkonform, und bei einigen Bibliotheken würden Fehler auftreten.Without hosting such an endpoint, the Microsoft identity platform would not be standards compliant and some libraries would fail. Aus der Liste der im OIDC-Standard identifizierten Ansprüche erstellen wir die Namensansprüche, den Antragstelleranspruch und die E-Mail-Adresse, sofern diese Angaben verfügbar sind und die Einwilligung für sie erteilt wurde.From the list of claims identified in the OIDC standard we produce the name claims, subject claim, and email when available and consented for.

Berücksichtigen Sie dabei Folgendes: Alternative Verwendung eines ID-TokensConsider: Use an ID Token instead

Die im ID-Token verfügbaren Informationen, die Ihre App empfangen kann, sind eine übergeordnete Menge der Informationen, die sie vom UserInfo-Endpunkt abrufen kann.The information available in the ID token that your app can receive is a superset of the information it can get from the UserInfo endpoint. Da Sie ein ID-Token zur gleichen Zeit wie ein Token zum Aufrufen des UserInfo-Endpunkts abrufen können, empfiehlt es sich, Informationen zum Benutzer mithilfe dieses ID-Tokens abzurufen, anstatt den UserInfo-Endpunkt aufzurufen.Because you can get an ID token at the same time you get a token to call the UserInfo endpoint, we suggest that you use that ID token to get information about the user instead of calling the UserInfo endpoint. Durch die Verwendung des ID-Tokens entfallen ein bis zwei Netzwerkanforderungen vom Anwendungsstart, sodass die Latenz der Anwendung verringert wird.Using the ID token will eliminate one to two network requests from your application launch, reducing latency in your application.

Wenn Sie weitere Informationen zum Benutzer benötigen, sollten Sie die Microsoft Graph-API /user aufrufen, um Informationen wie Büronummer oder Position abzurufen.If you require more details about the user, you should call the Microsoft Graph /user API to get information like office number or job title. Sie können auch optionale Ansprüche verwenden, um zusätzliche Benutzerinformationen in Ihre ID und Zugriffstoken einzubeziehen.You can also use optional claims to include additional user information in your ID and access tokens.

Aufrufen des UserInfo-EndpunktsCalling the UserInfo endpoint

UserInfo ist eine Standard-OAuth-Bearertoken-API, die wie jede andere Microsoft Graph-API mithilfe des beim Abrufen eines Tokens für Microsoft Graph erhaltenen Zugriffstokens aufgerufen wird.UserInfo is a standard OAuth Bearer token API, called like any other Microsoft Graph API using the access token received when getting a token for Microsoft Graph. Sie gibt eine JSON-Antwort zurück, die Ansprüche über den Benutzer enthält.It returns a JSON response containing claims about the user.

BerechtigungenPermissions

Verwenden Sie die folgenden OIDC-Berechtigungen, um die UserInfo-API aufzurufen.Use the following OIDC permissions to call the UserInfo API. openid ist erforderlich, und die Bereiche profile und email stellen sicher, dass zusätzliche Informationen in der Antwort bereitgestellt werden.openid is required, and the profile and email scopes ensure that additional information is provided in the response.

BerechtigungstypPermission type BerechtigungenPermissions
Delegiert (Geschäfts-, Schul- oder Unikonto)Delegated (work or school account) OpenID (erforderlich), Profil, E-Mail-Adresseopenid (required), profile, email
Delegiert (persönliches Microsoft-Konto)Delegated (personal Microsoft account) OpenID (erforderlich), Profil, E-Mail-Adresseopenid (required), profile, email
ApplicationApplication Nicht verfügbarNot applicable

Tipp

Kopieren Sie diese URL in Ihren Browser, um ein Token für den UserInfo-Endpunkt und ein ID-Token abzurufen, und ersetzen Sie dabei die Client-ID und den Umleitungs-URI durch Ihre eigenen Werte.Copy this URL in your browser to get a token for the UserInfo endpoint as well as an ID token and replace the client ID and redirect URI with your own. Beachten Sie, dass nur Bereiche für OpenID oder Graph angefordert werden und nichts anderes.Note that it only requests scopes for OpenID or Graph scopes, and nothing else. Dies ist erforderlich, da Sie Berechtigungen nicht für zwei verschiedene Ressourcen in derselben Tokenanforderung anfordern können.This is required, since you cannot request permissions for two different resources in the same token request.

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=<yourClientID>&response_type=token+id_token&redirect_uri=<YourRedirectUri>&scope=user.read+openid+profile+email&response_mode=fragment&state=12345&nonce=678910

Sie können dieses Zugriffstoken im nächsten Abschnitt verwenden.You can use this access token in the next section.

Wie bei anderen Microsoft Graph-Token ist das hier erhaltene Token möglicherweise kein JWT.As with any other Microsoft Graph token, the token you receive here may not be a JWT. Wenn Sie einen Microsoft-Kontobenutzer angemeldet haben, wird ein verschlüsseltes Tokenformat verwendet.If you signed in a Microsoft account user, it will be an encrypted token format. Dies liegt daran, dass Microsoft Graph ein spezielles Tokenausstellungsmuster aufweist.This is because Microsoft Graph has a special token issuance pattern. Die Möglichkeit, das Zugriffstoken zum Aufrufen des UserInfo-Endpunkts zu verwenden, wird dadurch nicht beeinträchtigt.This does not impact your ability to use the access token to call the UserInfo endpoint.

Aufrufen der APICalling the API

Die UserInfo-API unterstützt sowohl GET als auch POST gemäß der OIDC-Spezifikation.The UserInfo API supports both GET and POST, per the OIDC spec.

GET or POST /oidc/userinfo HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJub25jZSI6Il…

UserInfo-AntwortUserInfo response

{
    "sub": "OLu859SGc2Sr9ZsqbkG-QbeLgJlb41KcdiPoLYNpSFA",
    "name": "Mikah Ollenburg", // names all require the “profile” scope.
    "family_name": " Ollenburg",
    "given_name": "Mikah",
    "email": "mikoll@contoso.com" //requires the “email” scope.
}

Bei den hier aufgeführten Ansprüchen handelt es sich um alle Ansprüche, die vom UserInfo-Endpunkt zurückgegeben werden können.The claims listed here are all of the claims that the UserInfo endpoint can return. Dies sind dieselben Werte, die in den ID-Token an die App ausgegeben würden.These are the same values that the app would see in the ID token issued to the app.

Hinweise und Einschränkungen zum UserInfo-EndpunktNotes and caveats on the UserInfo endpoint

  • Wenn Sie diesen UserInfo-Endpunkt aufrufen möchten, müssen Sie den v2.0-Endpunkt verwenden.If you want to call this UserInfo endpoint you must use the v2.0 endpoint. Wenn Sie den v1.0-Endpunkt verwenden, erhalten Sie ein Token für den v1.0-UserInfo-Endpunkt, der unter login.microsoftonline.com gehostet wird.If you use the v1.0 endpoint you will get a token for the v1.0 UserInfo endpoint, hosted on login.microsoftonline.com. Es wird für alle OIDC-konformen Apps und Bibliotheken empfohlen, den v2.0-Endpunkt zu verwenden, um Kompatibilität zu gewährleisten.We recommend that all OIDC compliant apps and libraries use the v2.0 endpoint to ensure compatibility.
  • Die Antwort vom UserInfo-Endpunkt kann nicht angepasst werden.The response from the UserInfo endpoint cannot be customized. Wenn Sie Ansprüche anpassen möchten, bearbeiten Sie die in den Token zurückgegebenen Informationen mithilfe der Anspruchszuordnung.If you’d like to customize claims, please use claims mapping to edit the information returned in the tokens.
  • Der Antwort vom UserInfo-Endpunkt kann nichts hinzugefügt werden.The response from the UserInfo endpoint cannot be added to. Wenn Sie zusätzliche Ansprüche über den Benutzer abrufen möchten, fügen Sie den Token neue optionale Ansprüche hinzu.If you’d like to get additional claims about the user, please use optional claims to add new claims to the tokens.

Nächste SchritteNext Steps