原生驗證登入 API 參考

適用於: 綠色圓圈,帶有白色勾選標記符號,表示以下內容適用於外部租戶。 外部租戶(了解更多)

認證方式: 內建原生驗證。

登入會發現允許用於客戶識別碼的方法,並完成所需的憑證檢查。 帶密碼電子郵件與一次性密碼(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、時間戳記及狀態資訊,不保留憑證或完整的回應內容。