適用於:
外部租戶(了解更多)
認證方式: 嵌入式原生驗證。
原生驗證流程是一種回應驅動的交易。 Microsoft Entra 外部 ID 會回傳目前狀態、所需動作及允許操作。 您的應用程式會呈現介面,並透過使用者選擇或應用程式流程邏輯選擇允許的操作。
授權貫穿整個流程
Important
原生驗證 API V2 目前處於預覽階段。 原生驗證 API V1 仍然正式推出。 請參閱 Microsoft Azure 預覽補充使用條款,了解適用於預覽功能的法律條款。
初始授權挑戰要求包含應用程式 ID、要求的範圍及選用宣告。 若需驗證,其 401 InsufficientAuthorization 回應包含延續權杖及旅程連結。 此回應是邀請互動,而非密碼檢查失敗。
持續使用已設定的服務授權單位來進行授權、原生互動及權杖交換。 原生驗證 API V2 對於瀏覽器端應用程式(如 SPA)要求租戶驗證的自訂網域,但非瀏覽器用戶端(如使用原生 HTTP 傳輸的 iOS 和 Android 應用程式)則不需。 範例中使用自訂網域與租戶 GUID。 參見 運作與權限。
當服務傳回 state: continue 時,登入、註冊及密碼重設都會返回授權頁面。 您的應用程式會將最新的續接權杖傳送至傳回的 continue 連結。 接著它會在令牌端點交換產生的授權碼。
在密碼驗證、建立帳號或密碼更新後,應用程式會處理剩餘的政策要求,並在請求令牌前恢復授權。
這些授權界線說明了嵌入式原生驗證。 BYO UX 會使用其瀏覽器交接與回傳 Finish Link 之間共用的原生互動操作。 其自架頁面不會啟動或恢復 /authorize-challenge;依賴應用程式會完成原始的瀏覽器授權流程。 請參閱 「選擇驗證方式」。
| 邊界 | 請求或回應 |
|---|---|
| 開始授權 | 表單編碼 client_id、 scope、 response_type=code及可選的 claims。 |
| 開始旅程 | 頂層 sign_in、sign_up 或 reset_password URL,以及來自 OAuth 回應的 continuation_token。 |
| 互動 | 包含 continuationToken、狀態、動作與連結的 JSON 請求和 HAL 回應。 |
| 恢復授權 | 表單編碼, continuation_token僅在當前回應允許繼續時才發送。 |
| 請求令牌 | 以表單編碼進行的授權碼交換。 |
以下序列說明授權邊界與回應驅動的互動迴圈。 遵循目前的回應,而不是硬性編碼圖表的順序。
目前的回應是控制模型
每一次成功的原生驗證回應都會取代先前的互動模型。 租戶政策、應用程式的使用者流程以及交易狀態可以新增、重複或重新排序動作。 應用程式會從最新的回應中選擇操作,並根據回傳的需求來組織畫面。
| 狀態或行動 | 對客戶的意義 |
|---|---|
interactionRequired |
依照允許的操作進行處理 action ,並在需要時收集使用者輸入。 |
continue |
請依照 _links.continue 操作以恢復授權。 |
redirect |
停止原生交易。 此回應只能包含 state,不含延續權杖或瀏覽器網址。 已設定好的瀏覽器登入會啟動新的嘗試。 |
discover |
收集使用者的登入識別碼。 |
disambiguate |
識別 state: interactionRequired 下的帳戶選取。 |
collectAttributes |
收集所要求的註冊屬性。 |
challenge |
開始所選方法的驗證流程。 |
verify |
請提交所要求的密碼或一次性密碼。 |
enroll |
選擇顯示的方法並提交其登記資料。 |
activate |
提交一次性密碼以啟用已註冊的方法。 |
update |
提交替換密碼。 |
poll |
檢查非同步密碼更新。 |
例如,登入可以回傳密碼方式,接著是驗證動作,然後是電子郵件或簡訊方式,用於多重要素驗證(MFA)。 應用程式會先處理額外驗證因素,然後才恢復授權。
註冊時,提交電子郵件即可立即傳送驗證碼並回傳驗證連結 verify。 應用程式會收集該驗證碼並使用回傳的驗證連結。
完成單一操作並不代表應用程式擁有代幣。 在此描述的原生旅程中, continue 允許授權恢復;隨後的代碼交換則取得代幣。 狀態 completed 表示該操作已完成;不一定表示已登入的結果或包含其他連結。
接續權杖連結下一個操作
延續代幣代表交易在特定階段的狀態。 它受租戶、客戶、情境及當前行動所約束。 OAuth 訊息會命名它 continuation_token;原生驗證訊息則會命名它 continuationToken。
只保留目前交易的最新代幣。 把它和同一個回覆裡的連結配對看看。 不要解析、修改、記錄或在交易結束後持續保存它,也不要把它用在其他使用者或其他旅程上。 授權過期後重新啟動,而不是重新使用較舊的權杖。
個別續接令牌的文件記載的預設有效期為 10 分鐘。 較新的權杖並不保證整個流程會延長。 延續令牌與一次性密碼具有不同的有效期;依照服務回應處理到期。
方法識別碼與回傳的 URL 皆不透明。 原生驗證 API 範例使用 /api/v2.0。 請依循回傳的連結;不要替換版本或從方法類型構造 URL。 根據已設定的授權來源解析相對連結,並在傳送憑證前驗證目的地。
方法發現並非方法註冊
方法資源描述一種可用的驗證方法。 它的 type、隱藏的 hint、可選的 isPreferred 及連結,讓你的應用程式呈現選擇並完成挑戰。
codeLength 描述回傳時的密碼輸入。
challenge與verify連結皆對可用的方法運作。 註冊一個方法是一種獨立的策略驅動互動,並具有其自身的動作與請求合約。 Profile 屬性集合也有獨立的契約。
內嵌方法註冊使用 enroll 與 activate 操作。 電話註冊以 channels: ["sms"] 宣傳 type: phone;電子郵件註冊使用 type: email。 啟用會將根 otp 欄位中的程式碼提交至 activate 連結,而非憑證的 verify 連結。 註冊可以滿足 MFA 的要求,所以不一定會再遇到驗證挑戰。 請參閱 驗證方法註冊。
政策與屬性互動
使用者流程決定電子郵件註冊方式及所請求的屬性。 電子郵件與密碼註冊會收集密碼屬性。 電子郵件一次性密碼註冊會建立一個無密碼帳號,且不會收集密碼。
屬性描述符可以包含標籤、輸入類型、validation.validationRegEx 和初始值。 將每個確切的 attributeId 都當作提交鍵使用。 呈現表單時不需要頁面分組的元資料。 伺服器驗證仍具權威性。 請參閱 「原生驗證使用者屬性」。
支援透過系統原則進行多重要素驗證(MFA)。 註冊或重設密碼後,MFA 與條件存取可能會要求進行更多互動,才能完成授權。 你的應用程式會持續處理回應,而不是維持一個獨立的「已登入」流程來跳過這些要求。
錯誤與不支援的互動
OAuth 與原生驗證錯誤的封裝格式不同。 請使用穩定代碼進行處理,而非本地化訊息。 妥善保存診斷所需的請求識別碼與時間戳記;不要記錄憑證實體或權杖。
忽略未知的選用屬性與連結關係。 相較之下,未知的必要動作、缺少必填欄位或錯誤的回應,則使其無法安全地繼續進行。 當無法處理所需的互動時,停止原生操作。
帶有 invalid_grant 和 web_redirect_required 的 OAuth 錯誤,或帶有 state: redirect 的原生回應,表示原生交易程序無法繼續。 這兩種回應都無法建立可續接的瀏覽器交接。 提供獨立設定的瀏覽器登入,或明確的失敗結果。 將原生接續權杖保留在原生交易作業中。
聯邦、TOTP、通行金鑰、電話第一因素驗證、後續操作升級,以及設定檔或憑證管理的互通性,皆不支援此原生合約。 請參閱 支援矩陣。