原生驗證 API 參考

適用於：帶有白色核取記號符號的綠色圓圈，表示下列內容適用於外部租用戶。外部租用戶（深入瞭解）

Microsoft Entra 的 native authentication 讓你能在客戶端應用程式中託管應用程式的使用者介面，而非將認證委託給瀏覽器，從而實現原生整合的認證體驗。身為開發人員，您可以完全掌控登入介面的外觀和風格。

此 API 參考文章說明只有在您手動提出執行流程的原始 HTTP 要求時，才需要的詳細資料。不過，我們不建議使用此方法。因此，盡可能使用 Microsoft 建置且支持的驗證 SDK。了解更多關於原生認證 SDK 的資訊。當 API 端點的呼叫成功時，您會收到使用者身分識別的識別碼權杖，以及呼叫受保護 API 的存取權杖。來自 API 的所有回應都是 JSON 格式。

Microsoft Entra 的原生認證 API 支援兩種認證流程的註冊與登入：

具有密碼的電子郵件，支援使用電子郵件和密碼註冊和登入，以及自助式密碼重設 (SSPR)。
- 使用電子郵件地址和密碼登入的用戶，也需同時使用使用者名稱和密碼登入。
電子郵件一次性密碼，支援使用電子郵件一次性密碼註冊和登入。

注意

目前，原生驗證 API 端點不支援跨原始來源資源分享 (CORS)。

必要條件

一個 Microsoft Entra 外部租戶。如果您尚未擁有外部租用戶，請立即建立。
如果你還沒這麼做，請在Microsoft Entra管理中心註冊申請。請務必：
- 記錄 應用程式（用戶端）識別碼 和 目錄（租使用者）識別碼以供 日後使用。
- 授予應用程式系統管理員同意。
- 啟用公用用戶端和原生驗證流程。
如果你還沒這麼做，在Microsoft Entra管理中心建立使用者流程。建立使用者流程時，請注意你設定的使用者屬性，因為這些屬性是 Microsoft Entra 期望你的應用程式提交的。
將您的應用程式註冊與使用者流程關聯。
登入流程時，註冊一個客戶使用者，用來測試流程。或者，您可以在執行註冊流程之後取得此測試使用者。
針對 SSPR 流程，為客戶租用戶中的外部使用者啟用自助式密碼重設。 SSPR 適用於使用電子郵件搭配密碼驗證方法的客戶使用者。
如果你想讓使用電子郵件地址和密碼登入的用戶也能用使用者名稱和密碼登入，請使用「用別名或使用者名稱登入」文章中的步驟：
1. 登入時啟用使用者名稱。
2. 在管理中心建立使用者名稱，或透過新增使用者名稱更新現有使用者。或者，你也可以使用Microsoft Graph API 來自動化應用程式中的使用者建立與更新。
要為您的客戶強制多重身份驗證（MFA），請使用「新增多重身份驗證（MFA）」中的步驟，將多重身份驗證加入您的登入流程。原生認證支援電子郵件、一次性密碼和簡訊，作為多重身份驗證的第二要素。

接續權杖

每當你呼叫登入、註冊或 SSPR 端點時，回應都會包含 一個延續令牌。此令牌唯一識別當前流程，並讓 Microsoft Entra ID 能在其端點間維持狀態。在該流程的每個後續請求中都包含該標記。它只在有限時間內有效，且只能用於同一流程內後續的請求。

若要完成任一驗證方法的使用者註冊流程，您的應用程式會與四個端點 /signup/v1.0/start、/signup/v1.0/challenge、/signup/v1.0/continue 和 /token 互動。

端點	描述
`/signup/v1.0/start`	此端點會啟動註冊流程。您傳遞有效的應用程式識別碼、新的使用者名稱和查問類型，然後取得新的接續權杖。如果應用程式選擇的認證方法未被 Microsoft Entra 支援，端點可以回傳回應，指示應用程式使用網頁認證流程。
`/signup/v1.0/challenge`	你的應用程式會呼叫這個端點，並列出由 Microsoft Entra 支援的 challenge 類型。接著，Microsoft Entra 會選擇使用者可用的認證方式之一進行認證。
`/signup/v1.0/continue`	此端點可協助繼續流程來建立使用者帳戶，或因為缺少密碼原則需求等需求或錯誤屬性格式而中斷流程。此端點會產生接續權杖，然後將其傳回應用程式。端點可以回傳回應，指示應用程式使用網頁驗證流程，若應用程式未採用 Microsoft Entra 選擇的認證方式。
`oauth/v2.0/token`	應用程式會呼叫此端點，最後要求安全性權杖。應用程式需要使用從最後一次成功呼叫端 `/signup/v1.0/continue` 點取得的延續令牌。

API 允許客戶端應用程式在呼叫 Microsoft Entra 時，宣告其支援的認證方法。若要這樣做，應用程式會使用應用程式要求中的 challenge_type 參數。此參數會保留預先定義的值，代表不同的驗證方法。

深入了解原生驗證查問類型中的查問類型。本文說明您應該用於驗證方法的挑戰類型值。

循序圖示範註冊程序的流程。

註冊流程的原生驗證圖表。

此圖示顯示應用程式會在不同時間（甚至可能在不同畫面）從使用者收集使用者的使用者名稱（電子郵件）、密碼（包含密碼驗證流程的電子郵件）及屬性。不過，你可以設計應用程式在同一畫面收集使用者名稱（電子郵件）、密碼以及所有必需和可選屬性值，然後全部提交給 /signup/v1.0/start 端點。如果應用程式已向端點提交所有所需資訊 /signup/v1.0/start ，應用程式就不需要在可選步驟中呼叫或處理回應。

在第 21 步，使用者已經註冊完成。然而，如果應用程式需要用戶在註冊後自動登入，應用程式會呼叫 oauth/v2.0/token 端點來請求安全令牌。

註冊流程開始時，應用程式會向 /signup/v1.0/start 端點提出 POST 要求，以啟動註冊流程。

以下是請求的範例（我們以多行方式呈現，以便閱讀）：

範例 1：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&username=contoso-consumer@contoso.com

範例 2 (在要求中包含使用者屬性和密碼)：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&password={secure_password}
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postalCode": "{user_postal_code}"}
&username=contoso-consumer@contoso.com

參數	必要	描述
`tenant_subdomain`	是的	您所建立的外部租用戶的子網域。在 URL 中，將 `{tenant_subdomain}` 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。
`client_id`	是的	你在 Microsoft Entra 管理中心註冊的應用程式（客戶端）ID。
`username`	是的	客戶使用者要用來註冊的電子郵件，例如 contoso-consumer@contoso.com。
`challenge_type`	是的	應用程式支援的授權查問類型字串清單 (以空格分隔)，例如 `oob password redirect`。清單必須一律包含 `redirect` 查問類型。該值必須是 `oob redirect` 或 `oob password redirect` 用於具有密碼驗證方法的電子郵件。
`password`	否	應用程式從客戶使用者收集的密碼值。您可以在 `/signup/v1.0/start` 端點中，透過 `/signup/v1.0/continue` 或更新版本提交使用者的密碼。以應用程式從客戶使用者收集的密碼值取代 `{secure_password}`。您必須負責確認使用者想要使用的密碼，方法是在應用程式的 UI 中提供密碼確認欄位。您也必須確定使用者知道根據組織的原則，哪些內容構成強密碼。了解更多關於 Microsoft Entra 的密碼政策。此參數僅適用於具有密碼驗證方法的電子郵件。
`attributes`	否	應用程式從客戶使用者收集的使用者屬性值。該值是字串，但格式化為 JSON 物件，其索引鍵值是使用者屬性的可程式化名稱。這些屬性可以是內建或自訂，也可以是必要或選擇性的屬性。物件的金鑰名稱取決於管理員在 Microsoft Entra 管理中心設定的屬性。您可以在 `/signup/v1.0/start` 端點中，透過 `/signup/v1.0/continue` 端點或更新版本提交部分或所有使用者屬性。如果您透過 `/signup/v1.0/start` 端點提交所有必要屬性，則不需要在 `/signup/v1.0/continue` 端點中提交任何屬性。不過，如果您透過 `/signup/v1.0/start` 端點提交了一些必要屬性，稍後可以在 `/signup/v1.0/continue` 端點中提交其餘的必要屬性。將 `{given_name}`、`{user_age}` 和 `{postal_code}` 分別取代為應用程式從客戶使用者收集的名稱、年齡和郵遞區號值。 Microsoft Entra 會忽略你提交的任何屬性，這些屬性不存在。
`capabilities`	否	空格分隔的旗標描述客戶端應用程式的功能。雖然 `challenge_type` 定義了哪些方法可以被挑戰，但 `capabilities` 告訴原生認證 API 客戶端應用程式能處理哪些額外流程，以及可以向使用者顯示哪些 UI。例如，代表 `mfa_required` 另一個 `/challenge` 和 `/token` 迴圈; `registration_required` 代表客戶端應用程式呼叫註冊 API，並顯示註冊介面。如果客戶端應用程式沒有宣告某項所需功能，API 會回傳 redirect。支援的值為 `mfa_required` 和 `registration_required`。了解更多關於能力的資訊。

成功回應

以下是成功回應的範例：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "AQABAAEAAA…",
}

房產	描述
`continuation_token`	Continuation token Microsoft Entra回傳。

重定向反應

如果客戶端應用程式不支援 Microsoft Entra 所需的認證方式或功能，則需要回退到網頁驗證流程。在這種情況下，Microsoft Entra 會透過回應中回傳 redirect 挑戰類型來通知應用程式：

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}

房產	描述
`challenge_type`	Microsoft Entra 回傳一個具有挑戰類型的回應。此查問類型的值是重新導向，可讓應用程式使用 Web 型驗證流程。

此回應視為成功，但應用程式必須切換至 Web 型驗證流程。在此情況下，建議您使用 Microsoft 建置且支援的驗證程式庫。

回覆錯誤

範例：

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "user_already_exists", 
    "error_description": "AADSTS1003037: It looks like you may already have an account.... .\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...", 
    "error_codes": [ 
        1003037 
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

房產	描述
`error`	可用於將錯誤分類的錯誤碼字串，並回應錯誤。
`error_description`	可協助您識別驗證錯誤原因的特定錯誤訊息。
`error_codes`	一份 Microsoft Entra 專屬錯誤代碼清單，能幫助你診斷錯誤。
`timestamp`	錯誤發生時間。
`trace_id`	要求的唯一識別碼，可協助您診斷錯誤。
`correlation_id`	有助於跨元件診斷的要求唯一識別碼。
`invalid_attributes`	驗證失敗的屬性清單 (物件陣列)。當應用程式提交使用者屬性且 `suberror` 屬性值為 attribute_validation_failed時，此回應是可能的。
`suberror`	錯誤碼字串，可用來進一步分類錯誤類型。

以下是您可能遇到的錯誤（屬性的可能值 error ）：

錯誤值	描述
`invalid_request`	要求參數驗證失敗，例如當 challenge_type 參數的值包含不支援的驗證方法，或要求不包含 `client_id` 參數時，用戶端識別碼的值是空的或無效的值。使用 `error_description` 參數來瞭解錯誤的確切原因。
`invalid_client`	應用程式在要求中包含的用戶端識別碼是針對缺少原生驗證組態的應用程式，例如不是公用用戶端或未啟用原生驗證。利用該 `suberror` 屬性來了解錯誤的確切原因。
`unauthorized_client`	要求中使用的用戶端識別碼具有有效的用戶端識別碼格式，但不存在於外部租用戶中或不正確。
`unsupported_challenge_type`	`challenge_type` 參數值不包含 `redirect` 查問類型。
`user_already_exists`	使用者已經存在。
`invalid_grant`	應用程式提交的密碼不符合所有複雜度需求，例如密碼太短。利用該 `suberror` 屬性來了解錯誤的確切原因。此參數僅適用於具有密碼驗證方法的電子郵件。

若誤差參數值為 invalid_grant，Microsoft Entra 的回應包含 suberror 性質。以下是suberror錯誤時該性質可能的值：

Suberror 值	描述
`password_too_weak`	密碼強度太弱，因為它不符合複雜度需求。了解更多關於 Microsoft Entra 的密碼政策。如果應用程式提交了使用者密碼，則可能出現此回應。
`password_too_short`	新密碼少於 8 個字元。了解更多關於 Microsoft Entra 的密碼政策。如果應用程式提交了使用者密碼，則可能出現此回應。
`password_too_long`	新密碼超過 256 個字元。了解更多關於 Microsoft Entra 的密碼政策。如果應用程式提交了使用者密碼，則可能出現此回應。
`password_recently_used`	新密碼不得與最近使用的密碼相同。了解更多關於 Microsoft Entra 的密碼政策。如果應用程式提交了使用者密碼，則可能出現此回應。
`password_banned`	新密碼包含禁止的字詞、片語或模式。了解更多關於 Microsoft Entra 的密碼政策。如果應用程式提交了使用者密碼，則可能出現此回應。
`password_is_invalid`	密碼無效，例如，因為它使用不允許的字元。了解更多關於 Microsoft Entra 的密碼政策。如果應用程式提交了使用者密碼，則可能出現此回應。

若誤差參數值為 invalid_client，Microsoft Entra 的回應包含 suberror 性質。以下是suberror錯誤時該性質可能的值：

Suberror 值	描述
`nativeauthapi_disabled`	未啟用原生驗證的應用程式的用戶端識別碼。

注意

如果您透過 /signup/v1.0/start 端點提交所有必要屬性，但並非所有選擇性屬性，您稍後將無法透過 /signup/v1.0/continue 端點提交任何其他選擇性屬性。 Microsoft Entra 不會明確要求可選屬性，因為這些屬性並非註冊流程完成的必要條件。請參閱將使用者屬性提交至端點一節中的表格，以了解您可以提交至 /signup/v1.0/start 和 /signup/v1.0/continue 端點的使用者屬性。

步驟 2：選取驗證方法

應用程式會要求 Microsoft Entra 選擇使用者可透過的支援挑戰類型進行驗證。若要這樣做，應用程式會呼叫 /signup/v1.0/challenge 端點。應用程式必須包含它從要求中的 /signup/v1.0/start 端點取得的接續權杖。

以下是要求的範例 (我們以多行呈現範例要求，以取得可讀性)：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…

參數	必要	描述
`tenant_subdomain`	是的	您所建立的外部租用戶的子網域。在 URL 中，將 `{tenant_subdomain}` 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。
`client_id`	是的	你在 Microsoft Entra 管理中心註冊的應用程式（客戶端）ID。
`challenge_type`	否	應用程式支援的授權查問類型字串清單 (以空格分隔)，例如 `oob password redirect`。清單必須一律包含 `redirect` 查問類型。對於電子郵件一次性密碼，該值預期為 `oob redirect`，對於具有密碼驗證方法的電子郵件，該值為 `oob password redirect`。
`continuation_token`	是的	Continuation token，Microsoft Entra在上一次請求中回傳。

成功回應

Microsoft Entra會將一次性密碼發送到使用者的電子郵件，然後回覆挑戰類型，並以oob及關於一次性密碼的額外資訊回覆：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "interval": 300,
    "continuation_token": "AQABAAEAAAYn...",
    "challenge_type": "oob",
    "binding_method": "prompt",
    "challenge_channel": "email",
    "challenge_target_label": "c***r@co**o**o.com",
    "code_length": 8
}

房產	描述
`interval`	應用程式在嘗試重新傳送 OTP 之前，必須等候的時間長度，以秒為單位。
`continuation_token`	Continuation token Microsoft Entra回傳。
`challenge_type`	為使用者選取以進行驗證的查問類型。
`binding_method`	唯一有效的值是 prompt。這個參數未來可以用來為使用者提供更多方式來輸入一次性密碼。如果 `challenge_type` 為 oob，則發出
`challenge_channel`	傳送一次性密碼的通道類型。目前僅支援電子郵件頻道。
`challenge_target_label`	模糊化的電子郵件，其中傳送了一次性密碼。
`code_length`	Microsoft Entra 產生的一次性密碼長度。

重定向反應

HTTP/1.1 200 OK
Content-Type: application/json

{
   "challenge_type": "redirect"
}

房產	描述
`challenge_type`	Microsoft Entra 回傳一個具有挑戰類型的回應。此查問類型的值是重新導向，可讓應用程式使用 Web 型驗證流程。

此回應視為成功，但應用程式必須切換至 Web 型驗證流程。在此情況下，建議您使用 Microsoft 建置且支援的驗證程式庫。

回覆錯誤

範例：

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

房產	描述
`error`	可用於將錯誤分類的錯誤碼字串，並回應錯誤。
`error_description`	可協助您識別驗證錯誤原因的特定錯誤訊息。
`error_codes`	一份 Microsoft Entra 專屬錯誤代碼清單，能幫助你診斷錯誤。
`timestamp`	錯誤發生時間。
`trace_id`	要求的唯一識別碼，可協助您診斷錯誤。
`correlation_id`	有助於跨元件診斷的要求唯一識別碼。

以下是您可能遇到的錯誤（屬性的可能值 error ）：

錯誤值	描述
`invalid_request`	要求參數驗證失敗，例如用戶端識別碼是空的或無效的。
`expired_token`	接續權杖已過期。
`unsupported_challenge_type`	`challenge_type` 參數值不包含 `redirect` 查問類型。
`invalid_grant`	接續權杖無效。

步驟 3：提交一次性密碼

應用程式會提交傳送到使用者電子郵件的一次性密碼。由於我們提交一次性密碼，因此需要 oob 參數，而且 grant_type 參數的值必須為 oob。

以下是要求的範例 (我們以多行呈現範例要求，以取得可讀性)：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=oob 
&oob={otp_code}

參數	必要	描述
`tenant_subdomain`	是的	您所建立的外部租用戶的子網域。在 URL 中，將 `{tenant_subdomain}` 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。
`continuation_token`	是的	Continuation token，Microsoft Entra在上一次請求中回傳。
`client_id`	是的	你在 Microsoft Entra 管理中心註冊的應用程式（客戶端）ID。
`grant_type`	是的	`/signup/v1.0/continue` 端點的要求可用來提交一次性密碼、密碼或使用者屬性。在此情況下，會使用 `grant_type` 值來區分這三個使用案例。 grant_type 可能的值為 oob、password、attributes。在此呼叫中，由於我們傳送了一次性密碼，因此該值應為 oob。
`oob`	是的	客戶使用者在其電子郵件中收到的一次性密碼。以客戶使用者在其電子郵件中收到的一次性密碼值取代 `{otp_code}`。若要重新傳送一次性密碼，應用程式必須再次向 `/signup/v1.0/challenge` 端點提出要求。

一旦應用程式成功提交一次性密碼，註冊流程會視案例而定，如下所示：

案例	如何繼續進行
應用程式透過 `/signup/v1.0/start` 端點成功提交使用者密碼（電子郵件及密碼驗證方法），且管理中心未Microsoft Entra設定任何屬性，或透過 `/signup/v1.0/start` 端點提交所有必需的使用者屬性。	Microsoft Entra 會發行一個延續令牌。應用程式可以使用續權杖來請求安全權杖，如請求安全權杖所示。
應用程式會透過 `/signup/v1.0/start` 成功提交使用者的密碼（電子郵件時使用密碼驗證方法），但並未提交所有必要的使用者屬性，Microsoft Entra該欄位指示應用程式需要提交的屬性，如user attributes required所示。	應用程式必須透過 `/signup/v1.0/continue` 端點提交必要的使用者屬性。回應與 [所需的使用者屬性] 中的回應類似。提交顯示在 [提交使用者屬性] 中的使用者屬性。
應用程式不會透過 `/signup/v1.0/start` 端點提交使用者的密碼 (用於使用密碼驗證方法的電子郵件)。	Microsoft Entra 的回覆指出需要憑證。請參閱回應。這個回應適用於密碼驗證方法的電子郵件。

回應

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "credential_required",
    "error_description": "AADSTS55103: Credential required. Trace ID: d6966055-...-80500 Correlation ID: 3944-...-60d6 Timestamp: yy-mm-dd 02:37:33Z",
    "error_codes": [
        55103
    ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABEQEAAAA..."
}

房產	描述
`error`	可用於將錯誤分類的錯誤碼字串，並回應錯誤。
`error_description`	可協助您識別驗證錯誤原因的特定錯誤訊息。
`error_codes`	一份 Microsoft Entra 專屬錯誤代碼清單，能幫助你診斷錯誤。
`timestamp`	錯誤發生時間。
`trace_id`	要求的唯一識別碼，可協助您診斷錯誤。
`correlation_id`	有助於跨元件診斷的要求唯一識別碼。
`continuation_token`	Continuation token Microsoft Entra回傳。
`suberror`	錯誤碼字串，可用來進一步分類錯誤類型。

以下是您可能遇到的錯誤（屬性的可能值 error ）：

錯誤值	描述
`credential_required`	建立帳戶時需要驗證，因此您必須呼叫 `/signup/v1.0/challenge` 端點，才能判斷使用者必須提供的認證。
`invalid_request`	要求參數驗證失敗，例如驗證接續權杖失敗，或要求未包含 `client_id` 參數時，用戶端識別碼的值為空白或無效，或外部租用戶系統管理員尚未為所有租用戶使用者啟用電子郵件 OTP。
`invalid_grant`	要求中包含的授與類型無效或未受支援，或 OTP 值不正確。
`expired_token`	要求中包含的接續權杖已過期。

若誤差參數值為 invalid_grant，Microsoft Entra 的回應包含 suberror 性質。以下是suberror錯誤時該性質可能的值：

Suberror 值	描述
`invalid_oob_value`	一次性密碼的值無效。

若要從使用者收集密碼認證，應用程式必須呼叫 /signup/v1.0/challenge 端點，以判斷使用者必須提供的認證。

以下是要求的範例 (我們以多行呈現範例要求，以取得可讀性)：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…

參數	必要	描述
`tenant_subdomain`	是的	您所建立的外部租用戶的子網域。在 URL 中，將 `{tenant_subdomain}` 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。
`client_id`	是的	你在 Microsoft Entra 管理中心註冊的應用程式（客戶端）ID。
`challenge_type`	否	應用程式支援的授權查問類型字串清單 (以空格分隔)，例如 `oob password redirect`。清單必須一律包含 `redirect` 查問類型。對於附密碼電子郵件的註冊流程，此值預期會包含 `password redirect`。
`continuation_token`	是的	Continuation token，Microsoft Entra在上一次請求中回傳。

成功回應

如果密碼是 Microsoft Entra 管理中心為使用者設定的驗證方式，應用程式會回傳一個帶有延續權杖的成功回應。

HTTP/1.1 200 OK
Content-Type: application/json

{
    "challenge_type": "password",
    "continuation_token": " AQABAAEAAAAty..."
}

房產	描述
`challenge_type`	密碼會在所需認證的回應中傳回。
`continuation_token`	Continuation token Microsoft Entra回傳。

重定向反應

HTTP/1.1 200 OK
Content-Type: application/json

{     
    "challenge_type": "redirect" 
}

房產	描述
`challenge_type`	Microsoft Entra 回傳一個具有挑戰類型的回應。此查問類型的值是重新導向，可讓應用程式使用 Web 型驗證流程。

此回應視為成功，但應用程式必須切換至 Web 型驗證流程。在此情況下，建議您使用 Microsoft 建置且支援的驗證程式庫。

應用程式需要提交使用者的憑證，這裡指的是 Microsoft Entra 在前一步要求的密碼。如果應用程式未透過 /signup/v1.0/start 端點這麼做，就必須提交密碼認證。應用程式向 /signup/v1.0/continue 端點提出要求，以提交密碼。由於我們提交密碼，因此需要 password 參數，而且 grant_type 參數的值必須為密碼。

以下是要求的範例 (我們以多行呈現範例要求，以取得可讀性)：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=password 
&password={secure_password}

參數	必要	描述
`tenant_subdomain`	是的	您所建立的外部租用戶的子網域。在 URL 中，將 `{tenant_subdomain}` 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。
`continuation_token`	是的	Continuation token Microsoft Entra在前一步回傳。
`client_id`	是的	你在 Microsoft Entra 管理中心註冊的應用程式（客戶端）ID。
`grant_type`	是的	`/signup/v1.0/continue` 端點的要求可用來提交一次性密碼、密碼或使用者屬性。在此情況下，會使用 `grant_type` 值來區分這三個使用案例。 grant_type 可能的值為 oob、password、attributes。在此呼叫中，由於我們傳送使用者的密碼，因此該值應為密碼。
`password`	是的	應用程式從客戶使用者收集的密碼值。以應用程式從客戶使用者收集的密碼值取代 `{secure_password}`。您必須負責確認使用者想要使用的密碼，方法是在應用程式的 UI 中提供密碼確認欄位。您也必須確定使用者知道根據組織的原則，哪些內容構成強密碼。了解更多關於 Microsoft Entra 的密碼政策。

成功回應

如果請求成功，但管理中心未設定屬性，或Microsoft Entra /signup/v1.0/start端點提交所有所需屬性，應用程式會獲得續寫令牌，無需提交任何屬性。應用程式可以使用續權杖來請求安全權杖，如請求安全權杖所示。否則，Microsoft Entra 的回應顯示應用程式需要提交所需的屬性。這些屬性，不論內建或自訂，都是由租戶管理員在 Microsoft Entra 管理中心設定的。

需要使用者屬性

此回應要求應用程式提交姓名、年齡及手機屬性的數值。

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "attributes_required",
    "error_description": "User attributes required",
    "error_codes": [
            55106
        ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABAAEAAAAtn...",
    "required_attributes": [
        {
            "name": "displayName",
            "type": "string",
            "required": true,
            "options": {
              "regex": ".*@.**$"
            }
        },
        {
            "name": "extension_2588abcdwhtfeehjjeeqwertc_age",
            "type": "string",
            "required": true
        },
        {
            "name": "postalCode",
            "type": "string",
            "required": true,
            "options": {
              "regex":"^[1-9][0-9]*$"
            }
        }
    ],
}

注意

自訂屬性 (也稱為目錄延伸模組) 的命名慣例為 extension_{appId-without-hyphens}_{attribute-name}，其中 {appId-without-hyphens} 是 延伸模組應用程式 用戶端識別碼的移除版本。例如，如果 延伸模組應用程式 的用戶端識別碼為 2588a-bcdwh-tfeehj-jeeqw-ertc，且屬性名稱為 hobbies，則自訂屬性會命名為 extension_2588abcdwhtfeehjjeeqwertc_hobbies。深入瞭解自訂屬性和延伸模組應用程式。

房產	描述
`error`	此屬性是設定在 Microsoft Entra 無法建立使用者帳號，因為需要驗證或提交屬性時設定。
`error_description`	可協助您識別錯誤原因的特定錯誤訊息。
`error_codes`	一份 Microsoft Entra 專屬錯誤代碼清單，能幫助你診斷錯誤。
`timestamp`	錯誤發生時間。
`trace_id`	要求的唯一識別碼，可協助您診斷錯誤。
`correlation_id`	有助於跨元件診斷的要求唯一識別碼。
`continuation_token`	Continuation token Microsoft Entra回傳。
`required_attributes`	應用程式需要提交，下一個呼叫才能繼續的屬性清單 (物件陣列)。這些屬性是應用程式除了使用者名稱以外需要提交的額外屬性。 Microsoft Entra包含此參數為響應，若`error`參數的值為attributes_required。

以下是您可能遇到的錯誤（屬性的可能值 error ）：

錯誤值	描述
`invalid_request`	要求參數驗證失敗，例如驗證接續權杖失敗，或要求未包含 `client_id` 參數時，用戶端識別碼值為空白或無效。
`invalid_grant`	要求中包含的授與類型無效或未受支援。 `grant_type` 可能的值為 oob、password、attributes
`expired_token`	要求中包含的接續權杖已過期。
`attributes_required`	需要一或多個使用者屬性。

重定向反應

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}

房產	描述
`challenge_type`	Microsoft Entra 回傳一個具有挑戰類型的回應。此查問類型的值是重新導向，可讓應用程式使用 Web 型驗證流程。

此回應視為成功，但應用程式必須切換至 Web 型驗證流程。在此情況下，建議您使用 Microsoft 建置且支援的驗證程式庫。

回覆錯誤

範例：

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "invalid_grant",
    "error_description": "New password is too weak",
    "error_codes": [
        399246
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
    "suberror": "password_too_weak"
}

房產	描述
`error`	可用於將錯誤分類的錯誤碼字串，並回應錯誤。
`error_description`	可協助您識別驗證錯誤原因的特定錯誤訊息。
`error_codes`	一份 Microsoft Entra 專屬錯誤代碼清單，能幫助你診斷錯誤。
`timestamp`	錯誤發生時間。
`trace_id`	要求的唯一識別碼，可協助您診斷錯誤。
`correlation_id`	有助於跨元件診斷的要求唯一識別碼。
`suberror`	錯誤碼字串，可用來進一步分類錯誤類型。

以下是您可能遇到的錯誤（屬性的可能值 error ）：

錯誤值	描述
`invalid_request`	要求參數驗證失敗，例如當 `challenge_type` 參數包含無效的查問類型時。
`invalid_grant`	提交的授與無效，例如提交的密碼太短。利用該 `suberror` 屬性來了解錯誤的確切原因。
`expired_token`	接續權杖已過期。
`attributes_required`	需要一或多個使用者屬性。

若誤差參數值為 invalid_grant，Microsoft Entra 的回應包含 suberror 性質。以下是該性質可能的 suberror 值：

Suberror 值	描述
`password_too_weak`	密碼強度太弱，因為它不符合複雜度需求。了解更多關於 Microsoft Entra 的密碼政策。
`password_too_short`	新密碼少於 8 個字元。了解更多關於 Microsoft Entra 的密碼政策。
`password_too_long`	新密碼超過 256 個字元。了解更多關於 Microsoft Entra 的密碼政策。
`password_recently_used`	新密碼不得與最近使用的密碼相同。了解更多關於 Microsoft Entra 的密碼政策。
`password_banned`	新密碼包含禁止的字詞、片語或模式。了解更多關於 Microsoft Entra 的密碼政策。
`password_is_invalid`	密碼無效，例如，因為它使用不允許的字元。了解更多關於 Microsoft Entra 的密碼政策。如果應用程式提交了使用者密碼，則可能出現此回應。

提交使用者屬性

若要繼續進行流程，應用程式必須呼叫 /signup/v1.0/continue 端點以提交必要的使用者屬性。由於我們提交屬性，因此需要 attributes 參數，而且 grant_type 參數的值必須等於 attributes。

以下是要求的範例 (我們以多行呈現範例要求，以取得可讀性)：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=attributes 
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postalCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...

參數	必要	描述
`tenant_subdomain`	是的	您所建立的外部租用戶的子網域。在 URL 中，將 `{tenant_subdomain}` 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。
`continuation_token`	是的	Continuation token，Microsoft Entra在上一次請求中回傳。
`client_id`	是的	你在 Microsoft Entra 管理中心註冊的應用程式（客戶端）ID。
`grant_type`	是的	`/signup/v1.0/continue` 端點的要求可用來提交一次性密碼、密碼或使用者屬性。在此情況下，會使用 `grant_type` 值來區分這三個使用案例。 grant_type 可能的值為 oob、password、attributes。在此呼叫中，由於我們要傳送使用者屬性，因此該值應為 attributes。
`attributes`	是的	應用程式從客戶使用者收集的使用者屬性值。該值是字串，但格式化為 JSON 物件，其索引鍵值是內建或自訂使用者屬性的名稱。物件的金鑰名稱取決於管理員在 Microsoft Entra 管理中心設定的屬性。將 `{given_name}`、`{user_age}` 和 `{postal_code}` 分別取代為應用程式從客戶使用者收集的名稱、年齡和郵遞區號值。 Microsoft Entra 會忽略你提交的任何屬性，這些屬性不存在。

成功回應

如果請求成功，Microsoft Entra 會為使用者註冊，然後發出延續令牌。應用程式可以使用延續權杖向 oauth/v2.0/token 端點請求安全權杖。

HTTP/1.1 200 OK
Content-Type: application/json

{  
    "continuation_token": "AQABAAEAAAYn..."
}

房產	描述
`continuation_token`	Continuation token Microsoft Entra回傳。

重定向反應

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}

房產	描述
`challenge_type`	Microsoft Entra 回傳一個具有挑戰類型的回應。此查問類型的值是重新導向，可讓應用程式使用 Web 型驗證流程。

此回應視為成功，但應用程式必須切換至 Web 型驗證流程。在此情況下，建議您使用 Microsoft 建置且支援的驗證程式庫。

回覆錯誤

範例：

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "expired_token",
    "error_description": "AADSTS901007: The continuation_token is expired.  .\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...", 
    "error_codes": [
        552003
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd" 
}

房產	描述
`error`	可用於將錯誤分類的錯誤碼字串，並回應錯誤。
`error_description`	可協助您識別驗證錯誤原因的特定錯誤訊息。
`error_codes`	一份 Microsoft Entra 專屬錯誤代碼清單，能幫助你診斷錯誤。
`timestamp`	錯誤發生時間。
`trace_id`	要求的唯一識別碼，可協助您診斷錯誤。
`correlation_id`	有助於跨元件診斷的要求唯一識別碼。
`continuation_token`	Continuation token Microsoft Entra回傳。
`unverified_attributes`	必須驗證的屬性索引鍵名稱清單 (物件陣列)。當 `error` 參數的值為 verification_required 時，這個參數會包含在回應中。
`required_attributes`	應用程式需要提交的屬性的清單 (物件陣列)。當 `error` 參數的值為 attributes_required時，Microsoft Entra 會在回應中包含此參數。
`invalid_attributes`	驗證失敗的屬性清單 (物件陣列)。當 `suberror` 屬性價值 attribute_validation_failed時，這個參數會包含在回應中。
`suberror`	錯誤碼字串，可用來進一步分類錯誤類型。

以下是您可能遇到的錯誤（屬性的可能值 error ）：

錯誤值	描述
`invalid_request`	要求參數驗證失敗，例如驗證接續權杖失敗，或要求未包含 `client_id` 參數時，用戶端識別碼值為空白或無效。
`invalid_grant`	提供的授與類型無效或支援或驗證失敗，例如屬性驗證失敗。利用該 `suberror` 屬性來了解錯誤的確切原因。
`expired_token`	要求中包含的接續權杖已過期。
`attributes_required`	需要一或多個使用者屬性。

若誤差參數值為 invalid_grant，Microsoft Entra 的回應包含 suberror 性質。以下是suberror錯誤時該性質可能的值：

Suberror 值	描述
`attribute_validation_failed`	使用者屬性驗證失敗。 `invalid_attributes` 參數包含無法驗證的屬性清單(物件陣列)。

若用戶註冊後必須自動登入，應用程式會向端點發出 POST 請求 oauth/v2.0/token ，並提供前一步取得的續權杖以取得安全權杖。學習如何呼叫 token 端點。

將使用者屬性提交至端點

在 Microsoft Entra 管理中心，你可以設定使用者屬性為必需或選擇。此設定決定了 Microsoft Entra 在您呼叫端點時的回應方式。完成註冊流程並不需要選擇性屬性。因此，當所有屬性均為選擇性屬性時，必須先提交這些屬性，才能驗證使用者名稱。否則，註冊會完成，但不含選擇性屬性。

下表總結了何時可以向 Microsoft Entra 端點提交使用者屬性。

端點	必要屬性	選用屬性	必要和選擇性屬性兩者
`/signup/v1.0/start` 端點	是的	是的	是的
使用者名稱驗證之前的 `/signup/v1.0/continue` 端點	是的	是的	是的
使用者名稱驗證之後的 `/signup/v1.0/continue` 端點	是的	否	是的

使用者屬性值的格式

你可以在 Microsoft Entra 管理中心設定使用者流程設定中指定你想從使用者那裡收集的資訊。使用在註冊期間收集自訂使用者屬性這篇文章，瞭解如何收集內建和自訂屬性的值。

您也可以為您所設定的屬性指定 使用者輸入類型。下表總結了支援的使用者輸入類型，以及如何將 UI 控制項收集的值提交給 Microsoft Entra。

使用者輸入類型	提交值的格式
文字框	職稱等單一值，軟體工程師。
SingleRadioSelect	單一值，例如語言，挪威文。
CheckboxMultiSelect	一或多個值，例如一項或多項或愛好、舞蹈或舞蹈、游泳、旅行。

以下是示範如何提交屬性值的範例要求：

POST /{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue HTTP/1.1
Host: {tenant_subdomain}.ciamlogin.com
Content-Type: application/x-www-form-urlencoded
 
continuation_token=ABAAEAAAAtfyo... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=attributes 
&attributes={"jobTitle": "Software Engineer", "extension_2588abcdwhtfeehjjeeqwertc_language": "Norwegian", "extension_2588abcdwhtfeehjjeeqwertc_hobbies": "Dancing,Swimming,Traveling"}
&continuation_token=AQABAAEAAAAtn...

若要深入了解使用者屬性輸入類型，請參閱自訂使用者屬性輸入類型一文。

如何參考使用者屬性

當您建立註冊使用者流程時，您會設定想要在註冊期間從使用者收集的使用者屬性。 Microsoft Entra 管理中心的使用者屬性名稱與你在原生認證 API 中引用的方式不同。

例如，Microsoft Entra管理中心的 Display Name 在 API 中稱為 displayName。

使用使用者設定檔屬性這篇文章，瞭解如何在原生驗證 API 中參考內建和自訂使用者屬性。

用戶必須使用用來註冊的驗證方法登入。例如，使用密碼驗證方法註冊電子郵件的使用者必須登入電子郵件和密碼。

要請求安全令牌，您的應用程式會與三個端點互動，分別為 oauth/v2.0/initiate、、 oauth/v2.0/challengeoauth/v2.0/token、，且可選地 oauth/v2.0/introspect。

端點	描述
`oauth/v2.0/initiate`	此端點會起始登入流程。如果您的應用程式使用已存在的使用者帳戶的使用者名稱來呼叫它，則會傳回具有接續權杖的成功回應。如果你的應用程式要求使用Microsoft Entra不支援的認證方法，這個端點回應可能會指示應用程式需要使用瀏覽器式的認證流程。
`oauth/v2.0/challenge`	你的應用程式呼叫這個端點，請求Microsoft Entra選擇支援的登入挑戰類型供使用者驗證。當租戶管理員對客戶用戶強制多重驗證時，你的應用程式會呼叫這個端點，向使用者提出第二因素驗證的挑戰。
`oauth/v2.0/token`	這個端點會驗證從你的應用程式收到的使用者憑證，然後向你的應用程式發放安全憑證。此端點的回應也能指示使用者是否需要完成多重驗證挑戰或註冊強認證方法。
`oauth/v2.0/introspect`	你的應用程式呼叫它，是為了請求一份已註冊的強認證方法清單，用於多重驗證（MFA）。學習如何使用 Introspect 端點

API 允許應用程式在呼叫 Microsoft Entra 時，宣告其支援的認證方法。若要這樣做，應用程式會在其要求中使用 challenge_type 參數。此參數會保留預先定義的值，代表不同的驗證方法。

對於特定認證方式，應用程式在註冊流程中發送給 Microsoft Entra 的挑戰類型值，與應用程式登入時相同。例如，具有密碼驗證方法的電子郵件會針對註冊和登入流程使用 oob、 password 和 redirect 挑戰類型值。

深入了解原生驗證挑戰類型一文中的挑戰類型。

此循序圖示範登入程式的流程。登入流程取決於使用者的認證方式。

以電子郵件寄送一次性密碼
電子郵件使用密碼

使用寄送一次性密碼進行原生驗證登入的圖表。

應用程式使用 OTP 驗證使用者的電子郵件後，就會收到安全性權杖。如果一次性密碼的傳遞延遲或從未傳遞至使用者的電子郵件，使用者可以要求傳送另一個一次性密碼。如果之前的一次性密碼未被驗證，Microsoft Entra 會重新發送一次。當 Microsoft Entra 重新傳送一次性密碼時，先前傳送的密碼即失效。

使用電子郵件和密碼選項登入原生驗證的圖表。

此圖指出應用程式會在不同的時間收集使用者的使用者名稱 (電子郵件) 和密碼 (可能在不同的畫面上)。不過，您可以設計應用程式在同一個畫面中收集兩個值。
如果您在相同的畫面中收集使用者名稱 (電子郵件) 和密碼，則步驟二和三會與步驟八、九合併。在此情況下，應用程式會保存密碼，然後在步驟十提交密碼。

若租戶管理員啟用租戶使用者的多重驗證（MFA），端點的回應 /oauth2/v2.0/token 取決於使用者是否已註冊強驗證方法：

如果使用者擁有註冊的強認證方法，則會完成多重身份驗證（MFA）挑戰流程。
如果使用者沒有註冊的強認證方法，則他們會完成強驗證方法流程的註冊。

此序列圖顯示了多因素分析路徑。它涵蓋兩種情況：（1）使用者已註冊強驗證方法，或（2）使用者沒有強認證方法，必須即時註冊。流程會在應用程式從使用者那裡收集到正確密碼並呼叫 /oauth2/v2.0/token 後開始，該 token 會回應，指示使用者是否需要完成多重驗證或註冊強驗證方法。

原生認證、呼叫令牌、端點、登錄器認證方法或完整多重認證（MFA）示意圖。

在接下來的章節中，我們將簽到流程總結為三個基本步驟。

驗證流程開始時，應用程式會向 /initiate 端點提出 POST 要求，以啟動登入流程。

以下是要求的範例 (我們以多行呈現範例要求，以取得可讀性)：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/initiate
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect
&username=contoso-consumer@contoso.com
&capabilities=registration_required mfa_required

參數	必要	描述
`tenant_subdomain`	是的	您所建立的外部租用戶的子網域。在 URL 中，將 `{tenant_subdomain}` 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。
`client_id`	是的	你在 Microsoft Entra 管理中心註冊的應用程式（客戶端）ID。
`username`	是的	客戶使用者的電子郵件，例如 contoso-consumer@contoso.com。
`challenge_type`	是的	應用程式支援的授權查問類型字串清單 (以空格分隔)，例如 `oob password redirect`。清單必須一律包含 `redirect` 查問類型。對於電子郵件一次性密碼，該值預期為 `oob redirect`，對於具有密碼的電子郵件，該值為 `password redirect`。
`capabilities`	否	空格分隔的旗標描述客戶端應用程式的「如何」準備狀態。雖然 `challenge_type` 定義了哪些方法可以被挑戰，但 `capabilities` 告訴原生認證 API 客戶端應用程式能處理哪些額外流程，以及它能顯示哪些 UI。例如，表示 `mfa_required/introspect`、、 `/challenge`迴 `/token` 圈; `registration_required` 表示客戶端應用程式呼叫註冊 API 並顯示註冊介面。如果客戶端應用程式沒有包含所需的功能，API 會回傳 redirect。支援的值為 `mfa_required` 和 `registration_required`。了解更多關於能力的資訊。

成功回應

以下是成功回應的範例：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

房產	描述
`continuation_token`	Continuation token Microsoft Entra回傳。

重定向反應

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}

房產	描述
`challenge_type`	Microsoft Entra 回傳一個具有挑戰類型的回應。此查問類型的值是重新導向，可讓應用程式使用 Web 型驗證流程。

此回應視為成功，但應用程式必須切換至 Web 型驗證流程。在此情況下，建議您使用 Microsoft 建置且支援的驗證程式庫。

回覆錯誤

範例：

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

房產	描述
`error`	可用於將錯誤分類的錯誤碼字串，並回應錯誤。
`error_description`	可協助您識別驗證錯誤原因的特定錯誤訊息。
`error_codes`	一份 Microsoft Entra 專屬錯誤代碼清單，能幫助你診斷錯誤。
`timestamp`	錯誤發生時間。
`trace_id`	要求的唯一識別碼，可協助您診斷錯誤。
`correlation_id`	有助於跨元件診斷的要求唯一識別碼。

以下是您可能遇到的錯誤（屬性的可能值 error ）：

錯誤值	描述
`invalid_request`	要求參數驗證失敗，例如當 `challenge_type` 參數包含無效的查問類型時。或要求未包含 `client_id` 參數時，用戶端識別碼的值為空白或無效。使用 `error_description` 參數來瞭解錯誤的確切原因。
`unauthorized_client`	要求中使用的用戶端識別碼具有有效的用戶端識別碼格式，但不存在於外部租用戶中或不正確。
`invalid_client`	應用程式在要求中包含的用戶端識別碼是針對缺少原生驗證組態的應用程式，例如不是公用用戶端或未啟用原生驗證。利用該 `suberror` 屬性來了解錯誤的確切原因。
`user_not_found`	使用者名稱不存在。
`unsupported_challenge_type`	`challenge_type` 參數值不包含 `redirect` 查問類型。

若誤差參數值為 invalid_client，Microsoft Entra 的回應包含 suberror 性質。以下是suberror錯誤時該性質可能的值：

Suberror 值	描述
`nativeauthapi_disabled`	未啟用原生驗證的應用程式的用戶端識別碼。

步驟 2：選取驗證方法

為了繼續流程，應用程式會利用從前一步取得的延續權杖，請求 Microsoft Entra 選擇支援的挑戰類型之一，供使用者驗證或完成 MFA 挑戰。應用程式向 /oauth2/v2.0/challenge 端點發出POST要求。

以下是要求的範例 (我們以多行呈現範例要求，以取得可讀性)：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect 
&continuation_token=uY29tL2F1dGhlbnRpY...

參數	必要	描述
`tenant_subdomain`	是的	您所建立的外部租用戶的子網域。在 URL 中，將 `{tenant_subdomain}` 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。
`client_id`	是的	你在 Microsoft Entra 管理中心註冊的應用程式（客戶端）ID。
`continuation_token`	是的	Continuation token，Microsoft Entra在上一次請求中回傳。先前的請求會呼叫端 `/oauth2/v2.0/initiate` 點，或若使用者完成多重驗證挑戰則呼叫端 `/oauth2/v2.0/introspect` 點。
`challenge_type`	否	應用程式支援的授權查問類型字串清單 (以空格分隔)，例如 `oob password redirect`。清單必須一律包含 `redirect` 查問類型。對於電子郵件一次性密碼，該值預期為 `oob redirect`，對於具有密碼的電子郵件，該值為 `password redirect`。
`id`	否	從端點回傳 `/oauth2/v2.0/introspect` 的強認證方法的字串識別碼。當用戶端應用程式向使用者提出第二因素驗證挑戰時，這個參數是必須的。學習如何使用 Introspect Endpoint。

成功回應

成功回應取決於使用者的認證方式。

以電子郵件寄送一次性密碼
電子郵件使用密碼

如果租戶管理員在Microsoft Entra管理中心設定一次性密碼作為使用者的驗證方式，Microsoft Entra會將一次性密碼傳送給使用者的電子郵件，然後回覆oob的挑戰類型，並提供更多一次性密碼的資訊。

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "challenge_type": "oob",
    "binding_method": "prompt ", 
    "challenge_channel": "email",
    "challenge_target_label ": "c***r@co**o**o.com ",
    "code_length": 8
}

房產	描述
`continuation_token`	Continuation token Microsoft Entra回傳。
`challenge_type`	為使用者選取以進行驗證的查問類型。
`binding_method`	唯一有效的值是 prompt。這個參數未來可以用來為使用者提供更多方式來輸入一次性密碼。如果 `challenge_type` 為 oob，則發出
`challenge_channel`	傳送一次性密碼的通道類型。目前，我們支援電子郵件。
`challenge_target_label`	模糊化的電子郵件，其中傳送了一次性密碼。
`code_length`	Microsoft Entra 產生的一次性密碼長度。

如果租戶管理員在Microsoft Entra管理中心設定了帶有密碼的電子郵件作為使用者的認證方式，回應取決於對 /oauth2/v2.0/challenge 端點的請求是選擇使用者驗證方式還是完成多重驗證挑戰。

如果請求選擇認證方法，則回應

如果對 /oauth2/v2.0/challenge 端點的請求是選擇使用者要用的認證方法（第一因素認證），Microsoft Entra 會回傳成功回應，其中包含 password 的挑戰類型。

範例：

HTTP/1.1 200 OK
Content-Type: application/json

{   
   "continuation_token": "uY29tL2F1dGhlbnRpY",   
   "challenge_type": "password" 
}

房產	描述
`continuation_token`	Continuation token Microsoft Entra回傳。
`challenge_type`	Microsoft Entra 會回傳 Microsoft Entra 管理中心中為使用者設定的支援挑戰類型。在此情況下，該值應為 password。

如果請求是完成 MFA 挑戰，回應

若/oauth2/v2.0/challenge端點請求完成多重驗證挑戰（第二因素驗證），Microsoft Entra會向使用者選擇的多重認證通道發送一次性密碼，並提供更多一次性密碼資訊。

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "challenge_type": "oob",
    "binding_method": "prompt ", 
    "challenge_channel": "email",
    "challenge_target_label ": "c***r@co**o**o.com ",
    "code_length": 8
}

房產	描述
`continuation_token`	Continuation token Microsoft Entra回傳。
`challenge_type`	為使用者完成多重認證（MFA）選擇的挑戰類型。
`binding_method`	唯一有效的值是 prompt。這個參數未來可以用來為使用者提供更多方式來輸入一次性密碼。如果 `challenge_type` 為 oob，則發出
`challenge_channel`	MFA 挑戰頻道的類型，該通道是透過一次性密碼傳送的。支援的價值觀：電子郵件、簡訊。
`challenge_target_label`	模糊化的電子郵件，其中傳送了一次性密碼。
`code_length`	Microsoft Entra 產生的一次性密碼長度。

重定向反應

在以下情境下，可能需要備援至基於網頁的認證流程：

客戶端應用程式不支援 Microsoft Entra 所需的認證方式或功能。
使用者嘗試使用 SMS 作為強認證方式，但防詐騙系統若認定該請求風險較高（僅限於電子郵件並使用密碼驗證時），會封鎖該請求。

在這些情境下，Microsoft Entra 會透過回應回傳 redirect 挑戰類型來通知應用程式：

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}

房產	描述
`challenge_type`	Microsoft Entra 回傳一個具有挑戰類型的回應。此查問類型的值是重新導向，可讓應用程式使用 Web 型驗證流程。

此回應視為成功，但應用程式必須切換至 Web 型驗證流程。在此情況下，建議您使用 Microsoft 建置且支援的驗證程式庫。

回覆錯誤

範例：

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

房產	描述
`error`	可用於將錯誤分類的錯誤碼字串，並回應錯誤。
`error_description`	可協助您識別驗證錯誤原因的特定錯誤訊息。
`error_codes`	一份 Microsoft Entra 專屬錯誤代碼清單，能幫助你診斷錯誤。
`timestamp`	錯誤發生時間。
`trace_id`	要求的唯一識別碼，可協助您診斷錯誤。
`correlation_id`	有助於跨元件診斷的要求唯一識別碼。

以下是您可能遇到的錯誤（屬性的可能值 error ）：

錯誤值	描述
`invalid_request`	要求參數驗證失敗，例如當 `challenge_type` 參數包含無效的查問類型時。
`invalid_grant`	要求中包含的接續權杖無效。
`expired_token`	要求中包含的接續權杖已過期。
`unsupported_challenge_type`	`challenge_type` 參數值不包含 `redirect` 查問類型。

步驟 3：要求安全性權杖

應用程式會向 oauth2/v2.0/token 端點發送 POST 請求，並提供使用者在前一步選擇的憑證以取得安全憑證。

以下是要求的範例 (我們以多行呈現範例要求，以取得可讀性)：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=password 
&password={secure_password}
&scope=openid offline_access

參數	必要	描述
`tenant_subdomain`	是的	您所建立的外部租用戶的子網域。在 URL 中，將 `{tenant_subdomain}` 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。
`client_id`	是的	你在 Microsoft Entra 管理中心註冊的應用程式（客戶端）ID。
`continuation_token`	是的	Continuation token，Microsoft Entra在上一次請求中回傳。
`grant_type`	是的	補助金類型。當你呼叫令牌端點時，這個值必須是： - 電子郵件密碼，並以密碼驗證方式，在登入流程中驗證使用者的第一因素認證。 - 電子郵件的 OOB 一次性密碼驗證方式，在登入流程中。 - continuation_token 註冊流程後自動登入。 - continuation_token 自動登入，方便自助密碼重設流程。 - continuation_token 在強認證方法註冊流程之後。 - mfa_oob 在驗證使用者的第二因素認證時。
`scope`	是的	以空格分隔的範圍清單。所有範圍必須來自單一資源，並包含 OpenID Connect（OIDC）範圍，如個人檔案、 OpenID 和電子郵件。應用程式需要包含 openid範圍，讓Microsoft Entra能發出 ID 令牌。應用程式需要包含 offline_access 範圍，讓 Microsoft Entra 發出刷新令牌。深入了解 Microsoft 身分識別平台中的權限和同意。
`password`	否	應用程式從使用者那裡收集的密碼值。用應用程式從使用者那裡收集的密碼值替換 `{secure_password}` 。如果驗證方式是電子郵件並使用密碼，則此參數是必要的。
`oob`	否	使用者透過電子郵件收到的一次性密碼。必要條件： - 主要的驗證方式是電子郵件一次性密碼。 - 應用程式提交電子郵件一次性密碼以滿足多重身份驗證挑戰，但主要的驗證方式是帶有密碼的電子郵件。若要重新傳送一次性密碼，請再次呼叫端點 `/challenge` 。
`username`	否	他們想註冊的使用者的電子郵件，例如 contoso-consumer@contoso.com。這個參數在註冊流程中是必備的。

成功回應

以下是成功回應的範例：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "token_type": "Bearer",
    "scope": "openid profile",
    "expires_in": 4141,
    "access_token": "eyJ0eXAiOiJKV1Qi...",
    "refresh_token": "AwABAAAA...",
    "id_token": "eyJ0eXAiOiJKV1Q..."
}

房產	描述
`token_type`	指出權杖類型的值。 Microsoft Entra唯一支援的類型是承載者。
`scopes`	一個空格分隔的存取權杖有效範圍清單。
`expires_in`	存取權杖仍然有效的時間長度，以秒為單位。
`access_token`	應用程式從 `/token` 端點所要求的存取權杖。應用程式可以使用此存取權杖來要求存取受保護的資源，例如 Web API。
`refresh_token`	OAuth 2.0 重新整理權杖。應用程式可以使用這個權杖，在目前的存取權杖過期之後，取得其他的存取權杖。重新整理權杖會長期存在。他們可以在延長的期間內維護資源的存取權。關於刷新存取權杖的更多細節，請參考「重新整理存取權杖」。注意：只有在您要求 offline_access 範圍時才發出。
`id_token`	用來識別使用者的 JSON Web Token（Jwt）。應用程式可以將權杖解碼，以要求登入使用者的相關資訊。應用程式可以快取這些值並加以顯示，而機密用戶端可以使用此權杖來進行授權。欲了解更多關於 ID 標記的資訊，請參閱 Microsoft 身份平台中的 ID 標記。注意：只有在您要求 openid 範圍時才發出。

回覆錯誤

範例：

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_grant", 
    "error_description": "AADSTS901007: Error validating credentials due to invalid username or password.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

房產	描述
`error`	一個錯誤代碼字串，可用於分類錯誤類型並對錯誤做出反應。
`error_description`	可協助您識別驗證錯誤原因的特定錯誤訊息。
`error_codes`	一份 Microsoft Entra 專屬錯誤代碼清單，能幫助你診斷錯誤。
`timestamp`	錯誤發生時間。
`trace_id`	要求的唯一識別碼，可協助您診斷錯誤。
`correlation_id`	有助於跨元件診斷的要求唯一識別碼。

以下是您可能遇到的錯誤（屬性的可能值 error ）：

錯誤值	描述
`invalid_request`	要求參數驗證失敗。若要瞭解所發生的情況，請使用錯誤描述中的訊息。
`invalid_grant`	請求中包含的延續權杖無效、請求中包含的使用者登入憑證無效、需要使用者進一步互動，或請求中包含的授權類型不明。
`invalid_client`	要求中包含的用戶端標識碼不適用於公用用戶端。
`expired_token`	要求中包含的接續權杖已過期。
`invalid_scope`	請求中包含的一個或多個作用域無效。
`unauthorized_client`	要求中包含的用戶端識別碼無效或不存在。
`unsupported_grant_type`	要求中包含的授與類型未受支援或不正確。

若誤差參數值為 invalid_grant，Microsoft Entra 的回應包含 suberror 性質。以下是suberror錯誤時該性質可能的值：

Suberror 值	描述
`invalid_oob_value`	應用程式提交的一次性密碼數值是無效的。
`mfa_required`	必須取得MFA。回應會附上一個續約標記。呼叫端 `oauth2/v2.0/introspect` 點以取得使用者註冊的強驗證方法。此子錯誤僅發生在使用者的主要認證方式為帶有密碼的電子郵件時。看看如何取得使用者註冊的強認證方法。注意：在某些情況下需要多重驗證，但原生認證不會回傳 `mfa_required`。例如，若強認證方法註冊流程在呼叫前 `/oauth2/v2.0/token` 進行，且該流程中唯一可用的方法（電子郵件）已被驗證。
`registration_required`	使用者必須完成 MFA 挑戰，但沒有註冊的強認證方法。提示使用者註冊一個。當使用者的主要驗證方式是帶有密碼的電子郵件時，會發生此錯誤。學習如何註冊強認證方法。

重定向反應

如果用戶端應用程式不支援 Microsoft Entra 所需的認證方式或功能，則需要回退到基於網頁的認證流程。在此情境中，Microsoft Entra 會透過回應回傳 redirect 挑戰類型來通知應用程式：

HTTP/1.1 200 OK
Content-Type: application/json

{     
    "challenge_type": "redirect",
    "redirect_reason": "Client is missing registration_required capability"
}

房產	描述
`challenge_type`	Microsoft Entra 回傳一個具有挑戰類型的回應。此查問類型的值是重新導向，可讓應用程式使用 Web 型驗證流程。
`redirect_reason`	需要重定向的原因。例如，Microsoft Entra 偵測到需要多重身份驗證（MFA）或強認證方法的註冊，但該應用程式並未在請求中包含這些功能。

此回應視為成功，但應用程式必須切換至 Web 型驗證流程。在此情況下，建議您使用 Microsoft 建置且支援的驗證程式庫。

取得使用者註冊的強性驗證方法

利用端 oauth2/v2.0/introspect 點請求使用者已註冊的強認證方法清單。

以下是要求的範例 (我們以多行呈現範例要求，以取得可讀性)：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/introspect
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444

參數	必要	描述
`tenant_subdomain`	是的	您所建立的外部租用戶的子網域。在 URL 中，將 `{tenant_subdomain}` 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。
`client_id`	是的	你在 Microsoft Entra 管理中心註冊的應用程式（客戶端）ID。
`continuation_token`	是的	Continuation token，Microsoft Entra在上一次請求中回傳。

成功回應

範例：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "methods":[
        {
            "id":"0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c",
            "challenge_type":"oob",
            "challenge_channel":"email",
            "login_hint":"c***r@co**o**o.com"
        },
        {   
          "id": "1b1b1b1b-2222-cccc-3333-4d4d4d4d4d4d",   
          "challenge_type": "oob",   
          "challenge_channel": "sms",   
          "login_hint": "+1********6"
        }
    ]
}

房產	描述
`continuation_token`	Continuation token Microsoft Entra回傳。
`methods`	一份使用者註冊強驗證方法的物件清單。

MFA 方法物件具有以下特性：

房產	描述
`id`	MFA 方法的自動產生唯一字串識別碼。應用程式在呼叫`id`端點時會使用這個字串`/oauth2/v2.0/challenge`。
`challenge_type`	選擇了供使用者使用的挑戰類型作為多重驗證方法。目前支援的挑戰類型是 OOB。
`challenge_channel`	MFA 方法傳送到的通道類型。目前支援的挑戰管道是電子郵件。
`login_hint`	強認證方法的提示，例如混淆郵件。

重定向反應

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}

回覆錯誤

範例：

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The continuation_token provided is not valid for this endpoint.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

房產	描述
`error`	可用於將錯誤分類的錯誤碼字串，並回應錯誤。
`error_description`	可協助您識別驗證錯誤原因的特定錯誤訊息。
`error_codes`	一份 Microsoft Entra 專屬錯誤代碼清單，能幫助你診斷錯誤。
`timestamp`	錯誤發生時間。
`trace_id`	要求的唯一識別碼，可協助您診斷錯誤。
`correlation_id`	有助於跨元件診斷的要求唯一識別碼。

以下是您可能遇到的錯誤（屬性的可能值 error ）：

錯誤值	描述
`invalid_request`	要求參數驗證失敗。若要瞭解所發生的情況，請使用錯誤描述中的訊息。
`invalid_client`	要求中包含的用戶端標識碼不適用於公用用戶端。
`expired_token`	要求中包含的接續權杖已過期。
`server_error`	這個請求出了問題。

當客戶端應用程式成功取得為使用者註冊的強驗證方法清單後，使用者選擇他們想使用的方法來完成多重驗證挑戰。流程接著如下進行：

用戶端應用程式呼叫， /oauth2/v2.0/challenge 並包含從 /oauth2/v2.0/introspect 和 id 所選 MFA 方法所取得的延續令牌：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/challenge
Content-Type: application/x-www-form-urlencoded    
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&id=0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c 
&continuation_token=uY29tL2F1dGhlbnRpY...

Microsoft Entra 會將挑戰代碼傳送到使用者的挑戰頻道，例如電子郵件，然後回覆客戶端應用程式，提供延續令牌及多重身份驗證挑戰細節：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "challenge_type": "oob",
    "binding_method": "prompt ", 
    "challenge_channel": "email",
    "challenge_target_label ": "c***r@co**o**o.com ",
    "code_length": 8
}

應用程式現在可以向端點發出 POST 請求 /oauth2/v2.0/token ，並包含延續權杖、正確的授權類型，以及對應的授權類型值來取得安全權杖。請參閱安全令牌請求中的預期回應：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded    
client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&continuation_token=uY29tL2F1dGhlbnRpY...   
&grant_type=mfa_oob  
&oob={otp_code}
&scope=openid offline_access

註冊強認證方法的 API 參考

原生認證支援強認證方法的註冊。當應用程式呼叫 /oauth2/v2.0/token 端點且需要多重驗證（MFA）但使用者沒有註冊強方法時，回應 registeration_required會告訴應用程式必須先註冊一個 MFA，才能發出權杖。

客戶端應用程式完成流程註冊強認證方法後，會呼叫 /oauth2/v2.0/token 端點請求安全憑證。

強認證方法註冊端點

要使用強認證方法註冊 API，應用程式會使用下表所示的端點：

端點	描述
`/register/v1.0/introspect`	呼叫此端點，取得使用者可註冊的強認證方法清單。
`/register/v1.0/challenge`	呼叫這個端點，將挑戰訊息傳送給使用者，例如電子郵件一次性密碼。
`/register/v1.0/continue`	呼叫此端點，提交應用程式從使用者收集的挑戰，例如一次性密碼，以完成流程以註冊強認證方法。呼叫成功並取得續權杖後，呼叫 `/oauth2/v2.0/token` 端點請求安全權杖。學習如何呼叫 token 端點。

步驟 1：取得強認證方法清單

註冊流程從應用程式請求使用者可註冊的強認證方式清單開始。

以下是要求的範例 (我們以多行呈現範例要求，以取得可讀性)：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/introspect
Content-Type: application/x-www-form-urlencoded
?continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444

參數	必要	描述
`tenant_subdomain`	是的	您所建立的外部租用戶的子網域。在 URL 中，將 `{tenant_subdomain}` 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。
`client_id`	是的	你在 Microsoft Entra 管理中心註冊的應用程式（客戶端）ID。

成功回應

以下是成功回應的範例：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "methods":[
        {
            "id":"email",
            "challenge_type":"oob",
            "challenge_channel":"email",
            "login_hint":"caseyjensen@contoso.com"
        },
        {   
          "id": "sms",   
          "challenge_type": "oob",   
          "challenge_channel": "sms"
        }
    ]
}

房產	描述
`continuation_token`	Continuation token Microsoft Entra回傳。
`methods`	一份（物件）清單，供使用者註冊強驗證方法。

強認證方法物件具有以下特性：

房產	描述
`id`	這個方法的字串鍵。支持價值電子郵件、簡訊。
`challenge_type`	選擇了供使用者使用的挑戰類型作為多重驗證方法。目前支援的挑戰類型是 OOB。
`challenge_channel`	MFA 方法傳送到的通道類型。支持價值電子郵件、簡訊。
`login_hint`	強認證方法如電子郵件的提示。這個值會被客戶端應用程式用來預先填充電子郵件文字框。

回覆錯誤

範例：

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The continuation_token provided is not valid for this endpoint.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

房產	描述
`error`	可用於將錯誤分類的錯誤碼字串，並回應錯誤。
`error_description`	可協助您識別驗證錯誤原因的特定錯誤訊息。
`error_codes`	一份 Microsoft Entra 專屬錯誤代碼清單，能幫助你診斷錯誤。
`timestamp`	錯誤發生時間。
`trace_id`	要求的唯一識別碼，可協助您診斷錯誤。
`correlation_id`	有助於跨元件診斷的要求唯一識別碼。

以下是您可能遇到的錯誤（屬性的可能值 error ）：

錯誤值	描述
`invalid_request`	要求參數驗證失敗，例如驗證接續權杖失敗，或要求未包含 `client_id` 參數時，用戶端識別碼的值為空白或無效，或外部租用戶系統管理員尚未為所有租用戶使用者啟用電子郵件 OTP。
`expired_token`	要求中包含的接續權杖已過期。

步驟 2：選擇強認證方法

在此步驟中，提交使用者希望註冊的強認證方式。接著 Microsoft Entra 會向使用者發送挑戰，例如電子郵件一次性密碼。

以下是要求的範例 (我們以多行呈現範例要求，以取得可讀性)：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/challenge 

?continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444  
&challenge_type=oob  
&challenge_channel=email 
&challenge_target=contoso-consumer@contoso.com

參數	必要	描述
`tenant_subdomain`	是的	您所建立的外部租用戶的子網域。在 URL 中，將 `{tenant_subdomain}` 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。
`client_id`	是的	你在 Microsoft Entra 管理中心註冊的應用程式（客戶端）ID。
`continuation_token`	是的	Continuation token Microsoft Entra從 `/register/v1.0/introspect` 端點回傳
`challenge_type`	是的	驗證方法的挑戰類型。目前的類型是 OOB。
`challenge_target`	是的	使用者想註冊的電子郵件或電話號碼。
`challenge_channel`	否	發送挑戰的頻道。支援的挑戰頻道價值：電子郵件、簡訊。

成功回應

這裡有一個成功回應的例子。

範例 1：

HTTP/1.1 200 OK
Content-Type: application/json

{ 
  "continuation_token": "uY29tL2F1dGhlbnRpY...", 
  "challenge_type": "oob", 
  "binding_method": "prompt", 
  "challenge_target": "contoso-consumer@contoso.com", 
  "challenge_channel": "email", 
  "code_length": 8 
}

範例 2：

如果註冊流程先於強認證方法註冊流程，且提交給 /register/v1.0/challenge 端點的電子郵件與註冊流程中驗證的郵件相符，原生認證 API 會註冊該方法，且不會向使用者發送挑戰。在這種情況下，回應會看起來像以下摘要：

HTTP/1.1 200 OK
Content-Type: application/json

{ 
  "continuation_token": "uY29tL2F1dGhlbnRpY...",
  "challenge_type": "preverified" 
}

房產	描述
`continuation_token`	Continuation token Microsoft Entra回傳。
`challenge_type`	選擇讓使用者驗證的挑戰類型，例如 OOB，或如果強認證方法被預先驗證，則是預先驗證。
`binding_method`	唯一有效的值是 prompt。這個參數未來可以用來為使用者提供更多方式來輸入一次性密碼。若 `challenge_type` 為 OOB，且強驗證方法未預先驗證，則會發出。
`challenge_channel`	傳送一次性密碼的通道類型。支持價值電子郵件、簡訊。若強認證方法未預先驗證，則會退回。
`code_length`	一次性密碼 `binding_method` 的長度為提示。若強認證方法未預先驗證，則會退回。
`challenge_target`	挑戰被派往的目標。這與請求中提供的輸入相同。若強認證方法未預先驗證，則會退回。
`interval`	客戶端在輪詢 /register/continue 之間的間隔（以秒為單位）應該等待。只有當 `prompt=none` 強驗證方法未被預先驗證時才會退回。用戶端每次從原生認證 API 收到 A `HTTP 429` 時，應該將間隔加倍。

回覆錯誤

這裡的錯誤與你呼叫 /register/v1.0/introspect 終端時可能遇到的錯誤相似。然而，在登記電話號碼時，若該號碼被視為高風險，申請可能會被阻擋。

以下是如果請求被封鎖，你可能會遇到的錯誤：

錯誤值	描述
`access_denied`	簡訊被封鎖了。

若錯誤參數值為 access_denied，Microsoft Entra 回應中包含子錯誤性質。以下是子錯誤屬性對invalid_grant錯誤的可能取值：

Suberror 值	描述
`provider_blocked_by_admin`	租戶管理員已經封鎖了電話區域。
`provider_blocked_by_rep`	多重驗證方法已被封鎖（電話號碼被 RepMap 封鎖）。

步驟三：提交挑戰

在此步驟中，呼叫 /register/v1.0/continue 端點以完成強認證方法的註冊。

以下是要求的範例 (我們以多行呈現範例要求，以取得可讀性)：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/continue 

?continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444  
&grant_type=oob  
&oob={otp_code}

參數	必要	描述
`tenant_subdomain`	是的	您所建立的外部租用戶的子網域。在 URL 中，將 `{tenant_subdomain}` 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。
`continuation_token`	是的	Continuation token，Microsoft Entra在上一次請求中回傳。
`client_id`	是的	你在 Microsoft Entra 管理中心註冊的應用程式（客戶端）ID。
`grant_type`	是的	補助金類型。目前支援的值是 OOB，若強認證方法在端點被預先驗證，則為 `/register/v1.0/challenge`。
`oob`	否	客戶使用者在其電子郵件中收到的一次性密碼。以客戶使用者在其電子郵件中收到的一次性密碼值取代 `{otp_code}`。若要重新傳送一次性密碼，應用程式必須再次向 `/register/v1.0/challenge` 端點提出要求。若端點未預先驗證 `/register/v1.0/challenge` 強認證方法，則必須如此。

成功回應

以下是成功回應的範例：

HTTP/1.1 200 OK
Content-Type: application/json

{ 
  "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

房產	描述
`continuation_token`	Microsoft Entra回傳的 continuation token。利用這個延續權杖呼叫 `/oauth2/v2.0/token` 端點請求安全權杖。學習如何呼叫 token 端點。

回覆錯誤

範例：

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS55200: The continuation_token is invalid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        55200 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

房產	描述
`error`	可用於將錯誤分類的錯誤碼字串，並回應錯誤。
`error_description`	可協助您識別驗證錯誤原因的特定錯誤訊息。
`error_codes`	一份 Microsoft Entra 專屬錯誤代碼清單，能幫助你診斷錯誤。
`timestamp`	錯誤發生時間。
`trace_id`	要求的唯一識別碼，可協助您診斷錯誤。
`correlation_id`	有助於跨元件診斷的要求唯一識別碼。

以下是您可能遇到的錯誤（屬性的可能值 error ）：

錯誤值	描述
`invalid_request`	要求參數驗證失敗，例如驗證接續權杖失敗，或要求未包含 `client_id` 參數時，用戶端識別碼的值為空白或無效，或外部租用戶系統管理員尚未為所有租用戶使用者啟用電子郵件 OTP。
`invalid_grant`	要求中包含的授與類型無效或未受支援，或 OTP 值不正確。
`expired_token`	要求中包含的接續權杖已過期。

若誤差參數值為 invalid_grant，Microsoft Entra 的回應包含 suberror 性質。以下是suberror錯誤時該性質可能的值：

Suberror 值	描述
`invalid_oob_value`	一次性密碼的值無效。

自助式密碼重設 (SSPR)

對於主要以電子郵件及密碼進行驗證的使用者，請使用自助式密碼重設（SSPR）API，讓客戶用戶能夠重設密碼。你可以用這個 API 來處理忘記密碼或更改密碼的情況。

自助式密碼重設的 API 端點

使用此 API 時，應用程式使用下表所示的端點：

端點	描述
`/resetpassword/v1.0/start`	當客戶使用者選取 [忘記密碼] 或 [變更密碼] 連結或應用程式中的按鈕時，您的應用程式會呼叫此端點。此端點會驗證使用者的使用者名稱（電子郵件），然後回傳一個延續權杖以用於密碼重設流程。如果你的應用程式要求使用Microsoft Entra不支援的認證方法，這個端點回應可能會指示應用程式需要使用瀏覽器式的認證流程。
`/resetpassword/v1.0/challenge`	接受用戶端支援的查問清單，以及接續權杖。查問會發出給其中一個慣用的復原認證。例如，oob 查問會向與客戶使用者帳戶關聯的電子郵件發出頻外一次性密碼。如果你的應用程式要求使用Microsoft Entra不支援的認證方法，這個端點回應可能會指示應用程式需要使用瀏覽器式的認證流程。
`/resetpassword/v1.0/continue`	驗證 `/resetpassword/v1.0/challenge` 端點發出的查問，然後針對端點傳回 `/resetpassword/v1.0/submit`，或對使用者發出另一個查問。
`/resetpassword/v1.0/submit`	接受使用者與接續權杖的新密碼輸入，以完成密碼重設流程。此端點會發出另一個接續權杖。
`/resetpassword/v1.0/poll_completion`	應用程式可以使用端點發出的`/resetpassword/v1.0/submit`來檢查密碼重設請求的狀態。
`oauth2/v2.0/token`	若密碼重設成功，應用程式可利用從端點取得 `/resetpassword/v1.0/poll_completion` 的續通令牌取得安全令牌 `oauth2/v2.0/token` 。

自助式密碼重設查問類型

針對 SSPR 流程，查問類型值會 oob 和 redirect。

深入了解原生驗證查問類型中的查問類型。

自助式密碼重設流程通訊協定詳細資料

此循序圖示範密碼重設程序的流程。

原生驗證自助式密碼重設流程的圖表。

此圖指出應用程式會在不同的時間收集使用者的使用者名稱 (電子郵件) 和密碼 (可能在不同的畫面上)。不過，您可以將應用程式設計為在同一個畫面上收集使用者名稱 (電子郵件) 和新密碼。在此情況下，應用程式會保存密碼，然後透過所需的 /resetpassword/v1.0/submit 端點提交密碼。

步驟 1：要求啟動自助式密碼重設流程

密碼重設流程開始時，應用程式會向 /resetpassword/v1.0/start 端點提出 POST 要求，以開始自助式密碼重設。

以下是要求的範例 (我們以多行呈現範例要求，以取得可讀性)：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/start
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&challenge_type=oob redirect 
&username=contoso-consumer@contoso.com

參數	必要	描述
`tenant_subdomain`	是的	您所建立的外部租用戶的子網域。在 URL 中，將 `{tenant_subdomain}` 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。
`client_id`	是的	你在 Microsoft Entra 管理中心註冊的應用程式（客戶端）ID。
`username`	是的	客戶使用者的電子郵件，例如 contoso-consumer@contoso.com。
`challenge_type`	是的	應用程式支援的授權查問類型字串清單 (以空格分隔)，例如 `oob password redirect`。清單必須一律包含 `redirect` 查問類型。針對此要求，該值預期會包含 `oob redirect`。
`capabilities`	否	空格分隔的旗標描述客戶端應用程式的「如何」準備狀態。雖然 `challenge_type` 定義了哪些方法可以被挑戰，但 `capabilities` 告訴原生認證 API 客戶端應用程式能處理哪些額外流程，以及它能顯示哪些 UI。例如，代表 `mfa_required` 另一個 `/challenge` 和 `/token` 迴圈; `registration_required` 代表客戶端應用程式呼叫註冊 API，並顯示註冊介面。如果客戶端應用程式沒有宣告某項所需功能，API 會回傳 redirect。支援的值為 `mfa_required` 和 `registration_required`。了解更多關於能力的資訊。

成功回應

範例：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

房產	描述
`continuation_token`	Continuation token Microsoft Entra回傳。

重定向反應

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}

房產	描述
`challenge_type`	Microsoft Entra 回傳一個具有挑戰類型的回應。此查問類型的值是重新導向，可讓應用程式使用 Web 型驗證流程。

此回應視為成功，但應用程式必須切換至 Web 型驗證流程。在此情況下，建議您使用 Microsoft 建置且支援的驗證程式庫。

回覆錯誤

範例：

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

房產	描述
`error`	可用於將錯誤分類的錯誤碼字串，並回應錯誤。
`error_description`	可協助您識別驗證錯誤原因的特定錯誤訊息。
`error_codes`	一份 Microsoft Entra 專屬錯誤代碼清單，能幫助你診斷錯誤。
`timestamp`	錯誤發生時間。
`trace_id`	要求的唯一識別碼，可協助您診斷錯誤。
`correlation_id`	有助於跨元件診斷的要求唯一識別碼。

以下是您可能遇到的錯誤（屬性的可能值 error ）：

錯誤值	描述
`invalid_request`	要求參數驗證失敗，例如當 `challenge_type` 參數包含無效的查問類型，或要求不包含 `client_id` 參數時，用戶端識別碼值為空白或無效。使用 `error_description` 參數來瞭解錯誤的確切原因。
`user_not_found`	使用者名稱不存在。
`unsupported_challenge_type`	`challenge_type` 參數值不包含 `redirect` 查問類型。
`invalid_client`	應用程式在要求中包含的用戶端識別碼是針對缺少原生驗證組態的應用程式，例如不是公用用戶端或未啟用原生驗證。利用該 `suberror` 屬性來了解錯誤的確切原因。
`unauthorized_client`	要求中使用的用戶端識別碼具有有效的用戶端識別碼格式，但不存在於外部租用戶中或不正確。

若誤差參數值為 invalid_client，Microsoft Entra 的回應包含 suberror 性質。以下是suberror錯誤時該性質可能的值：

Suberror 值	描述
`nativeauthapi_disabled`	一個沒有啟用原生認證的應用程式的客戶端 ID。

步驟 2：選取驗證方法

為了繼續流程，應用程式會使用前一步取得的延續令牌，請求 Microsoft Entra 選擇使用者可驗證的支援挑戰類型之一。應用程式向 /resetpassword/v1.0/challenge 端點發出POST要求。如果此請求成功，Microsoft Entra 會向使用者的帳號電子郵件發送一次性密碼。目前，我們僅支援電子郵件 OTP。

以下是範例 (我們以多行呈現範例要求，以取得可讀性)：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY...

參數	必要	描述
`tenant_subdomain`	是的	您所建立的外部租用戶的子網域。在 URL 中，將 `{tenant_subdomain}` 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。
`client_id`	是的	你在 Microsoft Entra 管理中心註冊的應用程式（客戶端）ID。
`continuation_token`	是的	Continuation token，Microsoft Entra在上一次請求中回傳。
`challenge_type`	否	應用程式支援的授權查問類型字串清單 (以空格分隔)，例如 `oob redirect`。清單必須一律包含 `redirect` 查問類型。針對此要求，該值預期會包含 `oob redirect`。

成功回應

範例：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "challenge_type": "oob",
    "binding_method": "prompt ", 
    "challenge_channel": "email",
    "challenge_target_label ": "c***r@co**o**o.com ",
    "code_length": 8
}

房產	描述
`continuation_token`	Continuation token Microsoft Entra回傳。
`challenge_type`	為使用者選取以進行驗證的查問類型。
`binding_method`	唯一有效的值是 prompt。這個參數未來可以用來為使用者提供更多方式來輸入一次性密碼。如果 `challenge_type` 為 oob，則發出
`challenge_channel`	傳送一次性密碼的通道類型。目前，我們支援電子郵件。
`challenge_target_label`	模糊化的電子郵件，其中傳送了一次性密碼。若啟用多重身份驗證（MFA），包含一次性密碼的電子郵件將寄送至： - 當電子郵件地址與帳戶電子郵件地址不同時，作為強驗證方法的電子郵件地址。 - 當強認證方式為簡訊時，帳號電子郵件地址。
`code_length`	Microsoft Entra 產生的一次性密碼長度。

重定向反應

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}

房產	描述
`challenge_type`	Microsoft Entra 回傳一個具有挑戰類型的回應。此查問類型的值是重新導向，可讓應用程式使用 Web 型驗證流程。

此回應視為成功，但應用程式必須切換至 Web 型驗證流程。在此情況下，建議您使用 Microsoft 建置且支援的驗證程式庫。

回覆錯誤

範例：

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

房產	描述
`error`	可用於將錯誤分類的錯誤碼字串，並回應錯誤。
`error_description`	可協助您識別驗證錯誤原因的特定錯誤訊息。
`error_codes`	一份 Microsoft Entra 專屬錯誤代碼清單，能幫助你診斷錯誤。
`timestamp`	錯誤發生時間。
`trace_id`	要求的唯一識別碼，可協助您診斷錯誤。
`correlation_id`	有助於跨元件診斷的要求唯一識別碼。

以下是您可能遇到的錯誤（屬性的可能值 error ）：

錯誤值	描述
`invalid_request`	要求參數驗證失敗，例如當 `challenge_type` 參數包含無效的查問類型或接續權杖驗證失敗時。
`expired_token`	接續權杖已過期。
`unsupported_challenge_type`	`challenge_type` 參數值不包含 `redirect` 查問類型。

步驟 3：提交一次性密碼

應用程式接著會向 /resetpassword/v1.0/continue 端點提出 POST 要求。在要求中，應用程式必須包含上一個步驟中選擇的使用者認證，以及從 /resetpassword/v1.0/challenge 端點發出的接續權杖。

以下是要求的範例 (我們以多行呈現範例要求，以取得可讀性)：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/continue
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=oob 
&oob={otp_code}

參數	必要	描述
`tenant_subdomain`	是的	您所建立的外部租用戶的子網域。在 URL 中，將 `{tenant_subdomain}` 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。
`continuation_token`	是的	Continuation token，Microsoft Entra在上一次請求中回傳。
`client_id`	是的	你在 Microsoft Entra 管理中心註冊的應用程式（客戶端）ID。
`grant_type`	是的	唯一有效的值是 oob。
`oob`	是的	客戶使用者在其電子郵件中收到的一次性密碼。以客戶使用者在其電子郵件中收到的一次性密碼取代 `{otp_code}`。若要重新傳送一次性密碼，應用程式必須再次向 `/resetpassword/v1.0/challenge` 端點提出要求。

成功回應

範例：

HTTP/1.1 200 OK
Content-Type: application/json

{ 
    "expires_in": 600,
    "continuation_token": "czZCaGRSa3F0MzpnW...",
}

房產	描述
`expires_in`	continuation_token 到期前的時間，以秒為單位。 `expires_in` 的最大值是 600 秒。
`continuation_token`	Continuation token Microsoft Entra回傳。

回覆錯誤

範例：

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS55200: The continuation_token is invalid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        55200 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

房產	描述
`error`	可用於將錯誤分類的錯誤碼字串，並回應錯誤。
`error_description`	可協助您識別驗證錯誤原因的特定錯誤訊息。
`error_codes`	一份 Microsoft Entra 專屬錯誤代碼清單，能幫助你診斷錯誤。
`timestamp`	錯誤發生時間。
`trace_id`	要求的唯一識別碼，可協助您診斷錯誤。
`correlation_id`	有助於跨元件診斷的要求唯一識別碼。
`suberror`	錯誤碼字串，可用來進一步分類錯誤類型。

以下是您可能遇到的錯誤（屬性的可能值 error ）：

錯誤值	描述
`invalid_request`	要求參數驗證失敗，例如驗證接續權杖失敗，或要求不包含 `client_id` 參數時，用戶端識別碼值為空白或無效，或外部租用戶系統管理員尚未為所有租用戶使用者啟用 SSPR 和電子郵件 OTP。使用 `error_description` 參數來瞭解錯誤的確切原因。
`invalid_grant`	授與類型未知或不符合預期的授與類型值。利用該 `suberror` 屬性來了解錯誤的確切原因。
`expired_token`	接續權杖已過期。

若誤差參數值為 invalid_grant，Microsoft Entra 的回應包含 suberror 性質。以下是suberror錯誤時該性質可能的值：

Suberror 值	描述
`invalid_oob_value`	一次性密碼的值無效。

步驟 4：提交新密碼

應用程式會從使用者收集新的密碼，然後使用端點發出的 /resetpassword/v1.0/continue，透過向 /resetpassword/v1.0/submit 端點發出 POST 要求來提交密碼。

以下是範例 (我們以多行呈現範例要求，以取得可讀性)：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/submit
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0Mzp...
&new_password={new_password}

參數	必要	描述
`tenant_subdomain`	是的	您所建立的外部租用戶的子網域。在 URL 中，將 `{tenant_subdomain}` 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。
`continuation_token`	是的	Continuation token，Microsoft Entra在上一次請求中回傳。
`client_id`	是的	你在 Microsoft Entra 管理中心註冊的應用程式（客戶端）ID。
`new_password`	是的	使用者的新密碼。以使用者的新密碼取代 `{new_password}`。您必須負責確認使用者想要使用的密碼，方法是在應用程式的 UI 中提供密碼確認欄位。您也必須確定使用者知道根據組織的原則，哪些內容構成強密碼。了解更多關於 Microsoft Entra 的密碼政策。

成功回應

範例：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "poll_interval": 2
}

房產	描述
`continuation_token`	Continuation token Microsoft Entra回傳。
`poll_interval`	應用程式在透過 `/resetpassword/v1.0/poll_completion` 端點檢查密碼重設要求狀態的輪詢要求之間應該等候的最短時間，以秒為單位，請參閱步驟 5

回覆錯誤

範例：

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

房產	描述
`error`	可用於將錯誤分類的錯誤碼字串，並回應錯誤。
`error_description`	可協助您識別驗證錯誤原因的特定錯誤訊息。
`error_codes`	一份 Microsoft Entra 專屬錯誤代碼清單，能幫助你診斷錯誤。
`timestamp`	錯誤發生時間。
`trace_id`	要求的唯一識別碼，可協助您診斷錯誤。
`correlation_id`	有助於跨元件診斷的要求唯一識別碼。
`suberror`	錯誤碼字串，可用來進一步分類錯誤類型。

以下是您可能遇到的錯誤（屬性的可能值 error ）：

錯誤值	描述
`invalid_request`	要求參數驗證失敗，例如接續權杖驗證失敗。
`expired_token`	接續權杖已過期。
`invalid_grant`	提交的授與無效，例如提交的密碼太短。利用該 `suberror` 屬性來了解錯誤的確切原因。

若誤差參數值為 invalid_grant，Microsoft Entra 的回應包含 suberror 性質。以下是該性質可能的 suberror 值：

Suberror 值	描述
`password_too_weak`	密碼強度太弱，因為它不符合複雜度需求。了解更多關於 Microsoft Entra 的密碼政策。
`password_too_short`	新密碼少於 8 個字元。了解更多關於 Microsoft Entra 的密碼政策。
`password_too_long`	新密碼超過 256 個字元。了解更多關於 Microsoft Entra 的密碼政策。
`password_recently_used`	新密碼不得與最近使用的密碼相同。了解更多關於 Microsoft Entra 的密碼政策。
`password_banned`	新密碼包含禁止的字詞、片語或模式。了解更多關於 Microsoft Entra 的密碼政策。
`password_is_invalid`	密碼無效，例如，因為它使用不允許的字元。了解更多關於 Microsoft Entra 的密碼政策。如果應用程式提交了使用者密碼，則可能出現此回應。

步驟 5：輪詢密碼重設狀態

最後，由於更新使用者設定並加入新密碼會產生一定延遲，應用程式可以使用 /resetpassword/v1.0/poll_completion 端點輪詢Microsoft Entra密碼重設狀態。應用程式在輪詢要求之間應該等候的最短時間 (以秒為單位) 將由 /resetpassword/v1.0/submit 端點在 poll_interval 參數中傳回。

以下是範例 (我們以多行呈現範例要求，以取得可讀性)：

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/poll_completion
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0...

參數	必要	描述
`tenant_subdomain`	是的	您所建立的外部租用戶的子網域。在 URL 中，將 `{tenant_subdomain}` 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。
`continuation_token`	是的	Continuation token，Microsoft Entra在上一次請求中回傳。
`client_id`	是的	你在 Microsoft Entra 管理中心註冊的應用程式（客戶端）ID。

成功回應

範例：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "succeeded",
    "continuation_token":"czZCaGRSa3F0..."
}

房產	描述
`status`	重設密碼要求的狀態。如果Microsoft Entra回傳failed，應用程式可以透過向 `/resetpassword/v1.0/submit` 端點提出另一個請求，並加入新的續寫權杖，重新提交新密碼。
`continuation_token`	Continuation token Microsoft Entra回傳。若狀態為成功，應用程式可利用Microsoft Entra回傳的延續權杖，透過 `oauth2/v2.0/token` 端點請求安全權杖，詳見 Request for security tokens。這表示使用者成功重設其密碼之後，您可以直接登入您的應用程式，而不需要起始新的登入流程。

以下是Microsoft Entra回傳的可能狀態（status參數的可能值）：

錯誤值	描述
`succeeded`	密碼重設成功完成。
`failed`	密碼重設失敗。應用程式可以向 `/resetpassword/v1.0/submit` 端點提出另一個要求，以重新提交新的密碼。
`not_started`	密碼重設尚未啟動。應用程式稍後可以再次檢查狀態。
`in_progress`	密碼重設正在進行中。應用程式稍後可以再次檢查狀態。

回覆錯誤

範例：

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "expired_token", 
    "error_description": "AADSTS901007: The continuation_token is expired.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        552003 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

房產	描述
`error`	可用於將錯誤分類的錯誤碼字串，並回應錯誤。
`error_description`	可協助您識別驗證錯誤原因的特定錯誤訊息。
`error_codes`	一份 Microsoft Entra 專屬錯誤代碼清單，能幫助你診斷錯誤。
`timestamp`	錯誤發生時間。
`trace_id`	要求的唯一識別碼，可協助您診斷錯誤。
`correlation_id`	有助於跨元件診斷的要求唯一識別碼。

以下是您可能遇到的錯誤（屬性的可能值 error ）：

錯誤值	描述
`invalid_request`	要求參數驗證失敗，例如驗證接續權杖失敗。
`expired_token`	接續權杖已過期。

如果使用者在成功重設密碼後需要登入。應用程式需要呼叫端點 /oauth2/v2.0/token 。學習如何呼叫 token 端點。

設定自訂宣告提供者。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-03-11

共用方式為

原生驗證 API 參考

必要條件

接續權杖

註冊用的 API 參考

註冊用的 API 端點

註冊查問類型

註冊流程通訊協定詳細資料

步驟 1：要求啟動註冊流程

成功回應

重定向反應

回覆錯誤

步驟 2：選取驗證方法

成功回應

重定向反應

回覆錯誤

步驟 3：提交一次性密碼

回應

成功回應

重定向反應

步驟 4：驗證並取得權杖以進行登入

成功回應

需要使用者屬性

重定向反應

回覆錯誤

提交使用者屬性

成功回應

重定向反應

回覆錯誤

步驟五：註冊後自動登入

將使用者屬性提交至端點

使用者屬性值的格式

如何參考使用者屬性

登入流程的 API 參考

登入用的 API 端點

登入查問類型

登入流程通訊協定詳細資料

步驟 1：要求啟動登入流程

成功回應

重定向反應

回覆錯誤

步驟 2：選取驗證方法

成功回應

重定向反應

回覆錯誤

步驟 3：要求安全性權杖

成功回應

回覆錯誤

重定向反應

取得使用者註冊的強性驗證方法

成功回應

重定向反應

回覆錯誤

註冊強認證方法的 API 參考

強認證方法註冊端點

步驟 1：取得強認證方法清單

成功回應

回覆錯誤

步驟 2：選擇強認證方法

成功回應

回覆錯誤

步驟三：提交挑戰

成功回應

回覆錯誤

自助式密碼重設 (SSPR)

自助式密碼重設的 API 端點

自助式密碼重設查問類型

自助式密碼重設流程通訊協定詳細資料

步驟 1：要求啟動自助式密碼重設流程

成功回應

重定向反應

回覆錯誤

步驟 2：選取驗證方法

成功回應

重定向反應

回覆錯誤

步驟 3：提交一次性密碼

成功回應

回覆錯誤

步驟 4：提交新密碼