原生驗證 API 參考
適用於：
員工租用戶 
外部租用戶 (深入了解)
Microsoft Entra 的原生驗證可讓您在用戶端應用程式中裝載應用程式的使用者介面，而不是將驗證委派給瀏覽器，進而產生原生整合式驗證體驗。 身為開發人員，您可以完全掌控登入介面的外觀和風格。
此 API 參考文章說明只有在您手動提出執行流程的原始 HTTP 要求時，才需要的詳細資料。 不過，我們不建議使用此方法。 因此，盡可能使用 Microsoft 建置且支持的驗證 SDK。 如需如何使用 SDK 的詳細資訊，請參閱 教學課程：準備 Android 行動應用程式進行原生驗證 和 教學課程：準備 iOS 行動應用程式進行原生驗證。
當 API 端點的呼叫成功時，您會收到使用者身分識別的 識別碼權杖，以及呼叫受保護 API 的 存取權杖。 來自 API 的所有回應都是 JSON 格式。
Microsoft Entra 的原生驗證 API 支援註冊和登入兩種驗證方法：
具有密碼的電子郵件，支援使用電子郵件和密碼註冊和登入，以及自助式密碼重設 (SSPR)。
電子郵件一次性密碼，支援使用電子郵件一次性密碼註冊和登入。
注意
目前，原生驗證 API 端點不支援 跨原始來源資源分享 (CORS)。
必要條件
客戶租用戶的 Microsoft Entra 外部 ID。 如果您還沒有試用版，請 註冊免費試用。
如果您尚未這麼做，在 Microsoft Entra 系統管理中心註冊應用程式。 請確定您授與委派的權限，並啟用公用用戶端和原生驗證流程。
如果您尚未這麼做，在 Microsoft Entra 系統管理中心建立使用者流程。 當您建立使用者流程時，請記下您設定的必要使用者屬性，因為這些屬性是 Microsoft Entra 預期您的應用程式提交的屬性。 在 [識別提供者] 下，選取 [寄送一次性密碼] 選項。
針對登入流程，註冊客戶使用者，以用於測試登入 API。 或者，您可以在執行註冊流程之後取得此測試使用者。
針對 SSPR 流程，為客戶租用戶中的客戶使用者啟用自助式密碼重設。 SSPR 適用於使用電子郵件搭配密碼驗證方法的客戶使用者。
接續權杖
每次您在任何流程中呼叫端點、登入、註冊或 SSPR 時，端點都會在其回應中包含 接續權杖。 接續權杖是一個唯一識別碼，Microsoft Entra ID 用來維護對相同流程內不同端點的呼叫之間的狀態。 您必須在相同流程的後續要求中包含此權杖。
每個接續權杖在特定期間都有效，而且只能用於相同流程內的後續要求。
註冊 API 參考
若要完成任一驗證方法的使用者註冊流程，您的應用程式會與四個端點 /signup/v1.0/start、/signup/v1.0/challenge、/signup/v1.0/continue 和 /token 互動。
註冊 API 端點
| 端點 | 描述 |
|---|---|
/signup/v1.0/start |
此端點會啟動註冊流程。 您傳遞有效的應用程式識別碼、新的使用者名稱和 查問類型，然後取得新的接續權杖。 如果 Microsoft Entra 不支援應用程式選擇的驗證方法，端點可以傳回回應，以指示應用程式使用 Web 驗證流程。 |
/signup/v1.0/challenge |
您的應用程式會呼叫此端點，其中包含 Microsoft Entra 支援的 查問類型 清單。 然後 Microsoft Entra 會選取其中一個支援的驗證方法，讓使用者進行驗證。 |
/signup/v1.0/continue |
此端點可協助繼續流程來建立使用者帳戶，或因為缺少密碼原則需求等需求或錯誤屬性格式而中斷流程。 此端點會產生接續權杖，然後將其傳回應用程式。 如果應用程式不是 Microsoft Entra 選擇的驗證方法，端點可以傳回回應，以指示應用程式使用 Web 型驗證流程。 |
/token |
應用程式會呼叫此端點，最後要求安全性權杖。 應用程式必須包含從上次成功呼叫 /signup/v1.0/continue 端點取得的接續權杖。 |
註冊查問類型
API 可讓用戶端應用程式在呼叫 Microsoft Entra 時，公告其支援的驗證方法。 若要這樣做，應用程式會使用應用程式要求中的 challenge_type 參數。 此參數會保留預先定義的值，代表不同的驗證方法。
深入了解原生驗證查問類型中的查問類型。 本文說明您應該用於驗證方法的查問類型值。
註冊流程通訊協定詳細資料
循序圖示範註冊程序的流程。
下圖指出應用程式會在不同的時間，收集使用者的使用者名稱 (電子郵件)、密碼 (用於具有密碼驗證方法的電子郵件) 和屬性 (可能位於不同的畫面上)。 不過，您可以設計應用程式在同一畫面中收集使用者名稱 (電子郵件)、密碼和所有必要的和選擇性的屬性值，然後透過 /signup/v1.0/start 端點提交所有屬性。 在此情況下，應用程式不需要進行呼叫並處理選擇性步驟的回應。
步驟 1：要求啟動註冊流程
註冊流程開始時，應用程式會向 /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 |
Yes | 您所建立的外部租用戶的子網域。 在 URL 中，將 {tenant_subdomain} 取代為目錄 (租用戶) 子網域。 例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。 |
client_id |
Yes | 您在 Microsoft Entra 系統管理中心所註冊應用程式的應用程式 (用戶端) 識別碼。 |
username |
Yes | 客戶使用者要用來註冊的電子郵件，例如 contoso-consumer@contoso.com。 |
challenge_type |
Yes | 應用程式支援的授權查問類型字串清單 (以空格分隔)，例如 oob password redirect。 清單必須一律包含 redirect 查問類型。 該值必須是 oob redirect 或 oob password redirect 用於具有密碼驗證方法的電子郵件。 |
password |
No | 應用程式從客戶使用者收集的密碼值。 您可以在 /signup/v1.0/continue 端點中，透過 /signup/v1.0/start 或更新版本提交使用者的密碼。 以應用程式從客戶使用者收集的密碼值取代 {secure_password}。 您必須負責確認使用者想要使用的密碼，方法是在應用程式的 UI 中提供密碼確認欄位。 您也必須確定使用者知道根據組織的原則，哪些內容構成強密碼。 深入了解 Microsoft Entra 的密碼原則。 此參數僅適用於具有密碼驗證方法的電子郵件。 |
attributes |
No | 應用程式從客戶使用者收集的使用者屬性值。 該值是字串，但格式化為 JSON 物件，其索引鍵值是使用者屬性的可程式化名稱。 這些屬性可以是內建或自訂，也可以是必要或選擇性的屬性。 物件的索引鍵名稱取決於系統管理員在 Microsoft Entra 系統管理中心設定的屬性。 您可以在 /signup/v1.0/continue 端點中，透過 /signup/v1.0/start 端點或更新版本提交部分或所有使用者屬性。 如果您透過 /signup/v1.0/start 端點提交所有必要屬性，則不需要在 /signup/v1.0/continue 端點中提交任何屬性。 不過，如果您透過 /signup/v1.0/start 端點提交了一些必要屬性，稍後可以在 /signup/v1.0/continue 端點中提交其餘的必要屬性。 將 {given_name}、{user_age} 和 {postal_code} 分別取代為應用程式從客戶使用者收集的名稱、年齡和郵遞區號值。 Microsoft Entra 會忽略您所提交，但不存在的任何屬性。 |
成功回應
以下是成功回應的範例：
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "AQABAAEAAA…",
}
| 參數 | 描述 |
|---|---|
continuation_token |
Microsoft Entra 傳回的 接續權杖。 |
如果應用程式無法透過 Microsoft Entra 支援必要的驗證方法，則需要 Web 型驗證流程的後援。 在此案例中，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": "user_already_exists",
"error_description": "AADSTS1003037: It looks like you may already have an account.... .\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
1003037
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| 參數 | 描述 |
|---|---|
error |
可用於將錯誤分類的錯誤碼字串，並回應錯誤。 |
error_description |
可協助您識別驗證錯誤原因的特定錯誤訊息。 |
error_codes |
Microsoft Entra 特定的錯誤碼清單，可協助您診斷錯誤。 |
timestamp |
錯誤發生時間。 |
trace_id |
要求的唯一識別碼，可協助您診斷錯誤。 |
correlation_id |
有助於跨元件診斷的要求唯一識別碼。 |
invalid_attributes |
驗證失敗的屬性清單 (物件陣列)。 如果應用程式提交了使用者屬性，且 suberror 參數的值為 attribute_validation_failed，則可能出現此回應。 |
suberror |
錯誤碼字串，可用來進一步分類錯誤類型。 |
i以下是您可能會遇到的錯誤 (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 參數來了解錯誤的確切原因。 此參數僅適用於具有密碼驗證方法的電子郵件。 |
如果 error 參數的值為 invalid_grant，Microsoft Entra 會在其回應中包含 suberror 參數。 以下是 invalid_grant 錯誤的 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 的密碼原則。 如果應用程式提交了使用者密碼，則可能出現此回應。 |
如果 error 參數的值為 invalid_client，Microsoft Entra 會在其回應中包含 suberror 參數。 以下是 invalid_client 錯誤的 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 |
Yes | 您所建立的外部租用戶的子網域。 在 URL 中，將 {tenant_subdomain} 取代為目錄 (租用戶) 子網域。 例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。 |
client_id |
Yes | 您在 Microsoft Entra 系統管理中心所註冊應用程式的應用程式 (用戶端) 識別碼。 |
challenge_type |
No | 應用程式支援的授權 查問類型 字串清單 (以空格分隔)，例如 oob password redirect。 清單必須一律包含 redirect 查問類型。 對於電子郵件一次性密碼，該值預期為 oob redirect，對於具有密碼驗證方法的電子郵件，該值為 oob password redirect。 |
continuation_token |
Yes | 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 |
Microsoft Entra 傳回的 接續權杖。 |
challenge_type |
為使用者選取以進行驗證的查問類型。 |
binding_method |
唯一有效的值是 prompt。 這個參數未來可以用來為使用者提供更多方式來輸入一次性密碼。 如果 challenge_type 為 oob，則發出 |
challenge_channel |
傳送一次性密碼的通道類型。 目前僅支援電子郵件頻道。 |
challenge_target_label |
模糊化的電子郵件，其中傳送了一次性密碼。 |
code_length |
Microsoft Entra 產生的一次性密碼的長度。 |
如果應用程式無法透過 Microsoft Entra 支援必要的驗證方法，則需要 Web 型驗證流程的後援。 在此案例中，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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| 參數 | 描述 |
|---|---|
error |
可用於將錯誤分類的錯誤碼字串，並回應錯誤。 |
error_description |
可協助您識別驗證錯誤原因的特定錯誤訊息。 |
error_codes |
Microsoft Entra 特定的錯誤碼清單，可協助您診斷錯誤。 |
timestamp |
錯誤發生時間。 |
trace_id |
要求的唯一識別碼，可協助您診斷錯誤。 |
correlation_id |
有助於跨元件診斷的要求唯一識別碼。 |
i以下是您可能會遇到的錯誤 (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 |
Yes | 您所建立的外部租用戶的子網域。 在 URL 中，將 {tenant_subdomain} 取代為目錄 (租用戶) 子網域。 例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。 |
continuation_token |
Yes | Microsoft Entra 在上一個要求中傳回的 接續權杖。 |
client_id |
Yes | 您在 Microsoft Entra 系統管理中心所註冊應用程式的應用程式 (用戶端) 識別碼。 |
grant_type |
Yes | /signup/v1.0/continue 端點的要求可用來提交一次性密碼、密碼或使用者屬性。 在此情況下，會使用 grant_type 值來區分這三個使用案例。 grant_type 可能的值為 oob、password、attributes。 在此呼叫中，由於我們傳送了一次性密碼，因此該值應為 oob。 |
oob |
Yes | 客戶使用者在其電子郵件中收到的一次性密碼。 以客戶使用者在其電子郵件中收到的一次性密碼值取代 {otp_code}。 若要重新傳送一次性密碼，應用程式必須再次向 /signup/v1.0/challenge 端點提出要求。 |
一旦應用程式成功提交一次性密碼，註冊流程會視案例而定，如下所示：
| 案例 | 如何繼續進行 |
|---|---|
應用程式已透過 /signup/v1.0/start 端點成功提交使用者的密碼 (以密碼驗證方法傳送電子郵件)，且在 Microsoft Entra 系統管理中心未設定任何屬性，或所有使用者必要屬性均已透過 /signup/v1.0/start 端點提交。 |
Microsoft Entra 發出接續權杖。 應用程式可以使用接續權杖來要求安全性權杖，如步驟 5 所示。 |
應用程式透過 /signup/v1.0/start 成功提交使用者的密碼 (以密碼驗證方法傳送電子郵件)，但並未提交所有必要的使用者屬性，Microsoft Entra 會指出應用程式需要提交的屬性，如必要使用者屬性中所示。 |
應用程式必須透過 /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 |
Microsoft Entra 傳回的 接續權杖。 |
suberror |
錯誤碼字串，可用來進一步分類錯誤類型。 |
i以下是您可能會遇到的錯誤 (error 參數可能的值)：
| 錯誤值 | 描述 |
|---|---|
credential_required |
建立帳戶時需要驗證，因此您必須呼叫 /signup/v1.0/challenge 端點，才能判斷使用者必須提供的認證。 |
invalid_request |
要求參數驗證失敗，例如驗證 接續權杖 失敗，或要求未包含 client_id 參數時，用戶端識別碼的值為空白或無效，或外部租用戶系統管理員尚未為所有租用戶使用者啟用電子郵件 OTP。 |
invalid_grant |
要求中包含的授與類型無效或未受支援，或 OTP 值不正確。 |
expired_token |
要求中包含的接續權杖已過期。 |
如果 error 參數的值為 invalid_grant，Microsoft Entra 會在其回應中包含 suberror 參數。 以下是 invalid_grant 錯誤的 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 |
Yes | 您所建立的外部租用戶的子網域。 在 URL 中，將 {tenant_subdomain} 取代為目錄 (租用戶) 子網域。 例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。 |
client_id |
Yes | 您在 Microsoft Entra 系統管理中心所註冊應用程式的應用程式 (用戶端) 識別碼。 |
challenge_type |
No | 應用程式支援的授權 查問類型 字串清單 (以空格分隔)，例如 oob password redirect。 清單必須一律包含 redirect 查問類型。 對於附密碼電子郵件的註冊流程，此值預期會包含 password redirect。 |
continuation_token |
Yes | Microsoft Entra 在上一個要求中傳回的 接續權杖。 |
成功回應
如果密碼是為 Microsoft Entra 系統管理中心中的使用者設定的驗證方法，則會將附有接續權杖的成功回應傳回給應用程式。
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "password",
"continuation_token": " AQABAAEAAAAty..."
}
| 參數 | 描述 |
|---|---|
challenge_type |
密碼 會在所需認證的回應中傳回。 |
continuation_token |
Microsoft Entra 傳回的 接續權杖。 |
如果應用程式無法透過 Microsoft Entra 支援必要的驗證方法，則需要 Web 型驗證流程的後援。 在此案例中，Microsoft Entra 會在其回應中傳回 重新導向 查問類型，以通知應用程式：
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| 參數 | 描述 |
|---|---|
challenge_type |
Microsoft Entra 會傳回具有查問類型的回應。 此查問類型的值是重新導向，可讓應用程式使用 Web 型驗證流程。 |
此回應視為成功，但應用程式必須切換至 Web 型驗證流程。 在此情況下，建議您使用 Microsoft 建置且支援的驗證程式庫。
步驟 4：驗證並取得權杖以進行登入
應用程式必須提交使用者認證，在此案例中是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 |
Yes | 您所建立的外部租用戶的子網域。 在 URL 中，將 {tenant_subdomain} 取代為目錄 (租用戶) 子網域。 例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。 |
continuation_token |
Yes | Microsoft Entra 在上一個步驟中傳回的 接續權杖。 |
client_id |
Yes | 您在 Microsoft Entra 系統管理中心所註冊應用程式的應用程式 (用戶端) 識別碼。 |
grant_type |
Yes | /signup/v1.0/continue 端點的要求可用來提交一次性密碼、密碼或使用者屬性。 在此情況下，會使用 grant_type 值來區分這三個使用案例。 grant_type 可能的值為 oob、password、attributes。 在此呼叫中，由於我們傳送使用者的密碼，因此該值應為 密碼。 |
password |
Yes | 應用程式從客戶使用者收集的密碼值。 以應用程式從客戶使用者收集的密碼值取代 {secure_password}。 您必須負責確認使用者想要使用的密碼，方法是在應用程式的 UI 中提供密碼確認欄位。 您也必須確定使用者知道根據組織的原則，哪些內容構成強密碼。 深入瞭解 Microsoft Entra 的密碼原則。 |
成功回應
如果要求成功，但在 Microsoft Entra 系統管理中心未設定任何屬性，或所有必要屬性均已透過 /signup/v1.0/start 端點提交，則應用程式會取得接續權杖，而不提交任何屬性。 應用程式可以使用接續權杖來要求安全性權杖，如 步驟 5 所示。 否則，Microsoft Entra 的回應表示應用程式需要提交必要屬性。 這些內建或自訂的屬性是在租用戶系統管理員在 Microsoft Entra 系統管理中心設定的。
需要使用者屬性
此回應會要求應用程式提交 name、*age 和 phone 屬性的值。
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 |
Microsoft Entra 傳回的 接續權杖。 |
required_attributes |
應用程式需要提交，下一個呼叫才能繼續的屬性清單 (物件陣列)。 這些屬性是應用程式除了使用者名稱以外需要提交的額外屬性。 如果 error 參數的值為 attributes_required，則 Microsoft Entra 會在回應中包含此參數。 |
以下是您可能會遇到的錯誤(error 參數可能的值)：
| 錯誤值 | 描述 |
|---|---|
invalid_request |
要求參數驗證失敗，例如驗證 接續權杖 失敗，或要求未包含 client_id 參數時，用戶端識別碼值為空白或無效。 |
invalid_grant |
要求中包含的授與類型無效或未受支援。 grant_type 可能的值為 oob、password、attributes |
expired_token |
要求中包含的接續權杖已過期。 |
attributes_required |
需要一或多個使用者屬性。 |
如果應用程式無法透過 Microsoft Entra 支援必要的驗證方法，則需要 Web 型驗證流程的後援。 在此案例中，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_grant",
"error_description": "New password is too weak",
"error_codes": [
399246
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6",
"suberror": "password_too_weak"
}
| 參數 | 描述 |
|---|---|
error |
可用於將錯誤分類的錯誤碼字串，並回應錯誤。 |
error_description |
可協助您識別驗證錯誤原因的特定錯誤訊息。 |
error_codes |
Microsoft Entra 特定的錯誤碼清單，可協助您診斷錯誤。 |
timestamp |
錯誤發生時間。 |
trace_id |
要求的唯一識別碼，可協助您診斷錯誤。 |
correlation_id |
有助於跨元件診斷的要求唯一識別碼。 |
suberror |
錯誤碼字串，可用來進一步分類錯誤類型。 |
i以下是您可能會遇到的錯誤 (error 參數可能的值)：
| 錯誤值 | 描述 |
|---|---|
invalid_request |
要求參數驗證失敗，例如當 challenge_type 參數包含無效的查問類型時。 |
invalid_grant |
提交的授與無效，例如提交的密碼太短。 使用 suberror 參數來瞭解錯誤的確切原因。 |
expired_token |
接續權杖已過期。 |
attributes_required |
需要一或多個使用者屬性。 |
如果 error 參數的值為 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}", "postaCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...
| 參數 | 必要 | 描述: |
|---|---|---|
tenant_subdomain |
Yes | 您所建立的外部租用戶的子網域。 在 URL 中，將 {tenant_subdomain} 取代為目錄 (租用戶) 子網域。 例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。 |
continuation_token |
Yes | Microsoft Entra 在上一個要求中傳回的 接續權杖。 |
client_id |
Yes | 您在 Microsoft Entra 系統管理中心所註冊應用程式的應用程式 (用戶端) 識別碼。 |
grant_type |
Yes | /signup/v1.0/continue 端點的要求可用來提交一次性密碼、密碼或使用者屬性。 在此情況下，會使用 grant_type 值來區分這三個使用案例。 grant_type 可能的值為 oob、password、attributes。 在此呼叫中，由於我們要傳送使用者屬性，因此該值應為 attributes。 |
attributes |
Yes | 應用程式從客戶使用者收集的使用者屬性值。 該值是字串，但格式化為 JSON 物件，其索引鍵值是內建或自訂使用者屬性的名稱。 物件的索引鍵名稱取決於系統管理員在 Microsoft Entra 系統管理中心設定的屬性。 將 {given_name}、{user_age} 和 {postal_code} 分別取代為應用程式從客戶使用者收集的名稱、年齡和郵遞區號值。 Microsoft Entra 會忽略您所提交，但不存在的任何屬性。 |
成功回應
如果要求成功，Microsoft Entra 會簽發接續權杖，應用程式可用來要求安全性權杖。
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "AQABAAEAAAYn..."
}
| 參數 | 描述 |
|---|---|
continuation_token |
Microsoft Entra 傳回的 接續權杖。 |
如果應用程式無法透過 Microsoft Entra 支援必要的驗證方法，則需要 Web 型驗證流程的後援。 在此案例中，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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
552003
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| 參數 | 描述 |
|---|---|
error |
可用於將錯誤分類的錯誤碼字串，並回應錯誤。 |
error_description |
可協助您識別驗證錯誤原因的特定錯誤訊息。 |
error_codes |
Microsoft Entra 特定的錯誤碼清單，可協助您診斷錯誤。 |
timestamp |
錯誤發生時間。 |
trace_id |
要求的唯一識別碼，可協助您診斷錯誤。 |
correlation_id |
有助於跨元件診斷的要求唯一識別碼。 |
continuation_token |
Microsoft Entra 傳回的 接續權杖。 |
unverified_attributes |
必須驗證的屬性索引鍵名稱清單 (物件陣列)。 當 error 參數的值為 verification_required 時，這個參數會包含在回應中。 |
required_attributes |
應用程式需要提交的屬性的清單 (物件陣列)。 當 error 參數的值為 attributes_required時，Microsoft Entra 會在其回應中包含此參數。 |
invalid_attributes |
驗證失敗的屬性清單 (物件陣列)。 當 suberror 參數的值為 attribute_validation_failed 時，這個參數會包含在回應中。 |
suberror |
錯誤碼字串，可用來進一步分類錯誤類型。 |
i以下是您可能會遇到的錯誤 (error 參數可能的值)：
| 錯誤值 | 描述 |
|---|---|
invalid_request |
要求參數驗證失敗，例如驗證 接續權杖 失敗，或要求未包含 client_id 參數時，用戶端識別碼值為空白或無效。 |
invalid_grant |
提供的授與類型無效或支援或驗證失敗，例如屬性驗證失敗。 使用 suberror 參數來瞭解錯誤的確切原因。 |
expired_token |
要求中包含的接續權杖已過期。 |
attributes_required |
需要一或多個使用者屬性。 |
如果 error 參數的值為 invalid_grant，Microsoft Entra 會在其回應中包含 suberror 參數。 以下是 invalid_grant 錯誤的 suberror 參數可能的值：
| Suberror 值 | 描述 |
|---|---|
attribute_validation_failed |
使用者屬性驗證失敗。 invalid_attributes 參數包含無法驗證的屬性清單(物件陣列)。 |
步驟 5：要求安全性權杖
應用程式向 /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=ABAAEAAAAtyo...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&username=contoso-consumer@contoso.com
&scope={scopes}
&grant_type=continuation_token
| 參數 | 必要 | 描述: |
|---|---|---|
tenant_subdomain |
Yes | 您所建立的外部租用戶的子網域。 在 URL 中，將 {tenant_subdomain} 取代為目錄 (租用戶) 子網域。 例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。 |
client_id |
Yes | 您在 Microsoft Entra 系統管理中心所註冊應用程式的應用程式 (用戶端) 識別碼。 |
grant_type |
Yes | 參數值必須為 continuation token。 |
continuation_token |
Yes | Microsoft Entra 在上一個步驟中傳回的 接續權杖。 |
scope |
Yes | 存取權杖有效範圍的清單，以空格分隔。 將 {scopes} 取代為 Microsoft Entra 傳回的存取權杖的有效範圍。 |
username |
Yes | 客戶使用者要用來註冊的電子郵件，例如 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..."
}
| 參數 | 描述 |
|---|---|
access_token |
應用程式從 /token 端點所要求的存取權杖。 應用程式可以使用此存取權杖來要求存取受保護的資源，例如 Web API。 |
token_type |
指出權杖類型的值。 Microsoft Entra 支援的唯一類型是 Bearer。 |
expires_in |
存取權杖仍然有效的時間長度，以秒為單位。 |
scopes |
存取權杖有效範圍的清單，以空格分隔。 |
refresh_token |
OAuth 2.0 重新整理權杖。 應用程式可以使用這個權杖，在目前的存取權杖過期之後，取得其他的存取權杖。 重新整理權杖會長期存在。 他們可以在延長的期間內維護資源的存取權。 如需重新整理存取權杖的詳細資訊，請參閱 重新整理存取權杖 一文。 備註：只有在要求 offline_access 範圍時才發出。 |
id_token |
用來識別客戶使用者的 JSON Web 權杖 (Jwt)。 應用程式可以將權杖解碼，以讀取登入使用者的相關資訊。 應用程式可以快取這些值並加以顯示，而機密用戶端可以使用此權杖來進行授權。 如需識別碼權杖的詳細資訊，請參閱 識別碼權杖。 備註：只有在要求 openid 範圍時才會發出。 |
回覆錯誤
範例：
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The client doesn't have consent for the requested scopes.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
50126
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| 參數 | 描述 |
|---|---|
error |
可用於將錯誤分類的錯誤碼字串，並回應錯誤。 |
error_description |
可協助您識別驗證錯誤原因的特定錯誤訊息。 |
error_codes |
Microsoft Entra 特定的錯誤碼清單，可協助您診斷錯誤。 |
timestamp |
錯誤發生時間。 |
trace_id |
要求的唯一識別碼，可協助您診斷錯誤。 |
correlation_id |
有助於跨元件診斷的要求唯一識別碼。 |
i以下是您可能會遇到的錯誤 (error 參數可能的值)：
| 錯誤值 | 描述 |
|---|---|
invalid_request |
要求參數驗證失敗，例如用戶端/應用程式未同意要求的範圍。 |
invalid_grant |
要求中包含的接續權杖無效。 |
unauthorized_client |
要求中包含的用戶端識別碼無效或不存在。 |
unsupported_grant_type |
要求中包含的授與類型未受支援或不正確。 |
將使用者屬性提交至端點
在 Microsoft Entra 系統管理中心，您可以將使用者屬性設定為必要或選擇性。 此組態會決定當您呼叫其端點時，Microsoft Entra 回應的方式。 完成註冊流程並不需要選擇性屬性。 因此，當所有屬性均為選擇性屬性時，必須先提交這些屬性，才能驗證使用者名稱。 否則，註冊會完成，但不含選擇性屬性。
下表摘要說明何時可以將使用者屬性提交至Microsoft Entra 端點。
| 端點 | 必要屬性 | 選用屬性 | 必要和選擇性屬性兩者 |
|---|---|---|---|
/signup/v1.0/start 端點 |
Yes | .是 | Yes |
使用者名稱驗證之前的 /signup/v1.0/continue 端點 |
Yes | .是 | Yes |
使用者名稱驗證之後的 /signup/v1.0/continue 端點 |
是 | 無 | Yes |
使用者屬性值的格式
您可以在 Microsoft Entra 系統管理中心設定使用者流程設定，以指定您想要從使用者收集的資訊。 使用 在註冊期間收集自訂使用者屬性 這篇文章，瞭解如何收集內建和自訂屬性的值。
您也可以為您所設定的屬性指定 使用者輸入類型。 下表摘要說明支援的使用者輸入類型，以及如何將 UI 控制項收集的值提交至 Microsoft Entra。
| 使用者輸入類型 | 提交值的格式 |
|---|---|
| TextBox | 職稱等單一值，軟體工程師。 |
| 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 中參考內建和自訂使用者屬性。
登入 API 參考
使用者需要使用註冊的驗證方法登入。 例如，使用密碼驗證方法註冊電子郵件的使用者必須登入電子郵件和密碼。
若要要求安全性權杖，您的應用程式會與 /initiate、/challenge 和 /token 這三個端點互動。
登入 API 端點
| 端點 | 描述 |
|---|---|
/initiate |
此端點會起始登入流程。 如果您的應用程式使用已存在的使用者帳戶的使用者名稱來呼叫它，則會傳回具有接續權杖的成功回應。 如果您的應用程式要求使用 Microsoft Entra 不支援的驗證方法，此端點回應可以向您的應用程式指出它需要使用瀏覽器型驗證流程。 |
/challenge |
您的應用程式會使用身分識別服務支援的 查問清單 來呼叫此端點。 我們的身分識別服務會產生一次性密碼，然後將其傳送至所選的查問通道，例如電子郵件。 如果您的應用程式重複呼叫此端點，每次呼叫時都會傳送新的 OTP。 |
/token |
此端點會驗證它從您的應用程式收到的一次性密碼，然後向您的應用程式發出安全性權杖。 |
登入查問類型
API 可讓應用程式在呼叫 Microsoft Entra 時，公告其支援的驗證方法。 若要這樣做，應用程式會在其要求中使用 challenge_type 參數。 此參數會保留預先定義的值，代表不同的驗證方法。
針對指定的驗證方法，應用程式在註冊流程期間傳送至 Microsoft Entra 的查問類型值會與應用程式登入時相同。 例如，具有密碼驗證方法的電子郵件會針對註冊和登入流程使用 oob、 password 和 redirect 挑戰類型值。
深入了解原生驗證挑戰類型一文中的挑戰類型。
登入流程通訊協定詳細資料
此循序圖示範登入程式的流程。
應用程式使用 OTP 驗證使用者的電子郵件後，就會收到安全性權杖。 如果一次性密碼的傳遞延遲或從未傳遞至使用者的電子郵件，使用者可以要求傳送另一個一次性密碼。 如果前一個密碼尚未驗證，Microsoft Entra 會重新傳送另一個一次性密碼。 當 Microsoft Entra 重新傳送一次性密碼時，它會使先前傳送的密碼失效。
在後續各節中，我們將循序圖流程摘要為三個基本步驟。
步驟 1：要求啟動登入流程
驗證流程開始時，應用程式會向 /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
| 參數 | 必要 | 描述: |
|---|---|---|
tenant_subdomain |
Yes | 您所建立的外部租用戶的子網域。 在 URL 中，將 {tenant_subdomain} 取代為目錄 (租用戶) 子網域。 例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。 |
client_id |
Yes | 您在 Microsoft Entra 系統管理中心所註冊應用程式的應用程式 (用戶端) 識別碼。 |
username |
Yes | 客戶使用者的電子郵件，例如 contoso-consumer@contoso.com。 |
challenge_type |
Yes | 應用程式支援的授權 查問類型 字串清單 (以空格分隔)，例如 oob password redirect。 清單必須一律包含 redirect 查問類型。 對於電子郵件一次性密碼，該值預期為 oob redirect，對於具有密碼的電子郵件，該值為 password redirect。 |
成功回應
以下是成功回應的範例：
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| 參數 | 描述 |
|---|---|
continuation_token |
Microsoft Entra 傳回的 接續權杖。 |
如果應用程式無法透過 Microsoft Entra 支援必要的驗證方法，則需要 Web 型驗證流程的後援。 在此案例中，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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| 參數 | 描述 |
|---|---|
error |
可用於將錯誤分類的錯誤碼字串，並回應錯誤。 |
error_description |
可協助您識別驗證錯誤原因的特定錯誤訊息。 |
error_codes |
Microsoft Entra 特定的錯誤碼清單，可協助您診斷錯誤。 |
timestamp |
錯誤發生時間。 |
trace_id |
要求的唯一識別碼，可協助您診斷錯誤。 |
correlation_id |
有助於跨元件診斷的要求唯一識別碼。 |
i以下是您可能會遇到的錯誤 (error 參數可能的值)：
| 錯誤值 | 描述 |
|---|---|
invalid_request |
要求參數驗證失敗，例如當 challenge_type 參數包含無效的查問類型時。 或要求未包含 client_id 參數時，用戶端識別碼的值為空白或無效。 使用 error_description 參數來瞭解錯誤的確切原因。 |
unauthorized_client |
要求中使用的用戶端識別碼具有有效的用戶端識別碼格式，但不存在於外部租用戶中或不正確。 |
invalid_client |
應用程式在要求中包含的用戶端識別碼是針對缺少原生驗證組態的應用程式，例如不是公用用戶端或未啟用原生驗證。 使用 suberror 參數來瞭解錯誤的確切原因。 |
user_not_found |
使用者名稱不存在。 |
unsupported_challenge_type |
challenge_type 參數值不包含 redirect 查問類型。 |
如果 error 參數的值為 invalid_client，Microsoft Entra 會在其回應中包含 suberror 參數。 以下是 invalid_client 錯誤的 suberror 參數可能的值：
| Suberror 值 | 描述 |
|---|---|
nativeauthapi_disabled |
未啟用原生驗證的應用程式的用戶端識別碼。 |
步驟 2：選取驗證方法
若要繼續進行流程，應用程式會使用從上一個步驟取得的接續權杖來要求 Microsoft Entra，以選取其中一個支援的查問類型，讓使用者進行驗證。 應用程式向 /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 |
Yes | 您所建立的外部租用戶的子網域。 在 URL 中，將 {tenant_subdomain} 取代為目錄 (租用戶) 子網域。 例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。 |
client_id |
Yes | 您在 Microsoft Entra 系統管理中心所註冊應用程式的應用程式 (用戶端) 識別碼。 |
continuation_token |
Yes | Microsoft Entra 在上一個要求中傳回的 接續權杖。 |
challenge_type |
No | 應用程式支援的授權 查問類型 字串清單 (以空格分隔)，例如 oob password redirect。 清單必須一律包含 redirect 查問類型。 對於電子郵件一次性密碼，該值預期為 oob redirect，對於具有密碼的電子郵件，該值為 password redirect。 |
成功回應
如果租用戶系統管理員在 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 |
Microsoft Entra 傳回的 接續權杖。 |
challenge_type |
為使用者選取以進行驗證的查問類型。 |
binding_method |
唯一有效的值是 prompt。 這個參數未來可以用來為使用者提供更多方式來輸入一次性密碼。 如果 challenge_type 為 oob，則發出 |
challenge_channel |
傳送一次性密碼的通道類型。 目前，我們支援電子郵件。 |
challenge_target_label |
模糊化的電子郵件，其中傳送了一次性密碼。 |
code_length |
Microsoft Entra 產生的一次性密碼的長度。 |
如果應用程式無法透過 Microsoft Entra 支援必要的驗證方法，則需要 Web 型驗證流程的後援。 在此案例中，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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| 參數 | 描述 |
|---|---|
error |
可用於將錯誤分類的錯誤碼字串，並回應錯誤。 |
error_description |
可協助您識別驗證錯誤原因的特定錯誤訊息。 |
error_codes |
Microsoft Entra 特定的錯誤碼清單，可協助您診斷錯誤。 |
timestamp |
錯誤發生時間。 |
trace_id |
要求的唯一識別碼，可協助您診斷錯誤。 |
correlation_id |
有助於跨元件診斷的要求唯一識別碼。 |
i以下是您可能會遇到的錯誤 (error 參數可能的值)：
| 錯誤值 | 描述 |
|---|---|
invalid_request |
要求參數驗證失敗，例如當 challenge_type 參數包含無效的查問類型時。 |
invalid_grant |
要求中包含的接續權杖無效。 |
expired_token |
要求中包含的接續權杖已過期。 |
unsupported_challenge_type |
challenge_type 參數值不包含 redirect 查問類型。 |
步驟 3：要求安全性權杖
應用程式會向 /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 |
Yes | 您所建立的外部租用戶的子網域。 在 URL 中，將 {tenant_subdomain} 取代為目錄 (租用戶) 子網域。 例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。 |
client_id |
Yes | 您在 Microsoft Entra 系統管理中心所註冊應用程式的應用程式 (用戶端) 識別碼。 |
continuation_token |
Yes | Microsoft Entra 在上一個要求中傳回的 接續權杖。 |
grant_type |
Yes | 對於具有密碼驗證方法的電子郵件，該值必須是 password，而對於電子郵件單次密碼驗證方法，該值則為 oob。 |
scope |
Yes | 以空格分隔的範圍清單。 所有範圍都必須來自單一資源，以及 OpenID Connect (OIDC) 範圍，例如 設定檔、*openid 和 電子郵件。 應用程式必須包含 openid 範圍，Microsoft Entra 才能發出識別碼權杖。 應用程式必須包含 offline_access 範圍，Microsoft Entra 才能發出重新整理權杖。 深入了解 Microsoft 身分識別平台中的權限和同意。 |
password |
是 (含密碼的電子郵件) |
應用程式從客戶使用者收集的密碼值。 以應用程式從客戶使用者收集的密碼值取代 {secure_password}。 |
oob |
是 (用於電子郵件一次性密碼) |
客戶使用者在其電子郵件中收到的一次性密碼。 以客戶使用者在其電子郵件中收到的一次性密碼取代 {otp_code}。 若要重新傳送一次性密碼，應用程式必須再次向 /challenge 端點提出要求。 |
成功回應
以下是成功回應的範例：
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 支援的唯一類型是 Bearer。 |
scopes |
存取權杖有效範圍的清單，以空格分隔。 |
expires_in |
存取權杖仍然有效的時間長度，以秒為單位。 |
access_token |
應用程式從 /token 端點所要求的存取權杖。 應用程式可以使用此存取權杖來要求存取受保護的資源，例如 Web API。 |
refresh_token |
OAuth 2.0 重新整理權杖。 應用程式可以使用這個權杖，在目前的存取權杖過期之後，取得其他的存取權杖。 重新整理權杖會長期存在。 他們可以在延長的期間內維護資源的存取權。 如需重新整理存取權杖的詳細資訊，請參閱重新整理存取權杖一文。 注意：只有在您要求 offline_access 範圍時才發出。 |
id_token |
用來識別客戶使用者的 JSON Web 權杖 (Jwt)。 應用程式可以將權杖解碼，以要求登入使用者的相關資訊。 應用程式可以快取這些值並加以顯示，而機密用戶端可以使用此權杖來進行授權。 如需識別碼權杖的詳細資訊，請參閱識別碼權杖。 注意：只有在您要求 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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
50126
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| 參數 | 描述 |
|---|---|
error |
可用於將錯誤分類的錯誤碼字串，並回應錯誤。 |
error_description |
可協助您識別驗證錯誤原因的特定錯誤訊息。 |
error_codes |
Microsoft Entra 特定的錯誤碼清單，可協助您診斷錯誤。 |
timestamp |
錯誤發生時間。 |
trace_id |
要求的唯一識別碼，可協助您診斷錯誤。 |
correlation_id |
有助於跨元件診斷的要求唯一識別碼。 |
i以下是您可能會遇到的錯誤 (error 參數可能的值)：
| 錯誤值 | 描述 |
|---|---|
invalid_request |
要求參數驗證失敗。 若要瞭解所發生的情況，請使用錯誤描述中的訊息。 |
invalid_grant |
要求中包含的接續權杖無效，或要求中包含的客戶使用者認證無效，或要求中包含未知的授與類型。 |
invalid_client |
要求中包含的用戶端標識碼不適用於公用用戶端。 |
expired_token |
要求中包含的接續權杖已過期。 |
invalid_scope |
要求中包含的一或多個範圍無效。 |
如果 error 參數的值為 invalid_grant，Microsoft Entra 會在其回應中包含 suberror 參數。 以下是 invalid_grant 錯誤的 suberror 參數可能的值：
| Suberror 值 | 描述 |
|---|---|
invalid_oob_value |
一次性密碼的值無效。 此子錯誤只適用於電子郵件一次性密碼 |
自助式密碼重設 (SSPR)
如果您使用電子郵件和密碼作為應用程式中的驗證方法，請使用自助式密碼重設 (SSPR) API，讓客戶使用者重設其密碼。 將此 API 用於忘記密碼或變更密碼案例。
自助式密碼重設 API 端點
若要使用此 API，應用程式會與下表所示的端點互動：
| 端點 | 描述 |
|---|---|
/start |
當客戶使用者選取 [忘記密碼] 或 [變更密碼] 連結或應用程式中的按鈕時，您的應用程式會呼叫此端點。 此端點會驗證使用者的使用者名稱 (電子郵件)，然後傳回用於密碼重設流程的 接續權杖。 如果您的應用程式要求使用 Microsoft Entra 不支援的驗證方法，此端點回應可以向您的應用程式指出它需要使用瀏覽器型驗證流程。 |
/challenge |
接受用戶端支援的查問清單，以及 接續權杖。 查問會發出給其中一個慣用的復原認證。 例如，oob 查問會向與客戶使用者帳戶關聯的電子郵件發出頻外一次性密碼。 如果您的應用程式要求使用 Microsoft Entra 不支援的驗證方法，此端點回應可以向您的應用程式指出它需要使用瀏覽器型驗證流程。 |
/continue |
驗證 /challenge 端點發出的查問，然後針對 /submit 端點傳回 接續權杖，或對使用者發出另一個查問。 |
/submit |
接受使用者與 接續權杖 的新密碼輸入，以完成密碼重設流程。 此端點會發出另一個 接續權杖。 |
/poll_completion |
最後，應用程式可以使用 /submit 端點發出的 接續權杖 來檢查密碼重設要求的狀態。 |
自助式密碼重設查問類型
API 可讓應用程式在呼叫 Microsoft Entra 時，公告其支援的驗證方法。 若要這樣做，應用程式會在其要求中使用 challenge_type 參數。 此參數會保留預先定義的值，代表不同的驗證方法。
針對 SSPR 流程，查問類型值會 oob 和 redirect。
深入瞭解 原生驗證查問類型 中的查問類型。
自助式密碼重設流程通訊協定詳細資料
此循序圖示範密碼重設程序的流程。
此圖指出應用程式會在不同的時間收集使用者的使用者名稱 (電子郵件) 和密碼 (可能在不同的畫面上)。 不過，您可以將應用程式設計為在同一個畫面上收集使用者名稱 (電子郵件) 和新密碼。 在此情況下，應用程式會保存密碼，然後透過所需的 /submit 端點提交密碼。
步驟 1：要求啟動自助式密碼重設流程
密碼重設流程開始時，應用程式會向 /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 |
Yes | 您所建立的外部租用戶的子網域。 在 URL 中，將 {tenant_subdomain} 取代為目錄 (租用戶) 子網域。 例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。 |
client_id |
Yes | 您在 Microsoft Entra 系統管理中心所註冊應用程式的應用程式 (用戶端) 識別碼。 |
username |
Yes | 客戶使用者的電子郵件，例如 contoso-consumer@contoso.com。 |
challenge_type |
Yes | 應用程式支援的授權 查問類型 字串清單 (以空格分隔)，例如 oob password redirect。 清單必須一律包含 redirect 查問類型。 針對此要求，該值預期會包含 oob redirect。 |
成功回應
範例：
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| 參數 | 描述 |
|---|---|
continuation_token |
Microsoft Entra 傳回的 接續權杖。 |
如果應用程式無法透過 Microsoft Entra 支援必要的驗證方法，則需要 Web 型驗證流程的後援。 在此案例中，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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| 參數 | 描述 |
|---|---|
error |
可用於將錯誤分類的錯誤碼字串，並回應錯誤。 |
error_description |
可協助您識別驗證錯誤原因的特定錯誤訊息。 |
error_codes |
Microsoft Entra 特定的錯誤碼清單，可協助您診斷錯誤。 |
timestamp |
錯誤發生時間。 |
trace_id |
要求的唯一識別碼，可協助您診斷錯誤。 |
correlation_id |
有助於跨元件診斷的要求唯一識別碼。 |
i以下是您可能會遇到的錯誤 (error 參數可能的值)：
| 錯誤值 | 描述 |
|---|---|
invalid_request |
要求參數驗證失敗，例如當 challenge_type 參數包含無效的查問類型，或要求不包含 client_id 參數時，用戶端識別碼值為空白或無效。 使用 error_description 參數來瞭解錯誤的確切原因。 |
user_not_found |
使用者名稱不存在。 |
unsupported_challenge_type |
challenge_type 參數值不包含 redirect 查問類型。 |
invalid_client |
應用程式在要求中包含的用戶端識別碼是針對缺少原生驗證組態的應用程式，例如不是公用用戶端或未啟用原生驗證。 使用 suberror 參數來瞭解錯誤的確切原因。 |
unauthorized_client |
要求中使用的用戶端識別碼具有有效的用戶端識別碼格式，但不存在於外部租用戶中或不正確。 |
如果 error 參數的值為 invalid_client，Microsoft Entra 會在其回應中包含 suberror 參數。 以下是 invalid_client 錯誤的 suberror 參數可能的值：
| Suberror 值 | 描述 |
|---|---|
nativeauthapi_disabled |
未啟用原生驗證的應用程式的用戶端識別碼。 |
步驟 2：選取驗證方法
若要繼續進行流程，應用程式會使用從上一個步驟取得的接續權杖來要求 Microsoft Entra，以選取其中一個支援的查問類型，讓使用者進行驗證。 應用程式向 /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=client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY...
| 參數 | 必要 | 描述: |
|---|---|---|
tenant_subdomain |
Yes | 您所建立的外部租用戶的子網域。 在 URL 中，將 {tenant_subdomain} 取代為目錄 (租用戶) 子網域。 例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。 |
client_id |
Yes | 您在 Microsoft Entra 系統管理中心所註冊應用程式的應用程式 (用戶端) 識別碼。 |
continuation_token |
Yes | Microsoft Entra 在上一個要求中傳回的 接續權杖。 |
challenge_type |
No | 應用程式支援的授權 查問類型 字串清單 (以空格分隔)，例如 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 |
Microsoft Entra 傳回的 接續權杖。 |
challenge_type |
為使用者選取以進行驗證的查問類型。 |
binding_method |
唯一有效的值是 prompt。 這個參數未來可以用來為使用者提供更多方式來輸入一次性密碼。 如果 challenge_type 為 oob，則發出 |
challenge_channel |
傳送一次性密碼的通道類型。 目前，我們支援電子郵件。 |
challenge_target_label |
模糊化的電子郵件，其中傳送了一次性密碼。 |
code_length |
Microsoft Entra 產生的一次性密碼的長度。 |
如果應用程式無法透過 Microsoft Entra 支援必要的驗證方法，則需要 Web 型驗證流程的後援。 在此案例中，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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| 參數 | 描述 |
|---|---|
error |
可用於將錯誤分類的錯誤碼字串，並回應錯誤。 |
error_description |
可協助您識別驗證錯誤原因的特定錯誤訊息。 |
error_codes |
Microsoft Entra 特定的錯誤碼清單，可協助您診斷錯誤。 |
timestamp |
錯誤發生時間。 |
trace_id |
要求的唯一識別碼，可協助您診斷錯誤。 |
correlation_id |
有助於跨元件診斷的要求唯一識別碼。 |
i以下是您可能會遇到的錯誤 (error 參數可能的值)：
| 錯誤值 | 描述 |
|---|---|
invalid_request |
要求參數驗證失敗，例如當 challenge_type 參數包含無效的查問類型或 接續權杖 驗證失敗時。 |
expired_token |
接續權杖已過期。 |
unsupported_challenge_type |
challenge_type 參數值不包含 redirect 查問類型。 |
步驟 3：提交一次性密碼
應用程式接著會向 /continue 端點提出 POST 要求。 在要求中，應用程式必須包含上一個步驟中選擇的使用者認證，以及從 /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 |
Yes | 您所建立的外部租用戶的子網域。 在 URL 中，將 {tenant_subdomain} 取代為目錄 (租用戶) 子網域。 例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。 |
continuation_token |
Yes | Microsoft Entra 在上一個要求中傳回的 接續權杖。 |
client_id |
Yes | 您在 Microsoft Entra 系統管理中心所註冊應用程式的應用程式 (用戶端) 識別碼。 |
grant_type |
Yes | 唯一有效的值是 oob。 |
oob |
Yes | 客戶使用者在其電子郵件中收到的一次性密碼。 以客戶使用者在其電子郵件中收到的一次性密碼取代 {otp_code}。 若要 重新傳送一次性密碼，應用程式必須再次向 /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 |
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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
55200
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| 參數 | 描述 |
|---|---|
error |
可用於將錯誤分類的錯誤碼字串，並回應錯誤。 |
error_description |
可協助您識別驗證錯誤原因的特定錯誤訊息。 |
error_codes |
Microsoft Entra 特定的錯誤碼清單，可協助您診斷錯誤。 |
timestamp |
錯誤發生時間。 |
trace_id |
要求的唯一識別碼，可協助您診斷錯誤。 |
correlation_id |
有助於跨元件診斷的要求唯一識別碼。 |
suberror |
錯誤碼字串，可用來進一步分類錯誤類型。 |
i以下是您可能會遇到的錯誤 (error 參數可能的值)：
| 錯誤值 | 描述 |
|---|---|
invalid_request |
要求參數驗證失敗，例如驗證 接續權杖 失敗，或要求不包含 client_id 參數時，用戶端識別碼值為空白或無效，或外部租用戶系統管理員尚未為所有租用戶使用者啟用 SSPR 和電子郵件 OTP。 使用 error_description 參數來瞭解錯誤的確切原因。 |
invalid_grant |
授與類型未知或不符合預期的授與類型值。 使用 suberror 參數來瞭解錯誤的確切原因。 |
expired_token |
接續權杖已過期。 |
如果 error 參數的值為 invalid_grant，Microsoft Entra 會在其回應中包含 suberror 參數。 以下是 invalid_grant 錯誤的 suberror 參數可能的值：
| Suberror 值 | 描述 |
|---|---|
invalid_oob_value |
使用者提供的一次性密碼無效。 |
步驟 4：提交新密碼
應用程式會從使用者收集新的密碼，然後使用 /continue 端點發出的 接續權杖，透過向 /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 |
Yes | 您所建立的外部租用戶的子網域。 在 URL 中，將 {tenant_subdomain} 取代為目錄 (租用戶) 子網域。 例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。 |
continuation_token |
Yes | Microsoft Entra 在上一個要求中傳回的 接續權杖。 |
client_id |
Yes | 您在 Microsoft Entra 系統管理中心所註冊應用程式的應用程式 (用戶端) 識別碼。 |
new_password |
Yes | 使用者的新密碼。 以使用者的新密碼取代 {new_password}。 您必須負責確認使用者想要使用的密碼，方法是在應用程式的 UI 中提供密碼確認欄位。 您也必須確定使用者知道根據組織的原則，哪些內容構成強密碼。 深入瞭解 Microsoft Entra 的密碼原則。 |
成功回應
範例：
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY...",
"poll_interval": 2
}
| 參數 | 描述 |
|---|---|
continuation_token |
Microsoft Entra 傳回的 接續權杖。 |
poll_interval |
應用程式在透過 /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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| 參數 | 描述 |
|---|---|
error |
可用於將錯誤分類的錯誤碼字串，並回應錯誤。 |
error_description |
可協助您識別驗證錯誤原因的特定錯誤訊息。 |
error_codes |
Microsoft Entra 特定的錯誤碼清單，可協助您診斷錯誤。 |
timestamp |
錯誤發生時間。 |
trace_id |
要求的唯一識別碼，可協助您診斷錯誤。 |
correlation_id |
有助於跨元件診斷的要求唯一識別碼。 |
suberror |
錯誤碼字串，可用來進一步分類錯誤類型。 |
i以下是您可能會遇到的錯誤 (error 參數可能的值)：
| 錯誤值 | 描述 |
|---|---|
invalid_request |
要求參數驗證失敗，例如 接續權杖 驗證失敗。 |
expired_token |
接續權杖 已過期。 |
invalid_grant |
提交的授與無效，例如提交的密碼太短。 使用 suberror 參數來瞭解錯誤的確切原因。 |
如果 error 參數的值為 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：輪詢密碼重設狀態
最後，由於使用新密碼更新使用者的設定會產生一些延遲，因此應用程式可以使用 /poll_completion 端點來輪詢 Microsoft Entra 以取得密碼重設狀態。 應用程式在輪詢要求之間應該等候的最短時間 (以秒為單位) 將由 /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 |
Yes | 您所建立的外部租用戶的子網域。 在 URL 中，將 {tenant_subdomain} 取代為目錄 (租用戶) 子網域。 例如，如果您的租用戶的主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租用戶的子網域，瞭解如何閱讀租用戶詳細資料。 |
continuation_token |
Yes | Microsoft Entra 在上一個要求中傳回的 接續權杖。 |
client_id |
Yes | 您在 Microsoft Entra 系統管理中心所註冊應用程式的應用程式 (用戶端) 識別碼。 |
成功回應
範例：
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "succeeded",
"continuation_token":"czZCaGRSa3F0..."
}
| 參數 | 描述 |
|---|---|
status |
重設密碼要求的狀態。 如果 Microsoft Entra 傳回 失敗 狀態，應用程式可以向 /submit 端點提出另一個要求並包含新的接續權杖，以重新提交新的密碼。 |
continuation_token |
Microsoft Entra 傳回的 接續權杖。 如果狀態為 成功，應用程式可以使用 Microsoft Entra 傳回的接續權杖，透過 /token 端點要求安全性權杖，如 註冊流程 步驟 5 中所述。 這表示使用者成功重設其密碼之後，您可以直接登入您的應用程式，而不需要起始新的登入流程。 |
以下是 Microsoft Entra 傳回的可能狀態 (status 參數可能的值)：
| 錯誤值 | 描述 |
|---|---|
succeeded |
密碼重設成功完成。 |
failed |
密碼重設失敗。 應用程式可以向 /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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
552003
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| 參數 | 描述 |
|---|---|
error |
可用於將錯誤分類的錯誤碼字串，並回應錯誤。 |
error_description |
可協助您識別驗證錯誤原因的特定錯誤訊息。 |
error_codes |
Microsoft Entra 特定的錯誤碼清單，可協助您診斷錯誤。 |
timestamp |
錯誤發生時間。 |
trace_id |
要求的唯一識別碼，可協助您診斷錯誤。 |
correlation_id |
有助於跨元件診斷的要求唯一識別碼。 |
i以下是您可能會遇到的錯誤 (error 參數可能的值)：
| 錯誤值 | 描述 |
|---|---|
invalid_request |
要求參數驗證失敗，例如驗證 接續權杖 失敗。 |
expired_token |
接續權杖 已過期。 |