Microsoft Identity Platform: UserInfo-Endpunkt

Der UserInfo-Endpunkt ist Teil des OpenID Connect (OIDC)-Standards und gibt Informationen zu einem authentifizierten Benutzer zurück. Bei Microsoft Identity Platform wird der UserInfo-Endpunkt von Microsoft Graph (https://graph.microsoft.com/oidc/userinfo) gehostet.

Suchen des bekannten Konfigurationsendpunkts (.well-known)

Sie können programmgesteuert nach dem UserInfo-Endpunkt suchen, indem Sie die Informationen im Feld userinfo_endpoint des OpenID-Konfigurationsdokuments unter https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration lesen. Für den UserInfo-Endpunkt in Ihren Anwendungen wird eine Hartcodierung nicht empfohlen. Verwenden Sie stattdessen das OIDC-Konfigurationsdokument, um den Endpunkt zur Laufzeit zu finden.

Der UserInfo-Endpunkt wird in der Regel automatisch von OIDC-kompatiblen Bibliotheken aufgerufen, um Informationen zum Benutzer abzurufen. Aus der Liste der im OIDC-Standard identifizierten Ansprüche erzeugt Microsoft Identity Platform die Namenansprüche, den Antragstelleranspruch und die E-Mail-Adresse (sofern diese Angaben verfügbar sind und die Einwilligung für sie erteilt wurden).

Erwägen Sie stattdessen die Verwendung eines ID-Tokens

Die Informationen in einem ID-Token sind eine Obermenge der Informationen, die im UserInfo-Endpunkt verfügbar sind. Da Sie ein ID-Token zur gleichen Zeit abrufen können wie ein Token zum Aufrufen des UserInfo-Endpunkts, schlagen wir vor, die Benutzerinformationen aus dem ID-Token statt vom UserInfo-Endpunkt abzurufen. Bei der Verwendung des ID-Tokens anstelle des Aufrufs des UserInfo-Endpunkts werden bis zu zwei Netzwerkanforderungen weniger benötigt, was die Latenz in Ihrer Anwendung reduziert.

Wenn Sie weitere Details zu dem Benutzer wie Manager oder Jobtitel benötigen, rufen Sie die Microsoft Graph /user API auf. Sie können auch optionale Ansprüche verwenden, um zusätzliche Benutzerinformationen in Ihre ID und Zugriffstoken einzubeziehen.

Aufrufen des UserInfo-Endpunkts

UserInfo ist eine standardmäßige OAuth-Bearer-Token-API, die von Microsoft Graph gehostet wird. Rufen Sie den UserInfo-Endpunkt wie eine beliebige Microsoft Graph-API auf, und verwenden Sie dafür das Zugriffstoken, das Ihre Anwendung beim Anfordern des Zugriffs auf Microsoft Graph erhalten hat. Der UserInfo-Endpunkt gibt eine JSON-Antwort zurück, die Ansprüche über den Benutzer enthält.

Berechtigungen

Verwenden Sie die folgenden OIDC-Berechtigungen, um die UserInfo-API aufzurufen. Der Anspruch openid ist erforderlich, und die Bereiche profile und email stellen sicher, dass in der Antwort zusätzliche Informationen bereitgestellt werden.

Berechtigungstyp Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) openid (erforderlich), profile, email
Delegiert (persönliches Microsoft-Konto) openid (erforderlich), profile, email
Application Nicht verfügbar

Tipp

Kopieren Sie diese URL in Ihren Browser, um ein Zugriffstoken für den UserInfo-Endpunkt und ein ID-Token abzurufen. Ersetzen Sie die Client-ID und den Umleitungs-URI durch Werte aus einer App-Registrierung.

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 das Zugriffstoken verwenden, das in der Abfrage im nächsten Abschnitt zurückgegeben wird.

Microsoft Graph verwendet ein spezielles Token-Ausgabemuster, das die Lese- oder Validierungsfähigkeit Ihrer App beeinträchtigen kann. Wie bei anderen Microsoft Graph-Token ist das hier erhaltene Token möglicherweise kein JSON Web Token (JWT), und Ihre App sollte es als nicht transparent betrachten. Wenn Sie einen Microsoft-Kontobenutzer angemeldet haben, wird ein verschlüsseltes Tokenformat verwendet. Keine dieser Faktoren beeinträchtigt jedoch die Fähigkeit Ihrer App, das Zugriffstoken in einer Anforderung an den UserInfo-Endpunkt zu verwenden.

Aufrufen der API

Die UserInfo-API unterstützt sowohl GET- als auch POST-Anforderungen.

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

UserInfo-Antwort

{
    "sub": "OLu859SGc2Sr9ZsqbkG-QbeLgJlb41KcdiPoLYNpSFA",
    "name": "Mikah Ollenburg", // names all require the “profile” scope.
    "family_name": " Ollenburg",
    "given_name": "Mikah",
    "picture": "https://graph.microsoft.com/v1.0/me/photo/$value",
    "email": "mikoll@contoso.com" //requires the “email” scope.
}

Alle in der Antwort angezeigten Ansprüche können vom UserInfo-Endpunkt zurückgegeben werden. Diese Werte entsprechen den Werten in einem ID-Token.

Hinweise und Einschränkungen zum UserInfo-Endpunkt

Sie können die von dem UserInfo-Endpunkt zurückgegebenen Informationen nicht hinzufügen oder anpassen.

Um die von der Identitätsplattform zurückgegebenen Informationen bei der Authentifizierung und Autorisierung anzupassen, verwenden Sie die Anspruchszuordnung und optionale Ansprüche, um die Sicherheitstokenkonfiguration zu ändern.

Nächste Schritte