原生驗證 API V2 參考

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

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

原生驗證 API 在 Microsoft Entra 外部 ID 外部租戶中使用回應驅動流程。 啟動授權,完成回傳的驗證互動,恢復授權,並以授權碼交換令牌。 此參考定義共享操作;旅程專屬參考定義了登入發現、註冊屬性及密碼重設。

對於現有的 V1 整合,請使用 V1 API 參考。 請參閱 「從 V1 遷移到 V2 」以了解套件版本、遷移需求及 SDK 整合細節。

Prerequisites

Important

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

  • 一個外部租戶以及一個為公開用戶端與原生驗證流程所設定的應用程式。 請參閱 「設定應用程式」。
  • 與應用程式相關聯的使用者流程。
  • 對於基於瀏覽器的應用程式,例如 SPA,則需設定一個經租戶驗證、用於服務 API 呼叫的自訂 URL 網域。
  • 當您請求存取 API 時,目標資源所需的委派權限與同意。
  • 對於具備嵌入式原生驗證及 BYO UX 網站的 SPA,則需採用一套實作 瀏覽器代理需求所需的代理或邊緣政策。

運作與權限

範例使用 https://{custom_domain}/{tenant},其中 custom_domain 是租戶驗證的驗證網域,例如 login.contoso.com,且 tenant 為其目錄(租戶)識別碼,GUID。 client_id 是應用程式(用戶端)ID。 在這些範例中,所有服務 API 呼叫 URL 都使用此自訂網域,包括授權挑戰與權杖交換。

原生驗證 API V2 要求瀏覽器應用程式(如 SPA)使用租戶驗證的自訂網域,以協助防範跨站請求偽造(CSRF)。 非瀏覽器用戶端,例如 iOS 和 Android 應用程式使用原生 HTTP 傳輸,則不需要自訂網域。 嵌入式瀏覽器或 webview 並非原生的 HTTP 傳輸。 BYO UX 仍以瀏覽器為基礎,且需要經租戶驗證的自訂網域。 請參閱設定 API 權限。

除了初始授權請求與令牌交換外,請使用目前回應所宣告的網址。 方法識別碼是不透明的。 根據已設定的權威來源解析相對連結,驗證目的地,並保留回傳路徑與查詢不變。

以下授權開始、恢復及程式碼交換說明了嵌入式原生驗證。 BYO UX 頁面則會使用瀏覽器交接,並回傳關於共享原生互動操作的 FINISH 連結。 不要在那個 BYO UX 交易中開始或繼續 /authorize-challenge 。

運算 方法 路徑或連結
開始授權 POST /{tenant}/oauth2/v2.0/authorize-challenge
恢復授權 POST 已回傳 continue 連結。
開始登入 POST 回傳 sign_in 連結;範例使用 /{tenant}/api/v2.0/signin/start。
開始註冊 POST 回傳 sign_up 連結;範例使用 /{tenant}/api/v2.0/signup/start。
提交註冊屬性 POST 已回傳 submitAttributes 連結。
開始重設密碼 POST 回傳重設密碼連結;範例使用 /{tenant}/api/v2.0/resetpassword/start。
開始內嵌密碼重設 POST 密碼方法回傳 recover 的連結。
註冊驗證方法 POST 已選取方法回傳 enroll 的連結。
啟用驗證方法 POST 已回傳 activate 連結。
提出異議或重新發送 POST 已退回 challenge 或 resend 連結。
驗證憑證 POST 已回傳 verify 連結。
更新密碼 PUT 已回傳 update 連結。
輪詢密碼更新 POST 已回傳 poll 連結。
Exchange 授權碼 POST /{tenant}/oauth2/v2.0/token

原生範例使用 /api/v2.0;OAuth 操作 使用 /oauth2/v2.0。 在這些權限範例中使用租戶 GUID。 追蹤回傳的連結,無需重寫其路徑、版本或查詢參數。

Headers

OAuth 與原生驗證操作使用不同的實體編碼。

Header 使用
Content-Type: application/x-www-form-urlencoded 授權挑戰與令牌請求所必需。
Content-Type: application/json 原生驗證請求實體所必需。
Accept: application/hal+json 建議用於原生驗證請求。
client-request-id: {guid} 推薦。 為每個流程產生一個新值,並保留以供診斷使用。

瀏覽器代理伺服器需求

這些要求適用於來自具內嵌原生驗證及 BYO UX 網站的 SPA 的瀏覽器 API 呼叫。 使用 Android 和 iOS 原生 HTTP 傳輸的應用程式不需要 CORS 設定或 CORS 代理。

原生驗證路由處理 OPTIONS,但不會讓瀏覽器透過 進行原始存取。Access-Control-Allow-Origin 因此,跨來源瀏覽器整合需要一個代理或邊緣配置,以:

  • 轉發服務成功的預檢回應,並套用已設定的瀏覽器來源政策。
  • 返回的是 Access-Control-Allow-Origin 該完全允許的原點,而非 *。
  • 允許操作 POST 所需的方法 PUT ,以及整合所使用的請求標頭。
  • 保留請求主體、回應狀態碼、內容類型及交易連結,且不快取驗證回應。
  • 在授權、原生操作及令牌交換中,持續處理來源與路由。
  • 保留重試指引,包括 Retry-After,並在需要時將其暴露給瀏覽器程式碼。

請參閱 「原生驗證」CORS 概念 ,以了解瀏覽器邊界與 本地代理設定 。

延續權杖

延續權杖代表目前階段的認證交易。 它受租戶、客戶、情境及行動所約束。

郵件格式 Field
OAuth continuation_token
原生驗證 API continuationToken

僅使用目前由相同回應所識別的操作的令牌。 不要解析、修改、記錄或持續保存它,直到交易結束後才處理。 當回應提供替換時,停止使用先前的標記。 不要將代幣移到其他使用者或旅程上。 授權到期後重新啟動授權。

個別續接令牌的預設有效期為 10 分鐘。 依服務回應處理到期;更新的代幣並不保證整個旅程都能延長。 令牌與一次性密碼有不同的有效期限。 授權代碼壽命短暫且僅能一次性使用;不要把令牌回應 expires_in 解讀為授權碼的存續期。

反應模型

成功的原生互動操作會回傳 HAL JSON。 即使連續呼叫同一端點,下一個動作也可能有所不同。 欄位是針對回應的專用欄位:例如,一個重新導向只能 state包含 。

會員 Purpose
continuationToken 包含時,用於下一個允許請求的令牌。
state 目前的交易狀態。
action 回應所需的互動 interactionRequired 。
_links 允許操作的 URL。
_embedded 相關資源,包括可用的方法。

流程概念解釋了這些狀態與動作。 對於 interactionRequired,會使用允許的操作處理回傳動作。 對於 continue,請透過回傳的連結恢復授權。 單一操作的 completed 狀態並不會確認代幣是否已發出。

無法繼續的原生交易可以回傳:

{
  "state": "redirect"
}

此回應不會提供延續權杖、連結或瀏覽器交接 URL。 停止原生請求,並提供另行設定的瀏覽器登入或明顯失敗。 瀏覽器登入會重新啟動驗證;它不會恢復原生的進展。

帳戶選擇行動

Note

帳號選擇在嵌入式原生驗證中無關,且尚未支援 BYO UX 自架頁面。

disambiguate 在 下識別帳戶選擇 state: interactionRequired。

使用最新回應中的連結,並在轉發密鑰前驗證其權限。

Relation Purpose
self 目前的資源或操作。
discover 提交登入識別碼。
challenge 開始所選方法的挑戰。
verify 驗證密碼或一次性密碼。
resend 申請另一個一次性密碼。
submitAttributes 提交所要求的報名數值。
recover 在目前的登入交易中啟動密碼恢復。
enroll 開始註冊廣告中的驗證方式。
activate 驗證已註冊方法的程式碼。
update 提交替換密碼。
poll 檢查非同步更新。
continue 恢復 OAuth 授權。

此操作適用於 Bring Your Own UX(BYO UX)帳戶選擇。 內建的原生驗證整合不使用此功能,且目前在自架 BYO UX 頁面上的帳號選擇也不支援。

如果你的 BYO UX 整合依照建議的變通方式(發送 login_hint 或 prompt=login 在授權請求中)進行,那麼啟用帳號選擇不會中斷或破壞你現有的 UX。

動作有效載荷是現有 BYO UX 瀏覽器交接 initialResponse 的一部分,包含:

  • state: interactionRequired, action: disambiguate以及 a continuationToken 代表待選。
  • 一個 _embedded.user 包含每個提供帳戶及支援連結資訊的陣列。 活躍帳戶擁有帳戶專屬 _links.resume 的 URL。
  • 非活躍帳戶的回應層級 _links.discover URL,或 使用其他帳戶。

驗證方法資源

現有憑證方法選擇使用 _embedded.methods。 服務也可以選擇單一方法。 現有的憑證會有不 id透明的 、 , type 例如 password、 email、 sms,以及允許操作的連結。 遮罩 hint 識別目標但未完全揭露; isPreferred 為可選偏好設定中繼資料。 報名選項有獨立的表示方式,且不需要現有的憑證ID。

{
  "_embedded": {
    "methods": [
      {
        "id": "{id}",
        "type": "email",
        "hint": "u***@contoso.com",
        "isPreferred": true,
        "_links": {
          "challenge": {
            "href": "/{tenant}/api/v2.0/auth/methods/email/{id}/challenge"
          },
          "verify": {
            "href": "/{tenant}/api/v2.0/auth/methods/email/{id}/verify"
          }
        }
      }
    ]
  }
}

此片段說明方法的元資料。 方法的可用性會根據每筆交易決定。 您的應用程式可以呈現可用的方法,或透過應用程式流程邏輯選擇其中一個方法。 挑戰與驗證則針對所選方法進行;方法註冊有獨立合約。

不需要像 或 scenario這樣的可選簡報元資料pages。 範例描述的是基本的密碼與電子郵件/簡訊互動,而非所有特定方法的額外要求。

開始授權

在初始請求時將應用程式、範圍及選填聲明送出。 表單編碼值;下方的換行是為了方便閱讀。

POST https://{custom_domain}/{tenant}/oauth2/v2.0/authorize-challenge
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&
scope=openid%20profile%20offline_access&
response_type=code
Parameter 使用
client_id 所需應用程式(用戶端)ID。
scope 為您的應用程式請求範圍設定範圍。 包含 OpenID Connect (OIDC) 及產生的權杖所需的資源範圍。
response_type code 在這個例子中。 驗證後,端點會回傳授權碼。
claims 可選的 JSON 編碼 OpenID Connect 聲明請求。

當需要驗證時,回應為 401 Unauthorized,其中 Content-Type: application/json:

{
  "error": "InsufficientAuthorization",
  "error_description": "AADSTS500127: No authenticated credentials found in request.",
  "error_codes": [
    500127
  ],
  "timestamp": "2026-08-28T17:30:00Z",
  "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
  "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
  "continuation_token": "******",
  "reset_password": "/{tenant}/api/v2.0/resetpassword/start",
  "sign_in": "/{tenant}/api/v2.0/signin/start",
  "sign_up": "/{tenant}/api/v2.0/signup/start"
}

登入與註冊 URL 皆為條件式。 旅程連結是頂層 OAuth 回應屬性,而非 _links 條目。 選擇一個已宣告的旅程,並依 continuationToken 照 JSON 請求的方式傳送其令牌。 處理任何政策或帳戶特定的拒絕。

恢復授權

當目前回應回傳 state: continue時,將最新的 token 上傳到 _links.continue.href。 請不要重寄首字母 client_id、 scope或 claims 在此請求中。

POST https://{custom_domain}/{tenant}/oauth2/v2.0/authorize-challenge
Content-Type: application/x-www-form-urlencoded
continuation_token={continuation_token}

成功回應為 200 OK JSON 格式:

{
  "code": "{authorization_code}"
}

授權碼是短暫且一次性使用的。 Exchange 程式碼,而不是把它當作存取權杖來處理。

Exchange 授權碼

請使用相同應用程式 ID 張貼代碼:

POST https://{custom_domain}/{tenant}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&
grant_type=authorization_code&
code={authorization_code}

這三個參數都是必填的。 grant_type 是 authorization_code。 此公開用戶端請求不包含用戶端密鑰。

成功回應為 200 OK JSON 格式:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "******",
  "id_token": "******",
  "refresh_token": "******"
}

代幣欄位取決於最初建立的範圍與聲明。 只有當初始請求包含 offline_access時,才會回傳刷新權杖。 範例的到期金額並非固定的終身保證。 如果你的應用程式不需要刷新權杖,就不要提出要求 offline_access 。

提出異議或重新發送

請點擊所選方法的連結,或在客戶要求其他密碼時, challenge 點擊目前的 resend 連結:

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

電子郵件挑戰可以回傳:

{
  "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"
    }
  }
}

SMS 使用相同的憑證挑戰形狀,包含 type: sms、遮蔽的電話提示及其回傳的方法連結。 密碼挑戰不會傳送密碼,並會回傳密碼 verify 操作。 使用回傳 codeLength的長度,而非範例長度。 遵守服務控制的嘗試與重寄限制。

驗證憑證

請發文到目前的 verify 連結。 針對密碼方法:

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

針對電子郵件或簡訊方式:

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

驗證可以回傳另一個挑戰、屬性收集、密碼更新或繼續。 處理回傳動作。 驗證並非冪等;在網路故障不明時,不要自動重試。

驗證方法註冊

註冊或登入可能需要透過 action: enroll進行線上註冊,接著 action: activate。 註冊與收集個人資料屬性或驗證現有憑證是分開的。

Important

註冊與使用註冊方式驗證是分開的。 僅使用目前交易中所公告的註冊方式;不要從憑證挑戰推斷出註冊操作。

選取並註冊方法

從中 _embedded.methods 選擇一個支援的方法,並依照其 _links.enroll 網址操作。

方法 廣告 必填 JSON 欄位
電話簡訊 type: phone,其中 smschannels。 continuationToken, phoneNumber 包括國家代碼,以及 channel: sms。
電子郵件 type: email。 continuationToken 以及 email。 不要發送 channel.。

電話註冊使用 type: phone的方法,而非 sms 現有 SMS 挑戰方式所使用的類型。 電話註冊的範例 URL 為 /{tenant}/api/v2.0/auth/methods/phone;電子郵件 URL 為 /{tenant}/api/v2.0/auth/methods/email。 搭配 JSON 使用 POST ,並依照廣告的 URL 操作,而非自行建立。

對於電話簡訊註冊,正文如下:

{
  "continuationToken": "******",
  "phoneNumber": "+1 2025550123",
  "channel": "sms"
}

電子郵件註冊時,正文如下:

{
  "continuationToken": "******",
  "email": "user@contoso.com"
}

服務會傳送一個密碼,並回傳 action: activate一個新的續續權杖和一個 activate 連結。 顯示回傳的遮罩後 hint 及 codeLength 出現時。 電子郵件和簡訊可以使用不同長度的代碼。

手機啟用回應可以是:

{
  "continuationToken": "******",
  "state": "interactionRequired",
  "action": "activate",
  "id": "{phone_method_id}",
  "type": "phone",
  "channel": "sms",
  "hint": "***0123",
  "codeLength": 6,
  "_links": {
    "activate": {
      "href": "/{tenant}/api/v2.0/auth/methods/phone/{phone_method_id}/activate"
    },
    "resend": {
      "href": "/{tenant}/api/v2.0/auth/methods/phone"
    }
  }
}

使用實際回應中的欄位與連結;電子郵件使用其獨特的方法類型、程式碼長度及連結。

啟用或重新傳送

將包含最新continuationToken且使用者程式碼的 otpJSON POST 傳送到目前activate連結。 以電話為例 /{tenant}/api/v2.0/auth/methods/phone/{phone_method_id}/activate;電子郵件則使用其廣告連結。 不要將啟用碼提交到憑證的 verify 連結。

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

如果啟用回應有resend廣告,請將只包含最新continuationToken資訊的 JSON POST 傳送到該連結。 連結可以指向報名紀錄。 請勿保留或重新寄送聯絡資料;該令牌承載註冊情境。

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

在每次回應後更換有效的標記、連結、提示和程式碼長度。 啟動後繼續處理退回行動;僅 state: continue 允許恢復授權。 註冊本身就能滿足 MFA,所以不一定需要另外的資格認證挑戰。

對於 invalidGrantinnerError.code: invalidOneTimeCode,保留目前的啟動令牌與已公告的連結。 讓使用者修正程式碼或請求重寄。 在連線不明確失敗後,不要自動重播註冊或啟用。

Errors

OAuth 錯誤會使用像 error、 、 error_descriptiontrace_id、 correlation_id和 這樣的欄位。 原生驗證失敗會使用巢狀信封。 例如,錯誤的電子郵件驗證碼可能會回傳以下 HTTP 400 :

{
  "error": {
    "code": "invalidGrant",
    "message": "AADSTS50181: Unable to validate the otp.",
    "timestamp": "2026-08-28T17:30:00Z",
    "traceId": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
    "innerError": {
      "code": "invalidOneTimeCode"
    }
  }
}

使用穩定的程式碼來處理訊息,而非本地化訊息。 屬性驗證可回傳包含 、 、 及 的條目code,加上可選suggestions或 recovery。attributeIdsmessagedetailserror.innerError.code: attributeValidationError 解析前請檢查 HTTP 狀態與內容類型;不要在應用程式中呈現意外的 HTML 錯誤主體。

條件 狀態或錯誤 操作
無效的 OAuth 參數 400 invalid_request 請修正這個請求;不要不改動就重試。
無效或過期的程式碼 400 invalid_grant 重新啟動授權。
無效的應用程式 400 invalid_client 應用程式設定正確。
無效或未授權的範圍 400 invalid_scope 檢查所要求的範圍並取得同意。
需要驗證 401 InsufficientAuthorization 點擊已啟用的旅程連結。
無效的延續標記/狀態 400 invalidRequest 重新啟動相關流程。
過期的密碼更新令牌 400 expiredToken 和 innerError.code: expiredContinuationToken 重新啟動授權。
缺少驗證碼 400 invalidRequest 修正缺少的輸入。
電子郵件或簡訊驗證碼錯誤 400 invalidGrant 和 innerError.code: invalidOneTimeCode 讓使用者使用可用的當前驗證狀態修正程式碼,或點擊廣告中的重寄連結。 不要自動重新提交。
啟用碼錯誤 400 invalidGrant 和 innerError.code: invalidOneTimeCode 保留目前的啟動令牌和已宣傳的連結。 讓使用者修正程式碼或使用公告的重送動作。 不要自動重新提交。
需要瀏覽器互動 invalid_grant 和 web_redirect_required 停止原生請求並使用已設定的互動式復原路徑。 不要將續接權杖轉發到任意 URL。
原生交易無法繼續 本土身體 {"state":"redirect"} 停止原生請求。 獨立的瀏覽器登入無法保留原生進度。
節流限制 429 榮譽 Retry-After 與服務者的指導。

網路與服務故障可使用其他回應格式。 將意外的內容類型視為明確失敗。 表格描述的是具體的常見案例,而非所有操作的完整錯誤清單。

安全性與診斷

對每個上游請求都使用 HTTPS。 將密碼、密碼、延續令牌、代碼及已發出的令牌排除在 URL、日誌、遙測、例外、截圖及支援附件之外。 不要快取驗證回應,也不要在使用者之間分享交易狀態。

拒絕突如其來的權限,並轉寄而非轉寄機密。 在錯誤失敗後,不要自動重試認證驗證、帳戶建立提交或密碼更新。

僅顯示服務提供的遮蔽提示。 使用通用的發現失敗,這樣訊息和方法呈現就不會不必要地揭露帳戶存在。

保留安全的診斷資料:HTTP 狀態、作業類別、 client-request-id服務追蹤/關聯 ID 及時間戳記。 OAuth 名稱會使用底線;原生驗證錯誤名稱使用駱駝大小寫。 擷取這些診斷欄位時,不保留完整的請求或回應實體。

自訂驗證延伸模組

活動配置與合約是針對每個延伸與旅程所專屬的。 當擴充功能參與流程時,您的應用程式仍會從服務回應中選擇允許的操作。

原生事件覆蓋範圍包括 OnOtpSend 電子郵件及 OnTokenIssuanceStart。 OnAttributeCollectionStart 且 OnAttributeCollectionSubmit 不支援內嵌原生驗證或自帶用戶體驗。 請參閱 「自訂驗證擴充套件」 以了解事件特定行為。 此事件集不會建立密碼遷移掛鉤、密碼更新同步或任意上下文傳播。