Nakonfigurujte ověřování pomocí jednotného přihlašování Fabric pro aplikaci Fabric

Nastavte Fabric jednotného přihlašování (SSO) pro aplikaci Fabric, aby se uživatelé mohli přihlásit pomocí Microsoft Entra ID prostřednictvím portálu Fabric. Tento článek vysvětluje tok předání a ukazuje, jak povolit požadovanou konfiguraci a integraci sady SDK pro nasazené aplikace.

Předpoklady

• Projekt Fabric Apps s povoleným ověřováním Viz Konfigurace ověřování.
• Nasazená položka aplikace Fabric Viz Nasazení do Fabric.

Jak funguje Fabric SSO

Fabric jednotné přihlašování (SSO) používá zabezpečené předání založené na postMessage mezi vaší aplikací a portálem Fabric. Stránka přesměrování ani zpětného volání neexistuje:

1. Vaše aplikace otevře portál Fabric ve vyskakovacím okně a zaregistruje posluchač postMessage.
2. Uživatel se ověřuje prostřednictvím Microsoft Entra ID na portálu Fabric.
3. Rozšíření Fabric odešle předávací kód zpět do aplikace prostřednictvím window.opener.postMessage().
4. SDK vymění předávací kód za tokeny relace Rayfin a vytvoří relaci.
5. Vyskakovací okno Fabric se zavře automaticky.

Tok autorizace je zabezpečen pomocí PKCE (ověřovacího klíče pro výměnu kódu), jednorázových hodnot state (nonce) a ověření původu postMessage, aby se zabránilo zachycení autorizačního kódu a útokům CSRF.

Povolte ověřování Fabric

Do souboru rayfin/rayfin.yml přidejte konfiguraci ověřování Fabric:

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

U nasazených aplikací znovu nasaďte aktualizované nastavení:

npx rayfin up

Pro nasazené aplikace npx rayfin up přidá adresu URL zpětného volání nasazené aplikace do allowedRedirectUris.

Instalace poskytovatele ověřování Fabric (volitelné)

Projekty vytvořené pomocí npm create @microsoft/rayfin@latest již obsahují @microsoft/rayfin-auth-provider-fabric. Nainstalujte ho ručně jenom v případě, že přidáváte ověřování Fabric do projektu, který balíček ještě nemá:

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

Přidání přihlášení a registrace do aplikace

Jednotné přihlašování ve Fabric používá jedno rozhraní API pro přihlášení i vytvoření účtu: ensureSignedInWithFabric(). Když se uživatel poprvé přihlásí, Fabric pro ně automaticky zřídí relaci Rayfin na základě své Microsoft Entra ID identity – neexistuje žádný samostatný registrační hovor. Stejná větev kódu zpracovává i vracející se uživatele.

Tento kód můžete přidat ručně nebo ho vygenerovat pomocí GitHub Copilot ve VS Code.

Přidat přihlášení ručně

Volání ensureSignedInWithFabric() z obslužné rutiny gesta uživatele (například výběr tlačítka):

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

Aby nedocházelo k blokování automaticky otevíraných oken, musí být funkce volána z synchronní obslužné rutiny gest uživatele. Jeho volání při načtení stránky nebo v rámci asynchronního řetězce před interakcí uživatele spustí ochranu prohlížeče proti vyskakovacím oknům.

returnOrigin musí být holý původ (schéma a hostitel, bez cesty)– například https://app.contoso.com. Sada SDK ji používá k ověření příchozích postMessage událostí.

Přidat odhlášení ručně

Volání client.auth.signOut() pro ukončení relace a vymazání tokenů uložených v mezipaměti:

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

Přihlaste se k odběru změn relace a aktualizujte uživatelské rozhraní po dokončení přihlášení nebo odhlášení:

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

Generování přihlášení a registrace pomocí GitHub Copilot

Pokud používáte GitHub Copilot ve VS Code, otevřete v projektu Fabric Apps Copilot Chat a pomocí podobných výzev vygenerujte autentizační kód. Copilot vychází ze vzorů v dovednosti Rayfin dodávané s rozšířením Fabric VS Code.

Goal	Příklad výzva Copilota
Přidání tlačítka pro přihlášení	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.
Přidání tlačítka pro odhlášení	Add a Sign out button that calls client.auth.signOut() and updates the UI when the session ends.
Přidejte React hook pro autentizaci	Create a useFabricAuth React hook that exposes session, signIn, signOut, and isAuthenticated, using ensureSignedInWithFabric and client.auth.onSessionChange.
Podporovat vložený režim	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.
Omezit přístup k trase	Wrap the /dashboard route so it calls ensureSignedInWithFabric before rendering and redirects unauthenticated users to a sign-in page.

Po Copilot vygenerování kódu zkontrolujte úpravy a ujistěte se, že:

• Volání ensureSignedInWithFabric() se spustí uvnitř obslužné rutiny uživatelského gesta (například onClick), ne při načítání stránky.
• returnOrigin je samotný origin a odpovídá jednomu ze záznamů v allowedRedirectUris v rayfin/rayfin.yml.
• Importy se importují z @microsoft/rayfin-auth-provider-fabric (ne ze zastaralých pomocných funkcí pro callbacky).

Použijte režim vložení v rámci prvku iframe Fabric

Když se vaše aplikace načte uvnitř iframe Fabricu (například když ji uživatel otevře z portálu Fabric), použijte místo postupu s vyskakovacím oknem vložený režim:

• Vložený režim získává relaci prostřednictvím postMessage z rodičovského rámce.
• Neotevírá vyskakovací okno a nevyžaduje gesto uživatele, takže jej lze bezpečně volat během načítání stránky.
• Sada SDK automaticky rozpozná vložený režim z ?fabricEmbedded=true adresy URL. Můžete ho také vynutit nastavením fabricEmbedded: true v možnostech.

Zavolejte initEmbeddedAuth() na začátku spouštění aplikace:

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átí null , když aplikace není spuštěná v integrovaném režimu, takže je bezpečné volat bezpodmínečně. ensureSignedInWithFabric() také se pokusí automaticky zkusit vložený režim před návratem do automaticky otevíraných oken.

Použití ověřování Fabric v Reactu

Vytvořte vlastní háček, který integruje přihlášení, registraci a odhlášení:

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žijte háček ve svých součástech:

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í informace k rozhraní API

ensureSignedInWithFabric

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

Implementuje vodopád ověřování ve čtyřech krocích:

1. Vrátí existující relaci, pokud už je autentizovaná.
2. Pokusí se o tichou aktualizaci pomocí obnovovacího tokenu.
3. Vložený režim – pokud běží uvnitř iframu Fabric, získává relaci prostřednictvím postMessage z rodičovského rámce.
4. Otevře portál Fabric ve vyskakovacím okně (tok ve vyskakovacím okně) a počká na předání postMessage.

Kroky 1 až 3 jsou bezpečné pro volání při načítání stránky. Krok 4 otevře vyskakovací okno a musí běžet v obslužné rutině uživatelského gesta.

FabricAuthOptions

Property	Typ	Description
workspaceId	string	ID pracovního prostoru Fabric.
projectId	string	ID položky aplikace Fabric.
fabricPortalUrl	string	Základní adresa URL portálu Fabric (například https://app.fabric.microsoft.com).
returnOrigin	string	Původ vaší aplikace pro postMessage doručení (například window.location.origin). Musí to být holý původ (schéma a hostitel, žádná cesta).
fabricEmbedded	boolean (volitelné)	Vynutit vložený režim. Automaticky rozpoznáno z ?fabricEmbedded=true adresy URL.

Pomocné funkce

Function	Description
initEmbeddedAuth(auth, options)	Integrované ověřování bezpečné při načtení stránky. Vrátí relaci, pokud běží v rámci iframe Fabric, nebo jinak null.
initiateFabricLogin(auth, options)	Průběh vyskakovacího okna na nízké úrovni Otevře portál Fabric ve vyskakovacím okně s parametry PKCE a čeká na předání postMessage.
isEmbeddedMode(options)	Vrátí true, pokud je aplikace spuštěná v integrovaném režimu (Fabric iframe).

Funkce zabezpečení

• PKCE S256 – Každý tok generuje ověřovatel kryptografického kódu a výzvu, aby se zabránilo zachycení autorizačního kódu.
• State nonce – Náhodná jednorázová hodnota propojí odpověď handoffu s původní kartou prohlížeče, čímž brání útokům typu CSRF (padělání požadavků mezi weby).
• postMessage ověření původu – Sada SDK ověřuje event.origin příchozí zprávy a odmítá zprávy z neočekávaných zdrojů.
• Automatické čištění – Platnost stavu PKCE vyprší po 5 minutách a při dalším průchodu je automaticky odstraněn z paměti.
• Časový limit průběhu – Časový limit vyskakovacího průběhu vyprší po 5 minutách, pokud není přijata žádná předávací zpráva.

Řešení potíží s ověřováním

Automaticky otevírané okno zablokováno

Prohlížeč zablokoval okno portálu Fabric. Ujistěte se, že k volání ensureSignedInWithFabric() dochází v synchronní obsluze uživatelského gesta (například v obsluze tlačítka onClick). Před interakcí uživatele ji nezavolejte při načítání stránky ani uvnitř asynchronního řetězce.

Relace se neudržuje

Ověřte, že RayfinClient je nakonfigurován se správnými baseUrl a publishableKey. Panel zpětného volání a původní panel musí mít stejný původ, aby BroadcastChannel a localStorage fungovaly.

Ověřování po dlouhé prodlevě selže.

Tok přihlášení vyprší po 5 minutách. Pokud spustíte proces přihlášení, ale nedokončíte ho během této doby, tok selže. Zavřete automaticky otevírané okno a znovu vyberte tlačítko pro přihlášení a spusťte nový tok.

Související obsah

• Konfigurace ověřování
• Nasadit do Fabric
• Definování datových modelů