Microsoft ID プラットフォームの UserInfo エンドポイント

[アーティクル]
12/19/2023

OpenID Connect (OIDC) 標準の一部として、UserInfo エンドポイントは、認証されたユーザーに関する情報を返します。

.well-known 構成エンドポイントを探す

OpenID 構成ドキュメントの userinfo_endpoint フィールドを読み取ることで、UserInfo エンドポイントをプログラムで見つけることができます (https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration)。 UserInfo エンドポイントをアプリケーションにハードコーディングすることはお勧めしません。代わりに、OIDC 構成ドキュメントを使用して、実行時にエンドポイントを見つけてください。

UserInfo エンドポイントは、通常、OIDC 準拠のライブラリによって自動的に呼び出され、ユーザーに関する情報を取得します。 Microsoft ID プラットフォームは、OIDC 標準で指定されている要求の一覧から、名前の要求、件名の要求、メールを生成します (利用可能かつ同意が得られている場合)。

代わりに ID トークンを使用することを検討する

ID トークンの情報は、UserInfo エンドポイントで入手できる情報のスーパーセットです。 UserInfo エンドポイントを呼び出すトークンを取得すると、同時に ID トークンを取得できます。このため、UserInfo エンドポイントを呼び出す代わりに、トークンからユーザーの情報を取得することをお勧めします。 UserInfo エンドポイントを呼び出す代わりに ID トークンを使用すると、最大 2 つのネットワーク要求が不要になります。これにより、アプリケーションの待機時間が短縮されます。

上司や役職など、ユーザーの詳細が必要な場合は、Microsoft Graph /user API を呼び出します。このほか、オプションの要求を使用して、ID とアクセストークンに追加のユーザー情報を含めることもできます。

UserInfo エンドポイントを呼び出す

UserInfo は、Microsoft Graph によってホストされる標準の OAuth ベアラートークン API です。アプリケーションが Microsoft Graph へのアクセスを要求したときに受け取ったアクセストークンを使用して、Microsoft Graph API を呼び出す場合と同様に UserInfo エンドポイントを呼び出します。 UserInfo エンドポイントは、ユーザーに関する要求を含む JSON 応答を返します。

アクセス許可

UserInfo API の呼び出しには、OIDC アクセス許可を使用します。 openid 要求は必須です。profile と email は、応答内に情報を追加するためのスコープです。

アクセス許可の種類	アクセス許可
委任済み (職場または学校アカウント)	`openid` (必須)、`profile`、`email`
委任済み (個人用 Microsoft アカウント)	`openid` (必須)、`profile`、`email`
Application	適用なし

ヒント

次の URL をブラウザーにコピーして、UserInfo エンドポイントのアクセストークンと ID トークンを取得します。クライアント ID とリダイレクト URI は、アプリ登録の値に置き換えてください。

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

次のセクションのクエリで返されるアクセストークンを使用できます。

Microsoft Graph では、特殊なトークン発行パターンが使用されます。これは、アプリのトークンの読み取りまたは検証機能に影響を与える可能性があります。他の Microsoft Graph トークンと同様に、ここで受け取るトークンは JWT ではない場合があり、アプリではそのトークンを不透明と見なす必要があります。 Microsoft アカウントユーザーにサインインした場合は、暗号化されたトークン形式になります。ただし、これらの要因はいずれも、UserInfo エンドポイントへの要求でアクセストークンを使用するアプリの機能には影響しません。

API の呼び出し

UserInfo API では、GET 要求と POST 要求の両方がサポートされます。

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

UserInfo の応答

{
    "sub": "OLu859SGc2Sr9ZsqbkG-QbeLgJlb41KcdiPoLYNpSFA",
    "name": "Mikah Ollenburg", // all names 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.
}

応答で示される要求はすべて、UserInfo エンドポイントが返すことができる要求です。これらの値は、ID トークンに含まれる値と同じです。

UserInfo エンドポイントに関する注意事項

UserInfo エンドポイントが返す情報に追加を行うことや、情報をカスタマイズすることはできません。

認証および承認時に ID プラットフォームが返す情報をカスタマイズするには、要求マッピングとオプションの要求を使用して、セキュリティトークンの構成を変更します。

次の方法で共有