適用於:
外部租戶(了解更多)
認證方式: 內建原生驗證。
登入會發現允許用於客戶識別碼的方法,並完成所需的憑證檢查。 帶密碼電子郵件與一次性密碼(OTP)第一因素登入採用相同的回應驅動模式。 應用程式會透過使用者選擇或應用程式流程邏輯,從回應中選擇允許的操作,然後在恢復授權前滿足剩餘的驗證要求。
對於現有的 V1 整合,請使用 V1 API 參考。
範例中使用 租戶驗證的自訂網域權威機構。
custom_domain 是驗證網域, tenant 為租戶 GUID。
開始登入發現
Important
原生驗證 API V2 目前處於預覽階段。 原生驗證 API V1 仍然普遍提供。 請參閱 Microsoft Azure 預覽補充使用條款,了解適用於預覽功能的法律術語。
圖示顯示了一種可能的登入順序。 政策需求可以新增、重複或重新排序動作;永遠遵循當前的回應。
開始授權,然後點擊回傳的 sign_in 連結。 將 OAuth 回應 continuation_token 的值傳送為 continuationToken:
POST https://{custom_domain}/{tenant}/api/v2.0/signin/start
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******",
"username": "user@contoso.com"
}
| 屬性 | 類型 | Required | Description |
|---|---|---|---|
continuationToken |
String. | Yes. | 來自目前授權挑戰的 Token。 |
username |
String. | Yes. | 租戶政策接受的登入識別碼。 此範例使用電子郵件。 |
密碼方法選擇回應可以是:
{
"continuationToken": "******",
"state": "interactionRequired",
"action": "challenge",
"_embedded": {
"methods": [
{
"id": "{password_method_id}",
"type": "password",
"_links": {
"challenge": {
"href": "/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/challenge"
},
"verify": {
"href": "/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/verify"
}
}
}
]
}
}
Email-OTP 登入會回傳一個電子郵件方式,其中包含自己的 id、遮罩且 hint允許的連結。 您的應用程式可以透過應用程式流程邏輯呈現回傳的選項,或選擇可用的方法。 並非每個帳號都同時提供密碼和電子郵件 OTP。 使用通用的發現失敗並保護帳戶存在資訊。
挑戰所選方法
請依照該方法的 challenge 連結 POST 與最新的續用標記:
{
"continuationToken": "******"
}
共享挑戰合約定義標頭、回應欄位及重送行為。
| 回傳方法 | 互動 |
|---|---|
password |
沒有傳送任何程式碼。 當回應要求 verify時收集密碼。 |
email |
領取已送達的密碼。 使用回傳的遮 hint 罩後 和 codeLength。 |
sms |
當廣告中要求某個因素時,請利用簡訊的提示、長度和連結來收集 SMS 密碼。 |
只在服務宣傳且客戶要求其他代碼時使用 resend 。 不要在配送延遲後自動重新寄送。
驗證憑證
請使用目前 verify 的連結 POST點擊。 使用 JSON 和 Accept: application/hal+json,並使用這些實體之一。
密碼:
{
"continuationToken": "******",
"password": "******"
}
電子郵件或簡訊一次性密碼:
{
"continuationToken": "******",
"otp": "{one_time_passcode}"
}
請使用傳回方法類型中的憑證欄位。 請勿在 中輸入密碼 otp 或密碼 password。 在網路出現模糊故障後,不要自動重播驗證。
完整的附加保單需求
成功驗證後,可返回另一個 interactionRequired 回應,且 action: challenge_embedded.methods。 選擇廣告中所宣稱的方法,並使用新的代幣和連結重複挑戰與驗證。
多重身份驗證(MFA)使用相同的共用憑證操作,並支援電子郵件與簡訊一次性密碼作為第二因素。 透過系統政策支援多重驗證(MFA)。 從為所需因子回傳的方法中選擇一種方法。 SMS 範例描述了第二因素的互動。
如果下一個回應要求或activate,enroll請使用線上註冊合約。 帶有密碼的電子郵件帳戶可以註冊所提供的電子郵件或簡訊因子。 Email-OTP 第一因素帳號不能重複使用電子郵件作為第二因素;使用提供給的替代方案,例如 SMS。
如果客戶端不支援某項必要的互動,或服務回傳 state: redirect,請停止原生請求,改以另行設定的瀏覽器登入或明顯失敗。
恢復授權並取得憑證
當政策需求被滿足時,回應可以回傳:
{
"continuationToken": "******",
"state": "continue",
"_links": {
"continue": {
"href": "/{tenant}/oauth2/v2.0/authorize-challenge"
}
}
}
將代幣以表單編碼 continuation_token 的形式貼到回傳的連結上。 然後 將授權碼兌換 成代幣。 無論是挑戰回應還是成功的驗證回應,都無法取代這種交換。
Errors
使用 共用錯誤信封 搭配以下登入條件:
| 條件 | 狀態或錯誤 | 操作 |
|---|---|---|
| 缺少使用者名稱或令牌 | 400 |
請更正這個請求。 |
| 電子郵件或簡訊密碼錯誤 |
400 invalidGrant,其中 innerError.code: invalidOneTimeCode |
讓使用者使用可用的當前狀態或宣告的重送來修正程式碼。 |
| 缺少密碼 | 400 invalidRequest |
修正缺少的輸入。 |
| 交易狀態無效 |
400 使用原生誤差包絡 |
重新開始,而不是重玩先前的標記。 |
| 節流限制 | 429 |
停止自動重試並遵守伺服器指引。 |
| 不支援的原生互動 |
state: redirect,或 OAuth invalid_grant 搭配 web_redirect_required |
停止原生請求。 獨立瀏覽器登入會重新啟動驗證。 |
對於其他憑證、發現或傳送失敗,請處理實際狀態與穩定錯誤代碼,避免暴露帳戶存在細節。 這張表並不是一份完整的錯誤清單。 只保留安全的請求 ID、關聯 ID、時間戳記及狀態資訊,不保留憑證或完整的回應內容。