Microsoft 身分識別平台和 OAuth 2.0 資源擁有者密碼認證授與
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) 來登入應用程式，則會遭到封鎖。
- 混合式身分識別同盟案例 (例如，用來驗證內部部署帳戶的 Microsoft Entra ID 和 ADFS) 中不支援 ROPC。 如果以整頁方式將使用者重新導向至內部部署身分識別提供者，則 Microsoft Entra ID 無法測試該身分識別提供者的使用者名稱和密碼。 不過，ROPC 支援傳遞驗證。
- 混合式識別身分同盟案例的例外狀況如下：將 AllowCloudPasswordValidation 設定為 TRUE 的首頁領域探索原則，可讓 ROPC 流程在內部部署密碼同步至雲端時，供同盟使用者使用。 如需詳細資訊，請參閱為舊版應用程式啟用同盟使用者的直接 ROPC 驗證。
- ROPC 流程不支援具有前置或尾端空白字元的密碼。
通訊協定圖表
下圖顯示 ROPC 流程。
授權要求
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 錯誤。 若要解決此錯誤，用戶端應使用 WebView 或瀏覽器將使用者傳送至互動式提示。 |
invalid_request |
要求未正確建構 | /common 或 /consumers 驗證內容不支援授與類型。 請改為使用 /organizations 或租用戶識別碼。 |
深入了解
如需實作 ROPC 流程的範例，請參閱 GitHub 上的 .NET 主控台應用程式程式碼範例。