透過 Fabric 入口網站、直接委派的權杖交換或受信任的外部母入口網站,為 Fabric 應用程式設定 Microsoft Entra 登入。 這些認證路徑使用 Microsoft Entra,且不支援任意的身份提供者。
先決條件
- 一個啟用認證的 Fabric Apps 專案。 請參見「設定認證」。
- 一個已部署的 Fabric Apps 項目。 請參見 部署至 Fabric。
Fabric SSO 的運作原理
Fabric 單一登入(SSO)會在您的應用程式與 Fabric 入口網站之間,透過安全的postMessage式交接機制運作。 沒有重定向或回撥頁面:
- 你的應用程式會在彈出式視窗中開啟 Fabric 入口網站,並註冊
postMessage監聽器。 - 使用者透過 Fabric 入口網站內的 Microsoft Entra ID 進行認證。
- Fabric擴充功能會透過
window.opener.postMessage()把交接碼回傳給你的應用程式。 - SDK 會將 handoff 代碼交換成 Rayfin 會話令牌並建立會話。
- Fabric 彈出視窗會自動關閉。
此流程透過 PKCE(程式碼交換證明金鑰)、state nonce,以及 postMessage 來源驗證加以保護,以防止授權碼遭攔截及跨站請求偽造。
啟用 Fabric 認證
將Fabric認證設定加入你的 rayfin/rayfin.yml 檔案:
services:
auth:
enabled: true
allowedRedirectUris:
- http://localhost:5173
fabric:
enabled: true
對於已部署的應用程式,請重新部署以推送更新的設定:
npx rayfin up
對於已部署的應用程式, npx rayfin up 會將你已部署的應用程式來源加到 allowedRedirectUris。 關於設定與安全指引,請參閱「配置認證重定向 URI」。
安裝 Fabric 認證提供者(可選)
使用 npm create @microsoft/rayfin@latest 建立的專案已經包含 @microsoft/rayfin-auth-provider-fabric。 只有在你要為尚未安裝該套件的專案加裝 Fabric 認證時,才手動安裝:
npm install @microsoft/rayfin-auth-provider-fabric
在你的應用程式中新增登入和註冊
Fabric SSO 使用單一 API 進行登入與註冊:ensureSignedInWithFabric()。 當使用者首次登入時,Fabric 會根據他們的 Microsoft Entra ID 身份自動為他們設定 Rayfin 會話——沒有額外的註冊呼叫。 相同的程式碼路徑也用於處理回傳使用者。
你可以手動新增這些程式碼,或用 GitHub Copilot 在 VS Code 中產生。
手動新增登入功能
在使用者手勢處理常式中呼叫 ensureSignedInWithFabric()(例如按鈕選取):
import { RayfinClient } from '@microsoft/rayfin-client';
import { ensureSignedInWithFabric } from '@microsoft/rayfin-auth-provider-fabric';
const client = new RayfinClient({
baseUrl: import.meta.env.VITE_RAYFIN_API_URL,
publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
});
const fabricOptions = {
workspaceId: import.meta.env.VITE_FABRIC_WORKSPACE_ID,
projectId: import.meta.env.VITE_FABRIC_ITEM_ID,
fabricPortalUrl: import.meta.env.VITE_FABRIC_PORTAL_URL,
returnOrigin: window.location.origin,
};
async function handleSignIn() {
// Signs in existing users and provisions new users on first sign-in.
const session = await ensureSignedInWithFabric(client.auth, fabricOptions);
if (session.isAuthenticated && session.user) {
console.log('Signed in as:', session.user.email);
}
}
該函式必須由同步使用者手勢處理程序呼叫,以避免彈出視窗阻擋。 在頁面載入時,或在使用者互動前的非同步呼叫鏈中呼叫它,都會觸發瀏覽器的彈出式視窗防護機制。
returnOrigin 必須是裸原點(方案與宿主,無路徑)——例如, https://app.contoso.com。 SDK 利用它來驗證進入 postMessage 的事件。
手動新增登出功能
呼叫 client.auth.signOut() 結束會話並清除快取的標記:
async function handleSignOut() {
await client.auth.signOut();
console.log('Signed out');
}
訂閱會話變更,以便在登入或登出完成後更新你的介面:
client.auth.onSessionChange((session) => {
console.log('Session changed:', session?.isAuthenticated ? 'signed in' : 'signed out');
});
使用 GitHub Copilot 產生登入與註冊
如果你使用 VS Code 中的 GitHub Copilot,請在你的 Fabric Apps 專案中開啟 Copilot Chat,並使用如下提示來建立驗證程式碼的基本架構。 Copilot 依循隨 Fabric VS Code 擴充功能附帶的 Rayfin 技能中的模式。
| 目標 | Copilot 提示 範例 |
|---|---|
| 新增登入按鈕 | Add a Sign in with Fabric button to my React app using ensureSignedInWithFabric from @microsoft/rayfin-auth-provider-fabric. Read workspaceId, projectId, and fabricPortalUrl from VITE_* env vars and set returnOrigin to window.location.origin. |
| 新增登出按鈕 | Add a Sign out button that calls client.auth.signOut() and updates the UI when the session ends. |
| 新增一個可感知驗證狀態的 React Hook | Create a useFabricAuth React hook that exposes session, signIn, signOut, and isAuthenticated, using ensureSignedInWithFabric and client.auth.onSessionChange. |
| 支援嵌入式模式 | Update my app's entry point to call initEmbeddedAuth on page load so users signed in through the Fabric portal don't have to click Sign in again. |
| 控管路由 | Wrap the /dashboard route so it calls ensureSignedInWithFabric before rendering and redirects unauthenticated users to a sign-in page. |
Copilot 產生程式碼後,請檢視修改內容並確保:
-
ensureSignedInWithFabric()呼叫會在使用者手勢處理常式中執行(例如onClick),而非在頁面載入時。 -
returnOrigin是裸來源,並且符合allowedRedirectUris中rayfin/rayfin.yml的其中一個項目。 - 匯入資料來自
@microsoft/rayfin-auth-provider-fabric(不是已棄用的回撥輔助工具)。
在 Fabric iframe 內使用嵌入式模式
當你的應用程式載入 Fabric iframe 時(例如使用者從 Fabric 入口開啟時),請使用嵌入模式取代彈出式流程:
- 嵌入模式會透過
postMessage從父框架取得工作階段。 - 它不會跳出視窗,也不需要使用者手勢,所以在頁面載入時呼叫是安全的。
- SDK 會從 URL 中的
?fabricEmbedded=true自動偵測是否為嵌入模式。 你也可以透過在選項中設定fabricEmbedded: true來強制啟用它。
在應用程式啟動初期盡早呼叫 initEmbeddedAuth():
import { initEmbeddedAuth } from '@microsoft/rayfin-auth-provider-fabric';
import { client } from './lib/rayfin';
const session = await initEmbeddedAuth(client.auth, {
workspaceId: import.meta.env.VITE_FABRIC_WORKSPACE_ID,
projectId: import.meta.env.VITE_FABRIC_ITEM_ID,
fabricPortalUrl: import.meta.env.VITE_FABRIC_PORTAL_URL,
returnOrigin: window.location.origin,
});
if (session) {
console.log('Signed in via embedded mode:', session.user?.email);
}
initEmbeddedAuth() 當應用程式沒有在嵌入式模式下運行時,它會回傳 null ,所以無條件呼叫是安全的。
ensureSignedInWithFabric() 也會自動嘗試嵌入模式,然後再回到彈出式流程。
在 React 中使用 Fabric 認證
建立一個整合登入、註冊與登出的自訂掛鉤:
import { useState, useEffect, useCallback } from 'react';
import { ensureSignedInWithFabric } from '@microsoft/rayfin-auth-provider-fabric';
import { client } from './lib/rayfin';
const fabricOptions = {
workspaceId: import.meta.env.VITE_FABRIC_WORKSPACE_ID,
projectId: import.meta.env.VITE_FABRIC_ITEM_ID,
fabricPortalUrl: import.meta.env.VITE_FABRIC_PORTAL_URL,
returnOrigin: window.location.origin,
};
export function useFabricAuth() {
const [session, setSession] = useState(client.auth.getSession());
useEffect(() => client.auth.onSessionChange(setSession), []);
// Signs in existing users and provisions new users on first sign-in.
const signIn = useCallback(async () => {
const result = await ensureSignedInWithFabric(client.auth, fabricOptions);
setSession(result);
return result;
}, []);
const signOut = useCallback(async () => {
await client.auth.signOut();
}, []);
return {
session,
signIn,
signOut,
isAuthenticated: session?.isAuthenticated ?? false,
};
}
在你的組件中使用這個鉤子:
function App() {
const { isAuthenticated, signIn, signOut } = useFabricAuth();
if (!isAuthenticated) {
return <button onClick={signIn}>Sign in with Fabric</button>;
}
return (
<>
<Dashboard />
<button onClick={signOut}>Sign out</button>
</>
);
}
使用現有的 Microsoft Entra 令牌登入
當您的瀏覽器或 Node.js 應用程式已經取得委派的Microsoft Entra存取權杖時,請使用signInWithEntraToken()。 它會在你現有的 client.auth 上建立 Rayfin 會話,沒有彈出視窗、iframe、重定向或切換代碼。
啟用外部 Entra 交換作業
在目標應用程式的 rayfin/rayfin.yml 檔案中設定以下選項,然後使用 npx rayfin up 重新部署:
services:
auth:
enabled: true
fabric:
enabled: true
externalEntraExchange: true
目標 Fabric 環境必須支援外部資料交換。 所提供的權杖必須:
- 應為委派的使用者存取權杖,而非僅應用程式的服務主體權杖。
- 以部署接受的 Fabric 或 Power BI 資源為目標。
- 包含委派的
Item.Execute.All範圍。 - 在目標項目所屬的租用戶中簽發。
使用者也必須對應用程式項目擁有 執行 權限。 對於生產環境的 Power BI,請透過你的身分識別程式庫申請https://analysis.windows.net/powerbi/api/Item.Execute.All。 SDK 不會取得 Entra 代幣或處理使用者同意。
瀏覽器使用情況
使用與資料客戶端相同的受信任 HTTPS 後端 URL 和可發佈金鑰:
import { signInWithEntraToken } from '@microsoft/rayfin-auth-provider-fabric';
import { client } from './lib/rayfin';
async function signInWithDelegatedToken(entraToken: string) {
const session = await signInWithEntraToken(client.auth, { entraToken });
return session;
}
直接傳遞原始存取權杖,不要加 Bearer 前綴。 輔助工具使用用戶端的後端基礎 URL,保留其部署路徑,並附加 /api/auth/v1/brokered/token。 基礎 URL 必須是絕對 HTTPS,且不包含認證資訊、查詢或片段。 不要使用靜態主機 URL、相對代理 URL 或不受信任呼叫者提供的端點。
同一客戶端的資料與函式呼叫會自動使用交換的 Rayfin 會話。 瀏覽器端交換還需要服務的 CORS 政策允許你的來源和授權標頭。
在你的 UI 中處理被拒絕的登入,並在允許該帳號執行動作前顯示錯誤。 失敗的交換可能會在記憶體中留下較舊且未過期的會話;不要將其視為新選擇使用者的成功認證。
Node.js 使用與會話隔離
你可以匯入並使用輔助工具,而不需要 window、document 或 localStorage。 若要獨立整合 SDK,請建構 Auth 並附加到 API 用戶端:
import { Auth } from '@microsoft/rayfin-auth';
import { ApiClient } from '@microsoft/rayfin-lib';
import { signInWithEntraToken } from '@microsoft/rayfin-auth-provider-fabric';
async function authenticateUser(
rayfinEndpoint: string,
publishableKey: string,
entraToken: string,
) {
const apiClient = new ApiClient({ baseUrl: rayfinEndpoint, publishableKey });
const auth = new Auth(apiClient, { storage: false });
auth.attachToClient(apiClient);
try {
const session = await signInWithEntraToken(auth, { entraToken });
// Perform this user's SDK operations with apiClient inside this scope.
return session.isAuthenticated;
} finally {
auth.destroy();
}
}
使用受信任且已設定的 rayfinEndpoint,而不是由呼叫端控制的 URL。 為每個使用者或請求建立獨立實例,將會話保存在記憶體中,當不再需要時銷毀。 切勿在使用者間共享可變的登入用戶端。 若使用 RayfinClient,請使用 authStorage: false 以獲得相同的純記憶體行為。
RayfinServerClient 不會暴露 auth,也無法直接傳給這個輔助函式。
SDK 不會持久化所提供的 Entra 令牌。 正常的工作階段重新整理使用 Rayfin 重新整理權杖;若無法再重新整理,則取得新的 Entra 權杖並明確交換。
嵌入外部父層入口網站
當 Fabric 外部的入口網站嵌入你的應用程式,且已有委派的 Entra 身份時,請使用@microsoft/rayfin-embed-host。 父頁面負責認證;iframe 只會收到一次性的交接碼,而非父頁面的 Entra 令牌。
啟用 externalEntraExchange 並滿足委派權杖、租用戶、範圍及項目 執行 前述前提條件。 授權進入父頁面並不代表存取 Fabric 應用程式。
在父平台安裝主機套件:
npm install @microsoft/rayfin-embed-host
在掛載 iframe 前 先註冊主機,因為 iframe 只會發送一次準備信號:
import { createEmbedHost } from '@microsoft/rayfin-embed-host';
function mountFabricApp(getAccessToken: () => Promise<string>) {
const appUrl = 'https://my-fabric-app.example.com';
const host = createEmbedHost({
allowedOrigins: [new URL(appUrl).origin],
getAccessToken,
});
const iframe = document.createElement('iframe');
iframe.src = appUrl;
document.body.append(iframe);
return () => {
iframe.remove();
host.dispose();
};
}
為目前的父層使用者提供代幣取得函式。 在內嵌應用程式中,即使 initEmbeddedAuth() 已經顯示有使用者,請先呼叫並等待 getSession(),才能恢復儲存的工作階段或呈現已驗證的內容。 儲存的使用者可能與父方目前的使用者不同。 主機確認偵測外部嵌入;此路徑無需 fabricEmbedded 查詢標誌。
在 allowedOrigins 中使用精確的可信來源,包括 scheme、host 和 port。 主機在進行授權呼叫前,會同時驗證瀏覽器認證的 iframe 訊息來源與請求的回傳來源。 不要接受任意由來電者提供的允許清單。 將 Entra 令牌保留在父授權路徑中,絕不要透過 postMessage 傳送它,並在移除嵌入時呼叫 host.dispose()。
API 參考資料
確保已使用 Fabric 登入
function ensureSignedInWithFabric(
auth: Auth,
options: FabricAuthOptions
): Promise<OpaqueSession>;
實作四步驟認證瀑布式:
- 如果已經認證過,會回傳現有的會話。
- 嘗試透過刷新標記進行靜默刷新。
- 嵌入模式——若運行於Fabric iframe,則透過
postMessage取得父框架的會話。 - 以彈出視窗(彈出流程)開啟Fabric傳送門,並等待
postMessage交接。
步驟 1 至 3 可在頁面載入時安全呼叫。 步驟 4 會開啟一個彈出視窗,必須在使用者手勢處理器中執行。
FabricAuthOptions
| Property | 類型 | Description |
|---|---|---|
workspaceId |
string |
Fabric 工作區的 ID。 |
projectId |
string |
Fabric 應用程式的商品 ID。 |
fabricPortalUrl |
string |
Fabric入口網站的基礎網址(例如 https://app.fabric.microsoft.com)。 |
returnOrigin |
string |
你的應用程式用於傳送 postMessage 的來源(例如 window.location.origin)。 必須是裸原點(方案和主機,沒有路徑)。 |
fabricEmbedded |
boolean (選用) |
強制內嵌模式。 從 URL 中的 ?fabricEmbedded=true 自動偵測。 |
輔助函式
| 功能 | Description |
|---|---|
initEmbeddedAuth(auth, options) |
適用於 Fabric 或已確認的外部父主機、可在頁面載入時安全使用的驗證。 成功時回傳工作階段;若無法使用內嵌驗證則回傳 null。 |
initiateFabricLogin(auth, options) |
低階彈出式視窗流程。 在快顯視窗中使用 PKCE 參數開啟 Fabric 入口網站,並監聽 postMessage 交接。 |
isEmbeddedMode(options) |
若應用程式以嵌入式模式(Fabric iframe)運行,則回傳 true。 |
signInWithEntraToken(auth, { entraToken }) |
兌換委派的 Entra 權杖,並在瀏覽器或 Node.js 建立工作階段。 不需要 FabricAuthOptions。 |
安全特徵
- PKCE S256 – 交接流程會產生加密編譯的程式碼驗證碼與挑戰,以防止授權碼遭攔截。 直接 Entra 權杖交換不會使用 PKCE。
- 狀態 nonce-隨機 nonce 會將交接回應與發起該流程的原始分頁綁定,防止跨站請求偽造。
-
postMessage來源驗證 – SDK 會驗證event.origin收到的訊息,並拒絕來自意外來源的訊息。 - 自動清理 ——PKCE 狀態在 5 分鐘後失效,並在下一次流程中進行垃圾回收。
- 流程逾時 – 若未收到交接訊息,快顯視窗流程將於 5 分鐘後逾時。
針對驗證問題進行疑難排解
彈出視窗被封鎖
瀏覽器封鎖了 Fabric 入口視窗。 Ensure ensureSignedInWithFabric() 是由同步使用者手勢處理程式(例如按鈕 onClick)呼叫的。 不要在頁面載入時或使用者互動前在非同步鏈內呼叫它。
會話無法持續
確認 該 RayfinClient 設定為正確的 baseUrl 和 publishableKey。 回調分頁和原始分頁必須共享相同的起點BroadcastChannellocalStorage,才能運作。
驗證在長時間延遲後失敗
登入流程在 5 分鐘後終止。 如果你開始登入流程但沒在這段時間內完成,流程就會失敗。 關閉彈出視窗,再次選擇登入按鈕開始新的流程。