Microsoft 身分識別平台和 OAuth 2.0 資源擁有者密碼認證

發行項
04/08/2024

Microsoft 身分識別平台支援 OAuth 2.0 資源擁有者密碼認證（ROPC）授與，這可讓應用程式直接處理其密碼來登入使用者。本文說明如何直接針對應用程式中的通訊協議進行程序設計。建議您盡可能改為使用支援的 Microsoft 驗證程式庫 (MSAL)，以取得權杖並呼叫受保護的 Web API。另請參閱使用 MSAL 的範例應用程式。

警告

Microsoft 建議您不要使用 ROPC 流程。在大部分情況下，有更安全的替代方案可供使用，並建議使用。此流程在應用程式中需要非常高的信任度，而且具有在其他流程中不存在的風險。只有當其他更安全的流程無法運作時，才應該使用此流程。

重要

Microsoft 身分識別平台僅支援 Microsoft Entra 租使用者內的 ROPC 授與，而不是個人帳戶。這表示您必須使用租使用者特定的端點（https://login.microsoftonline.com/{TenantId_or_Name}）或 organizations 端點。
受邀加入 Microsoft Entra 租使用者的個人帳戶無法使用 ROPC 流程。
沒有密碼的帳戶無法使用 ROPC 登入，這表示 SMS 登入、FIDO 和 Authenticator 應用程式等功能將無法使用該流程。如果您的應用程式或使用者需要這些功能，請使用 ROPC 以外的授與類型。
如果使用者必須使用多重要素驗證 (MFA) 來登入應用程式，則會遭到封鎖。
混合式身分識別同盟案例不支援 ROPC（例如，用來驗證內部部署帳戶的 Microsoft Entra ID 和 AD FS）。如果以整頁方式將使用者重新導向至內部部署身分識別提供者，則 Microsoft Entra ID 無法測試該身分識別提供者的使用者名稱和密碼。不過，ROPC 支援傳遞驗證。
混合式身分識別同盟案例的例外狀況如下：將 AllowCloudPasswordValidation 設定為 TRUE 的主領域探索原則可讓 ROPC 流程在內部部署密碼同步至雲端時為同盟用戶運作。如需詳細資訊，請參閱為舊版應用程式啟用同盟使用者的直接 ROPC 驗證。
ROPC 流程不支援具有前置或尾端空格符的密碼。

通訊協定圖表

下圖顯示 ROPC 流程。

Diagram showing the resource owner password credential flow

授權要求

ROPC 流程是單一要求;它會將客戶端識別和使用者的認證傳送至識別提供者，並接收傳回的令牌。在這麼做之前，用戶端必須要求使用者的電子郵件地址 (UPN) 和密碼。在成功要求之後，客戶端應該從記憶體中安全地捨棄用戶的認證。絕不會儲存這些認證。

// Line breaks and spaces are for legibility only.  This is a public client, so no secret is required.

POST {tenant}/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=user.read%20openid%20profile%20offline_access
&username=MyUsername@myTenant.com
&password=SuperS3cret
&grant_type=password

參數	條件	描述
`tenant`	必要	您要登入使用者的目錄租使用者。租使用者可以是 GUID 或易記名稱格式。不過，其參數無法設定為 `common` 或 `consumers`，但可能設定為 `organizations`。
`client_id`	必要	Microsoft Entra 系統管理中心 - 應用程式註冊指派給應用程式的應用程式（用戶端）識別碼。
`grant_type`	必要	必須設定為 `password`。
`username`	必要	使用者的電子郵件地址。
`password`	必要	使用者的密碼。
`scope`	建議需求	應用程式需要的範圍或許可權以空格分隔的清單。在互動式流程中，系統管理員或用戶必須事先同意這些範圍。
`client_secret`	有時需要	如果應用程式是公用用戶端，則 `client_secret` 無法包含或 `client_assertion` 。如果應用程式是機密用戶端，則必須包含它。
`client_assertion`	有時需要	使用憑證產生的不同形式 `client_secret`。如需詳細資訊，請參閱憑證認證。

成功的驗證回應

下列範例會顯示成功的權杖回應：

{
    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}

參數	格式	描述
`token_type`	String	設定為 `Bearer`。
`scope`	空格分隔字串	如果傳回存取權杖，此參數會列出存取權杖適用的範圍。
`expires_in`	int	所含存取權杖的有效時間 (以秒為單位)。
`access_token`	不透明字串	針對所要求的範圍發出。
`id_token`	JWT	如果原始 `scope` 參數包含範圍， `openid` 則發出。
`refresh_token`	不透明字串	如果原始 `scope` 參數包含 `offline_access`，則發出。

您可以使用重新整理令牌，使用 OAuth 程式代碼流程檔中所述的相同流程來取得新的存取令牌和重新整理令牌。

警告

請勿在程式代碼中嘗試驗證或讀取您未擁有之任何 API 的令牌，包括此範例中的令牌。 Microsoft 服務的令牌可以使用不會驗證為 JWT 的特殊格式，也可以為取用者（Microsoft 帳戶）使用者加密。雖然讀取令牌是實用的偵錯和學習工具，但請勿在程式代碼中對此採取相依性，或假設您控制之 API 的令牌相關細節。

回覆錯誤

如果使用者未提供正確的使用者名稱或密碼，或用戶端尚未收到要求的同意，驗證將會失敗。

錯誤	描述	用戶端動作
`invalid_grant`	驗證失敗	認證不正確，或用戶端未同意要求的範圍。如果未授與範圍， `consent_required` 則會傳回錯誤。若要解決此錯誤，客戶端應該使用網頁檢視或瀏覽器，將用戶傳送至互動式提示。
`invalid_request`	要求未正確建構	或`/consumers`驗證內容不支援`/common`授與類型。請改用 `/organizations` 或租用戶標識碼。

深入了解

如需 ROPC 流程的範例實作，請參閱 GitHub 上的 .NET 控制台應用程式程式代碼範例。

Microsoft 身分識別平台 和 OAuth 2.0 資源擁有者密碼認證