Fabric Apps 內建認證服務,能登入使用者、管理會話,並將身份附加到應用程式的每一次資料與儲存呼叫中。 本文說明在為專案設定認證前,你需要了解的概念。
如需實作詳細數據,請參閱:
- 為您的Fabric應用程式設定Fabric SSO 認證 – 已部署應用程式的登入與註冊碼。
- 定義資料權限 ——使用已登入使用者的身份來控制資料存取。
認證模式
部署的 Fabric 應用程式會使用 Microsoft Entra ID 進行驗證。 根據應用程式運行的位置以及誰取得 Entra 代幣,選擇整合路徑:
| 環境 | 受支援的方法 | 何時使用它 |
|---|---|---|
| 透過 Fabric 入口網站使用的瀏覽器應用程式 | Fabric SSO 彈出視窗或嵌入式交接 | 讓 Fabric 執行互動式登入,或是在內嵌於 Fabric 的應用程式中登入。 |
| 具有委派 Entra 權杖的瀏覽器或 Node.js 應用程式 | signInWithEntraToken() |
將提供的令牌交換為 Rayfin 工作階段,且不會跳出視窗或重新導向。 |
| 嵌入外部父層入口網站的應用程式 |
createEmbedHost() 在父節點和 initEmbeddedAuth() iframe 中 |
讓受信任且經 Entra 驗證的父代理程式在不將 token 傳送至 iframe 的情況下中介交接。 |
| 本地開發與本地後端 | 電子郵件與密碼 | 測試時要針對本地後端;這個方法在已部署的 Fabric 後端上不適用。 |
關鍵概念:
- Fabric SSO 利用 Fabric 入口網站來驗證瀏覽器使用者。 該應用程式可在 Fabric 內執行,或使用來自獨立頁面的彈出視窗,包括連接至已部署後端的本地前端。
- 直接 Entra 交換與外部父主機交接是額外的 Microsoft Entra 路徑,並非支援任意身分識別提供者或僅限應用程式服務主體登入。
- 電子郵件與密碼 僅供本地開發使用。 部署後它就無法運作了。
- 首次登入功能會讓使用者獲得支援。 使用 Fabric SSO,則沒有獨立的註冊步驟——使用者在首次登入時會自動建立。
- Fabric 部署需要進行驗證。 將
services.auth.enabled設定為false會導致npx rayfin up失敗。
關於令牌需求與實作範例,請參見 直接 Entra 令牌登入 與 嵌入外部父入口網站。
會議與身份認同
使用者登入後,SDK 會建立一個代表已登入使用者的 會話 。 會話是不透明的——你的應用程式不應該檢查底層的代幣。 相反地,你的應用程式會讀取一組少量的高階屬性:
- 會話是否目前已驗證。
- 使用者的
id和email。 - 你在
rayfin.yml中設定的自訂宣告。
用來讓使用者登入的同一個用戶端執行個體,會自動在每次資料和儲存體呼叫中附加其身分資訊。 你不會手動傳遞代幣。
會話也會觸發變更事件,因此使用者登入或登出時,使用者介面可以做出反應,而不必重新載入頁面。
對於伺服器端整合,請為每位使用者使用獨立的用戶端,以及僅儲存在記憶體中的 Auth 工作階段(authStorage: false 於 RayfinClient 上,或 { storage: false } 於 Auth 上)。 切勿在不同使用者間共享可變的登入客戶端。 當驗證實例的請求或使用者特定範圍結束時,就銷毀該驗證實例。
在您的專案中啟用認證
驗證是在 rayfin/rayfin.yml 中設定的。 以下範例同時啟用 Fabric SSO(針對已部署應用程式)及電子郵件/密碼登入(用於本地開發):
services:
auth:
enabled: true
allowedRedirectUris:
- http://localhost:5173
fabric:
enabled: true
externalEntraExchange: true
password:
enabled: true # Local development only
各設定控制什麼:
-
services.auth.enabled– 開啟認證服務。 任何 Fabric 部署都需要此項。 -
allowedRedirectUris– 登入後允許接收使用者的來源。 請在此加入你在地的開發 URL。npx rayfin up會自動新增已部署應用程式的來源。 -
fabric.enabled– 啟用Fabric SSO。 已部署的應用程式所需。 -
fabric.externalEntraExchange– 啟用直接委派的 Entra 令牌交換及外部父主機交接。 目標 Fabric 環境也必須支援 Exchange。 -
password.enabled– 啟用電子郵件與密碼登入以進行本地開發。
Important
Fabric 部署需要啟用認證。
npx rayfin up 當 services.auth.enabled 設定為 false時 會失敗。
編輯 rayfin.yml後,重新啟動本地後端或執行 npx rayfin up 以套用變更。
外部取得 Entra 代幣的前提條件
直接交換與外部父代管主機驗證需要目標部署所接受、且具有 Item.Execute.All 的 Fabric/Power BI 受眾委派使用者令牌,並且該令牌是在項目所屬租戶中發出。 使用者也必須對應用程式項目擁有 執行 權限。 這些登入路徑不支援僅 App 的代幣。
你的身分識別程式庫會取得該權杖並處理使用者同意。 Rayfin SDK 會用它來交換 Rayfin 會話;它不會取得 Entra 代幣。 瀏覽器呼叫者還需要服務的 CORS 政策允許來源與授權標頭。
海關索賠
自訂聲明允許你為每個會話附加應用程式專屬的元資料——例如租戶名稱、功能標誌或應用程式版本。 它們對於基於角色的存取控制和功能閘門非常有用,且不需要改變你的資料模型。
services:
auth:
enabled: true
customClaims:
tenant: default
app_version: 1.0.0
自訂聲明會出現在會話物件中,並可從你的資料權限規則中引用。
SDK 所提供的是什麼
當你使用 RayfinClient 時,認證服務可於 client.auth 使用。 在概念層面,它提供:
- 在本地開發期間,請以電子郵件和密碼註冊並登入。
- 透過 Fabric SSO 登入與註冊,適用於已部署的應用程式。 同一通電話同時處理新手和回頭用戶。
- 直接委派的 Entra 令牌交換,透過瀏覽器或 Node.js 程式碼進行,並對嵌入式應用程式提供受信任的外部父主機交接。
- 登出 以結束當前會話。
- 會話讀取和訂閱 ,讓你的 UI 能與使用者的認證狀態保持同步。
關於將這些功能接入真實應用程式的程式碼,請參見「配置 Fabric 的 Fabric 應用程式 SSO 認證」。 如需回撥和交接允許清單的相關指引,請參閱「設定驗證重新導向 URI」。