Fabric SSO-hitelesítés konfigurálása az Fabric-alkalmazáshoz

Állítson be Fabric egyszeri bejelentkezést (SSO) egy Fabric-alkalmazáshoz, hogy a felhasználók a Fabric portálon keresztül Microsoft Entra ID bejelentkezhessenek. Ez a cikk ismerteti az átadási folyamatot, és bemutatja, hogyan engedélyezheti a szükséges konfigurációt és SDK-integrációt az üzembe helyezett alkalmazásokhoz.

Prerequisites

• Egy Fabric Apps-projekt, amelyen engedélyezve van a hitelesítés. Lásd: Hitelesítés konfigurálása.
• Telepített Fabric Apps-elem. Lásd: Deploy to Fabric.

A Fabric SSO működése

Fabric egyszeri bejelentkezés (SSO) biztonságos postMessage-alapú átadást használ az alkalmazás és a Fabric portál között. Nincs átirányítási vagy visszahívási oldal:

1. Az alkalmazás megnyitja a Fabric portált egy előugró ablakban, és regisztrál egy postMessage figyelőt.
2. A felhasználó a Fabric portálon Microsoft Entra ID keresztül hitelesít.
3. A Fabric bővítmény elküldi az átadási kódot az alkalmazásnak window.opener.postMessage() keresztül.
4. Az SDK kicseréli a Rayfin-munkamenet jogkivonatainak átadási kódját, és létrehoz egy munkamenetet.
5. A Fabric előugró ablak automatikusan bezárul.

A folyamat PKCE (Proof Key for Code Exchange), state nonces és postMessage origin validation használatával van biztosítva, hogy megakadályozza az engedélyezési kód elfogását és a helyek közötti kérések hamisítását.

Fabric hitelesítés engedélyezése

Adja hozzá a Fabric hitelesítési konfigurációt a rayfin/rayfin.yml fájlhoz:

services:
  auth:
    enabled: true
    allowedRedirectUris:
      - http://localhost:5173
    fabric:
      enabled: true

A már üzembe helyezett alkalmazásokat telepítse újra, hogy a frissített beállítások érvénybe lépjenek:

npx rayfin up

Az üzembe helyezett alkalmazások esetében a npx rayfin up hozzáadja az üzembe helyezett alkalmazás visszahívási URL-címét a(z) allowedRedirectUris elemhez.

A Fabric hitelesítésszolgáltató telepítése (nem kötelező)

A npm create @microsoft/rayfin@latest használatával létrehozott projektek már tartalmazzák a(z) @microsoft/rayfin-auth-provider-fabric elemet. Csak akkor telepítse manuálisan, ha Fabric hitelesítést ad hozzá olyan projekthez, amely még nem rendelkezik a csomagval:

npm install @microsoft/rayfin-auth-provider-fabric

Bejelentkezés és regisztráció hozzáadása az alkalmazáshoz

A Fabric SSO egyetlen API-t használ mind a bejelentkezéshez, mind a fiók létrehozásához: ensureSignedInWithFabric(). Amikor egy felhasználó először jelentkezik be, Fabric automatikusan kioszt egy Rayfin-munkamenetet a Microsoft Entra ID identitása alapján – nincs külön regisztrációs hívás. Ugyanaz a kódútvonal kezeli a visszatérő felhasználókat.

Ezt a kódot manuálisan is hozzáadhatja, vagy létrehozhatja GitHub Copilot a VS Code-ban.

Bejelentkezés kézi hozzáadása

Hívja meg a(z) ensureSignedInWithFabric()-t egy felhasználói műveletet kezelő eseménykezelőből (például egy gomb kiválasztásakor):

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);
  }
}

A függvényt szinkron felhasználói kézmozdulat-kezelőből kell meghívni az előugró ablakok blokkolásának elkerülése érdekében. Lapbetöltéskor vagy aszinkron láncon belül hívhatja meg, mielőtt a felhasználói beavatkozás aktiválja a böngésző előugró ablakának védelmét.

A(z) returnOrigin értékének csupasz originnek kell lennie (protokoll és host, elérési út nélkül) – például https://app.contoso.com. Az SDK a bejövő postMessage események ellenőrzésére használja.

Kijelentkezés manuális hozzáadása

Hívja meg a(z) client.auth.signOut() elemet a munkamenet befejezéséhez és a gyorsítótárazott tokenek törléséhez:

async function handleSignOut() {
  await client.auth.signOut();
  console.log('Signed out');
}

Iratkozzon fel a munkamenet módosításaira a felhasználói felület frissítéséhez a bejelentkezés vagy a kijelentkezés befejezésekor:

client.auth.onSessionChange((session) => {
  console.log('Session changed:', session?.isAuthenticated ? 'signed in' : 'signed out');
});

Bejelentkezési és regisztrációs felület generálása a GitHub Copilottal

Ha a VS Code-ban használt GitHub Copilotot használja, nyissa meg a Copilot Chatet a Fabric Apps-projektjében, és az alábbihoz hasonló utasításokkal hozza létre a hitelesítési kód alapjait. Copilot a Fabric VS Code-bővítményhez mellékelt Rayfin-képesség mintáit követi.

Cél	Példa a Copilot-utasításra
Bejelentkezési gomb hozzáadása	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.
Kijelentkezés hozzáadása gomb	Add a Sign out button that calls client.auth.signOut() and updates the UI when the session ends.
Hitelesítésérzékeny React-horog hozzáadása	Create a useFabricAuth React hook that exposes session, signIn, signOut, and isAuthenticated, using ensureSignedInWithFabric and client.auth.onSessionChange.
Beágyazott mód támogatása	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.
Útvonal hozzáférésének korlátozása	Wrap the /dashboard route so it calls ensureSignedInWithFabric before rendering and redirects unauthenticated users to a sign-in page.

Miután Copilot generálta a kódot, tekintse át a módosításokat, és győződjön meg arról, hogy:

• A ensureSignedInWithFabric() hívás egy felhasználói kézmozdulat-kezelőn belül fut (például onClick)– nem oldalbetöltés közben.
• A(z) returnOrigin egy üres eredet, és megegyezik a(z) allowedRedirectUris egyik bejegyzésével itt: rayfin/rayfin.yml.
• Az importok a @microsoft/rayfin-auth-provider-fabric elemből származnak (nem az elavult visszahívási segédfüggvényekből).

Beágyazott mód használata Fabric iframe-ben

Ha az alkalmazás betöltődik egy Fabric iframe-ben (például amikor egy felhasználó megnyitja a Fabric portálról), használjon beágyazott módot az előugró folyamat helyett:

• A beágyazott mód a munkamenetet a szülő keretből a(z) postMessage segítségével kéri le.
• Nem nyit meg előugró ablakokat, és nem igényel felhasználói kézmozdulatot, így biztonságosan meghívhatja az oldalbetöltést.
• Az SDK automatikusan észleli a beágyazott módot az URL-címből ?fabricEmbedded=true . Ezt a beállításoknál a fabricEmbedded: true beállításával is kikényszerítheti.

Hívja meg a(z) initEmbeddedAuth() elemet az alkalmazás indulásának korai szakaszában:

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() akkor ad null vissza, ha az alkalmazás nem beágyazott módban fut, így nyugodtan hívhat feltétel nélkül. ensureSignedInWithFabric() először automatikusan a beágyazott módot próbálja meg, mielőtt átvált a felugró ablakos folyamatra.

Fabric hitelesítés használata a Reactben

Hozzon létre egy egyéni horogot, amely integrálja a bejelentkezést, a regisztrációt és a kijelentkezéseket:

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,
  };
}

Használja a hookot a komponenseiben:

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>
    </>
  );
}

API-referencia

ensureSignedInWithFabric

function ensureSignedInWithFabric(
  auth: Auth,
  options: FabricAuthOptions
): Promise<OpaqueSession>;

Négylépcsős hitelesítési folyamatot valósít meg:

1. Ha már megtörtént a hitelesítés, a meglévő munkamenetet adja vissza.
2. Csendes frissítést kísérel meg a frissítési token segítségével.
3. Beágyazott mód – ha egy Fabric iframe-ben fut, a munkamenetet a postMessage használatával a szülőkerettől kéri le.
4. Megnyitja a Fabric portált egy előugró ablakban (felugró ablakos folyamat), és vár a postMessage átadásra.

Az 1–3. lépés biztonságosan meghívható az oldal betöltésekor. A 4. lépés megnyitja az előugró ablakokat, és egy felhasználói kézmozdulat-kezelőben kell futnia.

FabricAuthOptions

Property	Típus	Description
workspaceId	string	A Fabric munkaterület azonosítója.
projectId	string	Az Fabric alkalmazáselem-azonosító.
fabricPortalUrl	string	A Fabric portál alap URL-címe (például https://app.fabric.microsoft.com).
returnOrigin	string	Az alkalmazás postMessage kiszolgálásának forrása (például window.location.origin). Csak csupasz eredet lehet (protokoll és hoszt, elérési út nélkül).
fabricEmbedded	boolean (nem kötelező)	Beágyazott mód kényszerítése. Automatikusan észlelhető az URL-címből ?fabricEmbedded=true .

Segítő függvények

Function	Description
initEmbeddedAuth(auth, options)	Oldalbetöltéskor biztonságos beágyazott hitelesítés. A munkamenetet adja vissza, ha egy Fabric iframe-en belül fut, ellenkező esetben pedig a(z) null értéket.
initiateFabricLogin(auth, options)	Alacsony szintű felugróablak-folyamat. Megnyitja a Fabric portált egy PKCE-paraméterekkel ellátott felugró ablakban, és figyeli a(z) postMessage átadást.
isEmbeddedMode(options)	A true adja vissza, ha az alkalmazás beágyazott módban fut (Fabric iframe).

Biztonsági funkciók

• PKCE S256 – Minden folyamat létrehoz egy titkosítási kód-ellenőrzőt, és kihívást jelent az engedélyezési kód elfogásának megakadályozása érdekében.
• State nonce – Egy véletlenszerű nonce az átadási választ az eredeti laphoz köti, megakadályozva a helyek közötti kéréshamisítást.
• postMessage forrásérvényesítés – Az SDK ellenőrzi event.origin a bejövő üzeneteket, és elutasítja a váratlan eredetű üzeneteket.
• Automatikus tisztítás – A PKCE-állapot 5 perc után lejár, és a következő folyamat során eltávolításra kerül.
• Folyamat időtúllépése – Az előugró folyamat 5 perc elteltével időtúllépést jelent, ha nem érkezik átadási üzenet.

Hitelesítési problémák hibaelhárítása

Előugró ablak le van tiltva

A böngésző letiltotta a Fabric portálablakot. Győződjön meg arról, hogy a(z) ensureSignedInWithFabric() meghívása szinkron, felhasználói műveletet kezelő függvényből történik (például a(z) onClick gombkezelőből). Ne hívja meg lapbetöltéskor vagy aszinkron láncon belül a felhasználói beavatkozás előtt.

A munkamenet nem marad fenn

Győződjön meg arról, hogy a(z) RayfinClient a megfelelő baseUrl és publishableKey használatával van konfigurálva. Ahhoz, hogy a BroadcastChannel és a localStorage működjön, a visszahívó fülnek és az eredeti fülnek azonos eredetűnek kell lennie.

A hitelesítés hosszú késés után meghiúsul

A bejelentkezési folyamat 5 perc után lejár. Ha elindítja a bejelentkezési folyamatot, de nem fejezi be az adott időn belül, a folyamat meghiúsul. Zárja be az előugró menüt, és kattintson ismét a bejelentkezési gombra egy új folyamat elindításához.

Kapcsolódó tartalom

• Hitelesítés konfigurálása
• Deploy to Fabric
• Adatmodellek definiálása