原生驗證註冊 API 參考

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

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

本參考說明透過伺服器驅動屬性收集進行註冊。 電子郵件密碼與一次性密碼註冊使用相同的操作與訊息格式。 對於這些電子郵件方式,與應用程式相關聯的使用者流程會選擇註冊方式;用戶端在啟動請求中並未選擇它。

範例顯示的是以電子郵件為基礎的註冊方式。 對於現有的 V1 整合,請使用 V1 API 參考。

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

開始註冊

Important

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

圖示顯示了以回應為導向的報名流程。 使用者流程決定註冊方式,而目前回應決定所需的屬性與互動。

原生註冊序列圖,包含回應定義屬性的收集、驗證及授權碼交換。

啟動授權,然後使用回傳的令牌點擊其 sign_up 連結:

POST https://{custom_domain}/{tenant}/api/v2.0/signup/start
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******"
}

continuationToken 是必填字串。 啟動回應可請求電子郵件:

{
  "continuationToken": "******",
  "state": "interactionRequired",
  "action": "collectAttributes",
  "attributes": [
    {
      "attributeId": "email",
      "inputType": "text",
      "hidden": false,
      "required": true,
      "canChange": true,
      "label": "Email"
    }
  ],
  "_links": {
    "submitAttributes": {
      "href": "/{tenant}/api/v2.0/signup/submitattributes"
    }
  }
}

標籤、要求性與驗證元資料來自政策。 請在應用程式的介面與收集邏輯中運用這些需求。

提交屬性

請關注 _links.submitAttributes.href。 收集可以發生不只一次:

POST https://{custom_domain}/{tenant}/api/v2.0/signup/submitattributes
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******",
  "attributes": {
    "email": "user@contoso.com"
  }
}
屬性 類型 Required Description
continuationToken String. Yes. 最新註冊代幣。
attributes 字串值的物件。 Yes. 以精確回傳 attributeId 值為鍵的值。

註冊完成前必須提供所有所需數值。 可省略的選填值。 缺少必要值可能導致驗證錯誤或其他 collectAttributes 回應。

若使用電子郵件密碼註冊,請在要求時提交密碼。 例如,請求密碼與個人檔案欄位的收集回合可以接受:

{
  "continuationToken": "******",
  "attributes": {
    "email": "user@contoso.com",
    "password": "******",
    "givenName": "Example",
    "surname": "User"
  }
}

依據使用者流程回傳的描述符提交欄位。 電子郵件一次性密碼註冊會建立一個無需密碼的帳戶,並以電子郵件密碼登入。

收藏順序

服務可以先請求電子郵件、同時收集多個屬性,或在驗證後返回屬性收集。 提交最新回應所要求的屬性,而非從提交的值預測順序。

您的應用程式可以依據其流程邏輯及可用的描述符來組織集合。 請參閱 「收款順序與電子郵件驗證」。 每個回應決定可用的下一步操作。

解讀屬性與頁面描述符

每個回應都描述目前的表單。 下列欄位定義屬性:

Field Meaning
attributeId 服從鑰匙。
inputType 輸入控制類型,例如 text、 、 passwordboolean、 date或 checkboxMultiSelect。
required 是否必須提供某個值。
hidden 欄位是否被隱藏。
canChange 可編輯性資訊(如包含)。
label 可選的展示標籤。
initialValue 可選的預先填入值。
validation.validationRegEx 可選的驗證模式。
options 可選選項,包含屬性labelvalue與屬性。
confirmationInput 可選的確認行為,例如 retype、 reveal、 none或 。

不需要會員 pages 。 目前 attributes 陣列定義欄位與需求;若回傳頁面分組元資料,則為額外的呈現資訊。 輸入控制類型不會改變以字串值計算的提交物件。 請參閱 「使用者屬性概念」。

驗證電子郵件

當屬性提交需要電子郵件驗證時,系統會傳送密碼並回傳:

{
  "continuationToken": "******",
  "state": "interactionRequired",
  "action": "verify",
  "id": "{email_method_id}",
  "type": "email",
  "hint": "u***@contoso.com",
  "codeLength": 8,
  "_links": {
    "verify": {
      "href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/verify"
    },
    "resend": {
      "href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/challenge"
    }
  }
}

服務已經發送了密碼;直接進行驗證。 使用回傳的長度與遮罩提示。 寄至 verify:

POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/verify
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******",
  "otp": "{one_time_passcode}"
}

若要申請其他代碼,請僅發布目前resend連結的最新continuationToken代碼,並受服務限制限制。

驗證可返回更多屬性收集:

{
  "continuationToken": "******",
  "state": "interactionRequired",
  "action": "collectAttributes",
  "attributes": [
    {
      "attributeId": "givenName",
      "inputType": "text",
      "hidden": false,
      "required": true,
      "canChange": true,
      "label": "First name"
    }
  ],
  "_links": {
    "submitAttributes": {
      "href": "/{tenant}/api/v2.0/signup/submitattributes"
    }
  }
}

提交所要求的值,並繼續處理下一個回應。

完整的政策要求與授權

在建立帳戶並完成任何必要的驗證後,請完成任何多重驗證(MFA)及條件存取要求,才能恢復授權。

如果回應中宣告另一個方法挑戰,請使用 共用挑戰與驗證操作。 註冊方式與驗證註冊電子郵件不同。 請參閱 「方法發現與註冊 」以了解註冊合約。

服務恢復 state: continue後,請跟進 _links.continue, 恢復授權並交換驗證碼。 此工具可在不啟動無關登入交易的情況下取得代幣。

錯誤與生命週期

使用共用的錯誤信封。 結構化驗證項目可以包含 code、 message、 attributeIds、 suggestions及 可選 recovery性 。

條件 現狀或行為 操作
無效的延續標記 400 重新開始流程。
缺少或無效屬性 400 或是其他 collectAttributes 回應 提供現場回饋並提交修正後的數值。
使用者已存在 400 invalidRequest 提供一般性的登入或恢復指引,但不必要地透露帳號存在。
密碼政策違規 400 收集符合規定的密碼。
電子郵件密碼錯誤 400 invalidGrant 和 innerError.code: invalidOneTimeCode 讓使用者使用可用的當前狀態或宣告的重送來修正程式碼。
缺少密碼 400 invalidRequest 修正缺少的輸入。
節流限制 429 Honor 伺服器重試指引。
不支援的原生互動 state: redirect 停止原生請求並提供已設定的瀏覽器路徑或明顯失敗。

透過實際狀態與穩定錯誤代碼處理其他故障。 不要把過期的交易視為可恢復的錯誤代碼輸入。

使用者建立後,屬性提交不再是冪等的。 不要重播成功提交、不要記錄敏感屬性值,或將用戶端驗證視為權威性。