原生驗證密碼重設 API 參考

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

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

密碼重設會驗證客戶的恢復方式,接受替換密碼,並輪詢非同步更新。 電子郵件與簡訊一次性密碼(OTP)方法支援恢復。 多重驗證(MFA)及條件存取需求可在重設後且授權完成前適用。

對於現有的 V1 整合,請使用 V1 API 參考。

Prerequisites

Important

原生驗證 API V2 目前處於預覽階段。 原生驗證 API V1 仍然普遍提供。 請參閱 Microsoft Azure 預覽補充使用條款,了解適用於預覽功能的法律術語。

範例中使用 租戶驗證的自訂網域權威機構。 custom_domain 是驗證網域, tenant 為租戶 GUID。

無密碼的電子郵件 OTP 帳號沒有密碼可以重設。

開始重設密碼

圖示展示了使用電子郵件一次性密碼驗證的獨立復原程序。 內嵌恢復則改 recover 用密碼方法在主動登入交易中的連結。

密碼恢復、密碼驗證、密碼更新、可選輪詢及授權碼交換的序列圖。

開始授權並依照回傳的重設密碼連結(resetPasswordreset_password或)。 不要先呼叫登入發現:

POST https://{custom_domain}/{tenant}/api/v2.0/resetpassword/start
Content-Type: application/json
Accept: application/hal+json
{
  "username": "user@contoso.com",
  "continuationToken": "******"
}

將客戶識別碼與目前授權令牌continuationToken送入 username 。 範例中使用電子郵件地址。 回覆可以宣傳電子郵件復原方法:

{
  "state": "interactionRequired",
  "action": "challenge",
  "continuationToken": "******",
  "_links": {
    "self": {
      "href": "/{tenant}/api/v2.0/resetpassword/start"
    }
  },
  "_embedded": {
    "methods": [
      {
        "id": "{email_method_id}",
        "type": "email",
        "hint": "j****n@c****o",
        "_links": {
          "challenge": {
            "href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/challenge"
          },
          "verify": {
            "href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/verify"
          }
        }
      }
    ]
  }
}

透過使用者選擇或應用程式流程邏輯選擇回傳的電子郵件或簡訊復原方式。 範例顯示電子郵件;對於 SMS,請依照回傳的 SMS 方法的連結操作,且不重寫範例 URL。 在介面需要目的地標籤的地方,使用遮罩提示。

登入期間的線上恢復

僅在目前登入回應中的密碼方式宣告連結 recover 時,才提供內嵌復原服務。 使用目前的登入續簽權標記點選該連結。 不要再啟動授權請求,也不要重新提交使用者名稱或密碼。

POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/recover
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******"
}

兩個入口點都使用服務回傳的恢復方法、挑戰、驗證、密碼更新及輪詢操作。

挑戰並驗證復原方法

請貼至所選方法的 challenge 連結:

{
  "continuationToken": "******"
}

使用 JSON 和 Accept: application/hal+json。 共享挑戰操作會回傳目前的方法類型、遮蔽的 hint、 codeLength和 ,verify以及可選resend連結。

將輸入的密碼輸入到回傳 verify 的連結:

{
  "otp": "{one_time_passcode}",
  "continuationToken": "******"
}

為每個請求使用最新的令牌。 至於其他程式碼,請使用目前 resend 的連結與服務限制,而非先前的挑戰 URL/令牌對。

成功驗證後可回傳密碼方法:

{
  "state": "interactionRequired",
  "action": "update",
  "id": "{password_method_id}",
  "type": "password",
  "continuationToken": "******",
  "_links": {
    "update": {
      "href": "/{tenant}/api/v2.0/auth/methods/password/{password_method_id}"
    }
  }
}

請使用回傳 update 連結中的密碼方法識別碼,而非電子郵件或簡訊恢復方法識別碼。 內嵌復原可以保留父登入的密碼方法識別碼。

更新密碼

請以 非 PUTPOST的方式提交替換密碼:

PUT https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}
Content-Type: application/json
Accept: application/hal+json
{
  "newPassword": "{new_password}",
  "continuationToken": "******"
}
屬性 類型 Required Description
continuationToken String. Yes. 目前的令牌正在請求密碼更新。
newPassword String. Yes. 替換密碼。 密碼確認只在您的介面上,而非額外的請求欄位。

服務可返回:

{
  "state": "interactionRequired",
  "action": "poll",
  "pollInterval": "2",
  "id": "{password_method_id}",
  "type": "password",
  "continuationToken": "******",
  "_links": {
    "poll": {
      "href": "/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/pollUpdate"
    }
  }
}

這表示非同步更新,而非最終授權。 在等待期間不要再次提交密碼,或在網路故障不明時自動重複更新。

輪詢密碼更新

請點擊最新 poll 連結:

POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/pollUpdate
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******"
}

更新進行時,服務會回action: poll傳 interactionRequired 、 、 更新後的 token 和 poll link 。 在下一次投票前替換先前的回應。

包含時, pollInterval 是包含該區間(秒數)的字串。 使用目前回應的間隔進行下一個請求,並遵守伺服器重試指引。 這個例子 "2" 並不是固定的服務間隔。 當動作變更或傳回錯誤時停止輪詢,並處理政策所需的後續驗證。

續答如下:

{
  "state": "continue",
  "continuationToken": "******",
  "_links": {
    "continue": {
      "href": "/{tenant}/oauth2/v2.0/authorize-challenge"
    }
  }
}

完成政策要求並取得代幣

密碼重設並不會繞過多重驗證或條件存取。 如果有其他挑戰回傳,請使用共用的方法操作完成該挑戰。 代幣交換會在完成剩餘政策步驟並繼續授權後進行。

之後 state: continue,請使用最新令牌 恢復授權 並 交換代碼。 所請求的範圍與權利要求仍維持交易開始時所確定的範圍。

結果與錯誤

使用 共用錯誤處理。 回收合約描述了這些結果:

條件 結果與客戶處理
未知使用者名稱 復原不會開始。 使用通用的面向客戶訊息。
電子郵件或簡訊密碼錯誤 HTTP 400 invalidGrant 與 innerError.code: invalidOneTimeCode. 讓使用者使用可用的當前狀態或宣告的重送來修正程式碼。
缺少密碼 HTTP 400 invalidRequest. 修正缺少的輸入。
重新發送 會透過回傳 resend 的連結傳送一個新的密碼。
過期的密碼更新令牌 HTTP 400 expiredToken 與 innerError.code: expiredContinuationToken. 重新啟動授權。
弱或常見替換密碼 400 invalidRequest帶有適用的內部錯誤(例如 passwordTooWeak 或 passwordTooCommon)。 收集符合規定的密碼。
更新進行中 請遵循最新的輪詢回應與伺服器重試指引。
輪詢失敗密碼政策 帶有內部錯誤(如 passwordTooCommon 或 passwordBannedByPolicy)的 HTTP 400 invalidRequest 。 處理錯誤,而不是無限期地輪詢。
在輪詢期間帳戶被鎖定或停用 HTTP 403 forbidden 與 innerError.code: accountLocked. 停止復原作業。
密碼更新作業失敗 HTTP 500 serverError. 顯示明顯失敗,但不會自動重複密碼更新。
已完成復原 處理所有剩餘的政策操作、恢復授權並請求權杖。

本表描述的是具體結果,並非完整錯誤清單。 密碼更新接受、輪詢完成與令牌發放是獨立的界線。

不要記錄復原密碼、替換密碼或交易憑證。 只記錄安全的診斷識別碼、時間戳記及 HTTP 狀態。 不要自動重播驗證或密碼更新。