Konfigurujte autentifikáciu Fabric SSO pre vašu Fabric aplikáciu

Nastavte Fabric single sign-on (SSO) pre Fabric aplikáciu, aby sa používatelia mohli prihlásiť pomocou Microsoft Entra ID cez Fabric portál. Tento článok vysvetľuje proces odovzdávania a ukazuje, ako povoliť požadovanú konfiguráciu a integráciu SDK pre nasadené aplikácie.

Predpoklady

Projekt Fabric Apps s povolenou autentifikáciou. Pozri Konfigurovať autentifikáciu.
Nasadená položka Fabric Apps. Pozri Nasadiť do Fabric.

Ako funguje Fabric SSO

Fabric Single Sign-on (SSO) používa bezpečné odovzdanie postMessage medzi vašou aplikáciou a Fabric portálom. Neexistuje žiadna stránka na presmerovanie ani spätné volanie:

Vaša aplikácia otvorí Fabric portál v vyskakucom okne a zaregistruje poslucháča postMessage.
Používateľ sa autentifikuje cez Microsoft Entra ID vo vnútri portálu Fabric.
Rozšírenie Fabric posiela kód na odovzdanie späť vašej aplikácii cez window.opener.postMessage().
SDK vymení handoff kód za Rayfin session tokeny a vytvorí reláciu.
Vyskakovacie okno Fabric sa automaticky zatvorí.

Tok je zabezpečený pomocou PKCE (Proof Key for Code Exchange), stavových nonce a validácie pôvodu postMessage, aby sa zabránilo zachyteniu autorizačného kódu a falšovaniu požiadaviek medzi lokalitami.

Povoliť autentifikáciu Fabric

Pridajte konfiguráciu Fabric autentifikácie do svojho rayfin/rayfin.yml súboru:

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

Pre nasadené aplikácie znovu nasadiť, aby ste posunuli aktualizované nastavenia:

npx rayfin up

Pre nasadené aplikácie pridáva npx rayfin up URL spätného volania nasadených aplikácií do allowedRedirectUris.

Nainštalujte poskytovateľa autentifikácie Fabric (voliteľné)

Projekty, ktoré sú už podobudnuté npm create @microsoft/rayfin@latest , zahŕňajú @microsoft/rayfin-auth-provider-fabric. Nainštalujte ho manuálne len v prípade, že pridávate Fabric autentifikáciu do projektu, ktorý už balík nemá:

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

Fabric SSO používa jedno API na prihlásenie aj registráciu: ensureSignedInWithFabric(). Keď sa používateľ prvýkrát prihlási, Fabric mu automaticky skonfiguruje Rayfin reláciu na základe jeho identity Microsoft Entra ID – neexistuje samostatné registračné volanie. Rovnaká kódová cesta spracováva vracajúcich sa používateľov.

Tento kód môžete pridať ručne alebo ho vygenerovať pomocou GitHub Copilot vo VS Code.

Volanie ensureSignedInWithFabric() z handlera používateľských gest (napríklad výber tlačidla):

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

Funkcia musí byť volaná zo synchronného sprostredkovateľa používateľských gest, aby sa predišlo blokátorom vyskakovacích okien. Volanie pri načítaní stránky alebo v asynchrónnom reťazci pred interakciou používateľa spustí ochranu vyskakovacích okien prehliadača.

returnOrigin musí byť holý počiatok (schéma a hostiteľ, žiadna cesta)—napríklad https://app.contoso.com. SDK ho používa na overovanie prichádzajúcich postMessage udalostí.

Pridajte odhlásenie manuálne

Zavolajte client.auth.signOut() na ukončenie relácie a vyčistenie cacheovaných tokenov:

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

Prihláste sa na odber zmien relácie, aby ste aktualizovali svoje používateľské rozhranie po dokončení prihlásenia alebo odhlásenia:

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

Ak používate GitHub Copilot vo VS Code, otvorte Copilot Chat vo svojom projekte Fabric Apps a použite takéto výzvy na prepojenie autentifikačného kódu. Copilot nasleduje vzory zo zručností Rayfin, ktoré sú súčasťou rozšírenia Fabric VS Code.

Goal	Príklad príkaz funkcie Copilot
Pridajte tlačidlo na prihlásenie	`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.`
Pridajte tlačidlo na odhlásenie	`Add a Sign out button that calls client.auth.signOut() and updates the UI when the session ends.`
Pridajte auth-aware React hook	`Create a useFabricAuth React hook that exposes session, signIn, signOut, and isAuthenticated, using ensureSignedInWithFabric and client.auth.onSessionChange.`
Podpora zabudovaného režimu	`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.`
Gate a trasa	`Wrap the /dashboard route so it calls ensureSignedInWithFabric before rendering and redirects unauthenticated users to a sign-in page.`

Po tom, čo Copilot vygeneruje kód, skontrolujte úpravy a uistite sa:

Volanie prebieha ensureSignedInWithFabric() v rámci používateľského obsługovača gest (napríklad, onClick)—nie pri načítavaní stránky.
returnOriginje holý počiatok a zodpovedá jednému zo prvkov v allowedRedirectUris .rayfin/rayfin.yml
Importy pochádzajú od @microsoft/rayfin-auth-provider-fabric (nie od zastaraných callback helperov).

Použite vložený režim vo vnútri Fabric iframe

Keď sa vaša aplikácia načíta vo Fabric iframe (napríklad keď ju používateľ otvorí cez Fabric portál), použite vložený režim namiesto vyskakovacieho toku:

Vložený režim prijíma reláciu až postMessage do rodičovského rámca.
Neotvára sa vyskakovacie okno a nevyžaduje žiadne gesto používateľa, takže je bezpečné volať pri načítaní stránky.
SDK automaticky detekuje zabudovaný režim z ?fabricEmbedded=true URL. Môžete to tiež vynútiť nastavením fabricEmbedded: true v nastaveniach.

Zavolajte initEmbeddedAuth() už na začiatku začiatku aplikácie:

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() Vráti sa null , keď aplikácia nebeží v zabudovanom režime, takže je bezpečné volať bezpodmienečne. ensureSignedInWithFabric() Tiež skúša zabudovaný režim automaticky, než sa vráti k toku vyskakovacích okien.

Použite autentifikáciu Fabric v Reacte

Vytvorte vlastný háčik, ktorý integruje prihlásenie, registráciu a odhlásenie:

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

Použite háčik vo svojich komponentoch:

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

Referenčné informácie o rozhraní API

ensureSignedInFabric

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

Implementuje štvorstupňový autentifikačný vodopád:

Vráti existujúcu reláciu, ak je už autentifikovaná.
Snaží sa o tiché obnovenie cez obnovovací token.
Vložený režim – ak beží v Fabric iframe, prijíma reláciu cez postMessage do rodičovského rámca.
Otvorí Fabric portál v vyskakucom okne (popup flow) a čaká na odovzdanie postMessage.

Kroky 1 až 3 je bezpečné zavolať pri načítaní stránky. Krok 4 otvorí vyskakovacie okno a musí bežať vo vnútri používateľského manipulátora gest.

FabricAuthOptions

Vlastnosť	Typ	Description
`workspaceId`	`string`	Fabric workspace ID.
`projectId`	`string`	ID položky v aplikácii Fabric.
`fabricPortalUrl`	`string`	Základná URL Fabric portálu (napríklad `https://app.fabric.microsoft.com`).
`returnOrigin`	`string`	Pôvod vašej aplikácie pre `postMessage` doručenie (napríklad, `window.location.origin`). Musí to byť holý pôvod (schéma a hostiteľ, bez cesty).
`fabricEmbedded`	`boolean` (voliteľné)	Force embedded režim. Automaticky detegované z `?fabricEmbedded=true` URL.

Pomocné funkcie

Funkcia	Description
`initEmbeddedAuth(auth, options)`	Vstavaná autentifikácia bezpečná pri načítaní stránok. Vráti reláciu, ak beží v Fabric iframe, alebo `null` inak.
`initiateFabricLogin(auth, options)`	Nízkoúrovňový tok vyskakovacích okien. Otvorí Fabric portál v vyskakucom okne s parametrami PKCE a počúva odovzdanie `postMessage`.
`isEmbeddedMode(options)`	Vráti `true`, ak aplikácia beží v zabudovanom režime (Fabric iframe).

Funkcie zabezpečenia

PKCE S256 – Každý tok generuje kryptografický overovateľ kódu a výzvu, aby zabránil zachyteniu autorizačného kódu.
Stav nonce – Náhodný nonce viaže odpoveď na odovzdanie s pôvodnou záložkou, čím zabraňuje falšovaniu požiadaviek medzi lokalitami.
postMessage overenie pôvodu – SDK overuje event.origin prichádzajúce správy a odmieta správy z neočakávaných zdrojov.
Automatické čistenie – stav PKCE vyprší po 5 minútach a pri ďalšom toku je odvozený do odpadu.
Flow timeout – Vyskakovacie okno flow vyprší po 5 minútach, ak nie je prijatá žiadna správa o odovzdaní.

Riešenie problémov s autentifikáciou

Prehliadač zablokoval okno portálu Fabric. Ensure ensureSignedInWithFabric() je volaný zo synchronného používateľského manipulátora gest (napríklad tlačidlo onClick). Nevolajte to pri načítaní stránky alebo v asynchrónnom reťazci pred interakciou používateľa.

Relácia nepretrváva

Potvrďte, že je nastavený RayfinClient s správnymi baseUrl a publishableKey. Záložka callback a pôvodná záložka musia mať rovnaký pôvod, aby BroadcastChannel fungovali a localStorage aby fungovali.

Autentifikácia zlyhá po dlhom oneskorení

Proces prihlasovania vyprší po 5 minútach. Ak spustíte proces prihlásenia, ale nedokončíte ho v tomto čase, proces zlyhá. Zatvorte vyskakovacie okno a opäť vyberte tlačidlo prihlásenia, aby ste spustili nový flow.

Pripomienky

Bola táto stránka užitočná?

Last updated on 2026-06-02