Microsoft 身分識別平台的使用者資訊端點

發行項
2024/07/08

UserInfo 端點是 OpenID Connect (OIDC) 標準的一部分，旨在傳回已驗證使用者的相關資訊。

尋找 .well-known 設定端點

您可以在 https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration 讀取 OpenID 設定文件的 userinfo_endpoint 欄位，以程式設計方式找出使用者資訊端點。我們不建議您在應用程式中將使用者資訊端點寫入程式碼。請改為使用 OIDC 設定文件，在執行階段尋找此端點。

UserInfo 端點通常是由 OIDC 符合規範程式庫自動呼叫，以取得使用者的相關資訊。透過以 OIDC 標準所識別的宣告清單，Microsoft 身分識別平台可產生名稱宣告、主體宣告和電子郵件 (可用且獲得同意時)。

請考慮改用識別碼權杖

識別碼權杖中的資訊是使用者資訊端點上可用資訊的超集。因為您可以在取得權杖以呼叫使用者資訊端點的同時取得識別碼權杖，所以建議從權杖取得使用者的資訊，而不是呼叫 UserInfo 端點。使用識別碼權杖而不是呼叫使用者資訊端點時，最多會排除兩個網路要求，以降低應用程式的延遲。

如果您需要更多有關使用者的詳細資料 (例如主管或職稱)，請呼叫 Microsoft Graph /user API。您也可以使用選擇性宣告，在識別碼和存取權杖中包含額外的使用者資訊。

呼叫使用者資訊端點

使用者資訊是由 Microsoft Graph 裝載的標準 OAuth 持有人權杖 API。呼叫 UserInfo 端點的方式與呼叫任何 Microsoft Graph API 的方式相同，即使用應用程式在要求存取 Microsoft Graph 時收到的存取權杖。使用者資訊端點會傳回 JSON 回應，其中包含使用者的相關宣告。

權限

使用下列 OIDC 權限來呼叫使用者資訊 API。 openid 宣告是必要的，且 profile 和 email 範圍可確保回應中提供其他資訊。

權限類型	權限
已委派 (工作或學校帳戶)	`openid` (必要)、`profile`、`email`
已委派（個人 Microsoft 帳戶）	`openid` (必要)、`profile`、`email`
申請	不適用

提示

在您的瀏覽器中複製此 URL，以取得使用者資訊端點的存取權杖和識別碼權杖。將用戶端識別碼和重新導向 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 帳戶使用者登入，則會是加密的權杖格式。不過，這些因素都不會影響應用程式在對使用者資訊端點發出的要求中使用存取權杖的能力。

呼叫 API

使用者資訊 API 同時支援 GET 和 POST 要求。

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

使用者資訊回應

{
    "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.
}

回應中顯示的宣告是使用者資訊端點可能傳回的所有宣告。這些值與識別碼權杖中所包含的值相同。

使用者資訊端點的注意事項

您無法新增或自訂使用者資訊端點所傳回的資訊。

若要在驗證和授權期間自訂身分識別平台所傳回的資訊，請使用宣告對應和選擇性宣告來修改安全性權杖設定。

共用方式為