嵌入式原生驗證 CORS 概念

跨來源資源共享(CORS)控制瀏覽器程式碼是否能讀取來自其他來源的回應。 具備內嵌原生驗證及自帶 UX(BYO UX)網站的單頁應用程式(SPA)需要針對原生驗證 API 的跨來源呼叫設置代理或邊緣 CORS 政策。

透過原生 HTTP 傳輸呼叫 API 的 Android 和 iOS 應用程式不需要 CORS 或 CORS 代理。 他們會直接致電已設定的服務機構。 本文中的需求適用於瀏覽器請求,而非那些原生 API 呼叫。

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

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

Important

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

瀏覽器 CORS 為何適用

瀏覽器應用程式及其租戶驗證端點通常具有不同的來源。 對於跨來源請求,瀏覽器會在將回應公開給應用程式程式碼之前,先檢查伺服器的 CORS 回應標頭。

來源 Origin 包括通訊協定、主機和埠。 共用父網域並不代表兩個來源就一樣。

API 的 JSON POST 請求與密碼更新 PUT 請求需要進行檢查前檢查。 瀏覽器會先以所請求的方法與標頭傳送 OPTIONS,然後再發送驗證請求。 像 client-request-id 這樣的標頭也會觸發預檢。 表單編碼的 OAuth 請求屬於同一整合的一部分;它們的方法與標頭決定是否需要預檢。

即使瀏覽器程式碼在嵌入式網頁檢視中執行,仍受 CORS 規範。 CORS 規範瀏覽器回應存取;來電驗證與濫用防範需要分開的控制。

為什麼需要代理伺服器

原生驗證服務會在解析 API 請求或呼叫其憑證動作之前先處理 OPTIONS 。 它會回傳一個空的 HTTP 200。 當請求包含 Origin 時,服務會告知該動作接受的方法,並在 Access-Control-Allow-Headers 中回傳所要求的標頭。 不需要額外的預檢功能旗標。

該服務不提供 Access-Control-Allow-Origin 或 Access-Control-Allow-Credentials。 您的代理伺服器或邊緣節點提供明確的允許來源原則。 它可以轉發服務的預檢回應,或在本地回應已驗證的預檢。 帶有外部 HTTP 200 的 HTML 錯誤頁面並非成功的預檢回應。

代理伺服器會保留 API 操作、主體與交易處理狀態。 轉發或省略上游 Origin 標頭是實作選擇,並非必須移除的普遍要求。 一致地套用你的選擇,同時檢查授權、原生操作和代幣交換。

服務授權端點與代理傳輸

本文涵蓋的瀏覽器整合中,嵌入式原生驗證與 BYO UX 服務 API URL 使用租戶驗證的自訂驗證網域及租戶 GUID:

https://<tenant-verified-custom-domain>/<tenant-GUID>

例如,服務授權單位可能是 https://login.contoso.com/aaaabbbb-0000-cccc-1111-dddd2222eeee。 本地傳輸前綴可能改為 http://localhost:3001/api。 這些數值有不同的作用:

Value Purpose
服務授權單位 識別租戶的驗證服務。 將此自訂網域與租戶 GUID 設定為上游授權單位,並以此驗證服務回傳的連結。
傳輸前綴 識別面向瀏覽器的代理伺服器。 它可以取代經過驗證的 API 請求中用於傳輸的 authority 部分,但不會變更服務 authority 或交易本身。

有了這個本地前綴,服務 /<tenant-GUID>/api/v2.0/signin/start 路徑就映射到 /api/api/v2.0/signin/start。 第一個 /api 是代理前綴;第二個屬於服務路徑。 OAuth 請求類似地映射到 /api/oauth2/v2.0/authorize-challenge 或 /api/oauth2/v2.0/token。

針對這些瀏覽器整合,請不要將 ciamlogin.com 位址設為應用程式的服務 API 授權單位。 平台管理的來源路由位於已驗證自訂網域後方,並不能取代此項需求。 使用原生 HTTP 傳輸的非瀏覽器用戶端不需要自訂網域。 請參閱設定 API 權限。

代理合約

請在反向代理中設定這些設定。 直接轉發 API 實體與服務狀態碼。

Setting Configuration
上游權限 設定 https://<tenant-verified-custom-domain>/<tenant-GUID> 為固定目的地。 若要使用自訂網域邊緣,請使用平台已文件化的服務來源設定。
路線 允許 /api/v2.0/*、 /oauth2/v2.0/authorize-challenge,以及 /oauth2/v2.0/token 在租戶-GUID 前綴下。
方法與預檢 啟用 POST、密碼更新 PUT、以及 OPTIONS。 本地處理預檢或轉發給服務單位即可。 僅核准已設定的方法與標頭;返回 Access-Control-Allow-Methods: POST, PUT。
瀏覽器來源 設定 Access-Control-Allow-Origin 為您的應用程式的精確來源,例如 https://app.contoso.com。 僅對符合需求的 Origin 請求回傳,包括錯誤回應。
允許的請求標頭 將 Access-Control-Allow-Headers 設定為 Content-Type, Accept, client-request-id。 對於 Microsoft 驗證資源庫(MSAL)用戶端,也允許 x-client-sku、x-client-ver、x-client-current-telemetry、x-client-os、x-client-cpu 及 x-client-last-telemetry。
公開的回應標頭 將 Access-Control-Expose-Headers 設定為 Retry-After, client-request-id, x-ms-request-id, x-ms-clitelem。
快取 停用代理伺服器與 CDN 快取功能。 在每個回應中加入 Cache-Control: no-store 。
重新導向與失敗 停用自動上游重定向並移除回應 Location 標頭。 針對連線失敗與逾時事件傳回顯式代理錯誤。

API 參考定義了操作專用的方法、標頭、請求主體與回應。

代理實作

請選擇符合您主機環境且符合相同合約的實作:

JavaScript SDK 的 customAuth.authApiProxyUrl 不會重新對應絕對 HAL 連結。 對於這些 SDK 請求,請在自訂網域邊緣使用 CORS 政策。 本地與函數配方則顯示自訂客戶端傳輸,用以驗證並映射服務連結。

本地代理綁定到迴圈介面,並非共享主機配方。 對於已部署的代理伺服器,也請檢視您環境中的容量、成本、存取控制、診斷保留與復原程序。