Microsoft 身分識別平臺 UserInfo 端點

  • 文章

作為 OpenID 連線 （OIDC） 標準的一部分， UserInfo 端點 會傳回已驗證使用者的相關資訊。

尋找 .well-known 組態端點

您可以在 讀取 userinfo_endpoint OpenID 組態檔的 https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration 欄位，以程式設計方式找到 UserInfo 端點。 不建議在應用程式中硬式編碼 UserInfo 端點。 請改用 OIDC 組態檔，在執行時間尋找端點。

UserInfo 端點通常由 OIDC 相容的程式庫 自動呼叫，以取得使用者的相關資訊。 從 OIDC 標準 中識別的宣告清單中，Microsoft 身分識別平臺會在可用且同意時產生名稱宣告、主旨宣告和電子郵件。

請考慮改用識別碼權杖

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

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

呼叫 UserInfo 端點

UserInfo 是 Microsoft Graph 所裝載的標準 OAuth 持有人權杖 API。 呼叫 UserInfo 端點，因為您會使用應用程式在要求存取 Microsoft Graph 時收到的存取權杖來呼叫任何 Microsoft Graph API。 UserInfo 端點會傳回 JSON 回應，其中包含有關使用者的宣告。

權限

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

權限類型 權限
已委派 (工作或學校帳戶) openid（必要），， profileemail
已委派（個人 Microsoft 帳戶） openid（必要），， profileemail
應用程式 不適用

提示

在瀏覽器中複製此 URL，以取得 UserInfo 端點和識別碼權杖的 存取權杖 。 將用戶端識別碼和重新導向 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 端點可以傳回的宣告。 這些值與識別碼權杖 中包含的 值相同。

UserInfo 端點上的注意事項和注意事項

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

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

下一步