適用於:
外部租戶(了解更多)
認證方式: 內建原生驗證。
本參考說明透過伺服器驅動屬性收集進行註冊。 電子郵件密碼與一次性密碼註冊使用相同的操作與訊息格式。 對於這些電子郵件方式,與應用程式相關聯的使用者流程會選擇註冊方式;用戶端在啟動請求中並未選擇它。
範例顯示的是以電子郵件為基礎的註冊方式。 對於現有的 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 |
停止原生請求並提供已設定的瀏覽器路徑或明顯失敗。 |
透過實際狀態與穩定錯誤代碼處理其他故障。 不要把過期的交易視為可恢復的錯誤代碼輸入。
使用者建立後,屬性提交不再是冪等的。 不要重播成功提交、不要記錄敏感屬性值,或將用戶端驗證視為權威性。