Fabric 應用程式的認證

Fabric Apps 內建認證服務,能登入使用者、管理會話,並將身份附加到應用程式的每一次資料與儲存呼叫中。 本文說明在為專案設定認證前,你需要了解的概念。

如需實作詳細數據,請參閱:

認證模式

部署的 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」。