Eenmalige aanmelding van Fabric configureren voor uw Fabric-app

Stel Fabric eenmalige aanmelding (SSO) in voor een Fabric-app, zodat gebruikers zich kunnen aanmelden met Microsoft Entra ID via de Fabric-portal. In dit artikel wordt het handoffproces uitgelegd en ziet u hoe u de vereiste configuratie en SDK-integratie voor gedeployde apps inschakelt.

Prerequisites

• Een Fabric Apps-project waarvoor verificatie is ingeschakeld. Zie Verificatie configureren.
• Een uitgerold Fabric Apps-item. Zie Implementeren in Fabric.

Hoe Fabric SSO werkt

Fabric eenmalige aanmelding (SSO) maakt gebruik van een veilige overdracht op basis van postMessage tussen uw toepassing en de Fabric-portal. Er is geen omleidings- of callbackpagina:

1. De app opent de Fabric-portal in een pop-up en registreert een postMessage listener.
2. De gebruiker wordt geverifieerd via Microsoft Entra ID in de Fabric-portal.
3. De Fabric-extensie verzendt de handoff-code terug naar uw app via window.opener.postMessage().
4. De SDK wisselt de handoff-code voor Rayfin-sessietokens uit en maakt een sessie.
5. De Fabric pop-up wordt automatisch gesloten.

De procedure wordt beveiligd met PKCE (Proof Key for Code Exchange), state-nonces en postMessage validatie van de oorsprong om te voorkomen dat de autorisatiecode wordt onderschept en cross-site request forgery plaatsvindt.

Fabric-verificatie inschakelen

Voeg de Fabric-verificatieconfiguratie toe aan het bestand rayfin/rayfin.yml:

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

Voor uitgerolde toepassingen: rol opnieuw uit om de bijgewerkte instellingen door te voeren:

npx rayfin up

Voor geïmplementeerde apps npx rayfin up voegt u de callback-URL van uw geïmplementeerde app toe aan allowedRedirectUris.

De Fabric-verificatieprovider installeren (optioneel)

Projecten die met npm create @microsoft/rayfin@latest zijn opgezet, bevatten al @microsoft/rayfin-auth-provider-fabric. Installeer deze handmatig alleen als u Fabric verificatie toevoegt aan een project dat nog niet over het pakket beschikt:

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

Aanmelden en registreren toevoegen aan uw app

Fabric Single Sign-On gebruikt één API voor zowel aanmelden als registreren: ensureSignedInWithFabric(). Wanneer een gebruiker zich voor de eerste keer aanmeldt, Fabric een Rayfin-sessie automatisch inricht op basis van hun Microsoft Entra ID identiteit. Er is geen afzonderlijke registratieoproep. Hetzelfde codepad verwerkt terugkerende gebruikers.

U kunt deze code handmatig toevoegen of genereren met GitHub Copilot in VS Code.

Aanmelding handmatig toevoegen

Roep ensureSignedInWithFabric() aan vanuit een handler voor een gebruikersactie (bijvoorbeeld het selecteren van een knop):

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

De functie moet worden aangeroepen vanuit een synchrone handler voor gebruikersbewegingen om pop-upblokkeringen te voorkomen. Als u dit aanroept tijdens het laden van de pagina of binnen een asynchrone keten vóór gebruikersinteractie, wordt de pop-upbeveiliging van de browser geactiveerd.

returnOrigin moet een lege oorsprong zijn (schema en host, geen pad), bijvoorbeeld https://app.contoso.com. De SDK gebruikt deze om binnenkomende postMessage gebeurtenissen te valideren.

Afmelden handmatig toevoegen

Aanroepen client.auth.signOut() om de sessie te beëindigen en tokens in de cache te wissen:

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

Abonneer u op sessiewijzigingen om uw gebruikersinterface bij te werken wanneer aanmelden of afmelden is voltooid:

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

Genereer aanmeld- en registratiepagina's met GitHub Copilot

Als u GitHub Copilot in VS Code gebruikt, open dan Copilot Chat in uw Fabric Apps-project en gebruik aanwijzingen zoals de volgende om de authenticatiecode te genereren. Copilot volgt de patronen in de Rayfin-skill die wordt meegeleverd met de Fabric VS Code-extensie.

Doel	Voorbeeld van Copilot-prompt
Een aanmeldingsknop toevoegen	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.
Een afmeldingsknop toevoegen	Add a Sign out button that calls client.auth.signOut() and updates the UI when the session ends.
Een verificatiebewuste React-hook toevoegen	Create a useFabricAuth React hook that exposes session, signIn, signOut, and isAuthenticated, using ensureSignedInWithFabric and client.auth.onSessionChange.
Ondersteuning voor ingesloten modus	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.
Een route beveiligen	Wrap the /dashboard route so it calls ensureSignedInWithFabric before rendering and redirects unauthenticated users to a sign-in page.

Nadat Copilot code heeft gegenereerd, controleert u de wijzigingen en zorgt u ervoor dat:

• De ensureSignedInWithFabric() aanroep wordt uitgevoerd in een handler voor gebruikersbewegingen (bijvoorbeeld onClick), niet bij het laden van de pagina.
• returnOrigin is een lege oorsprong en komt overeen met een van de vermeldingen in allowedRedirectUrisrayfin/rayfin.yml.
• De invoer komt van @microsoft/rayfin-auth-provider-fabric (niet de afgeschafte callback-helpers).

Ingesloten modus gebruiken in een Fabric iframe

Wanneer uw app in een Fabric iframe wordt geladen (bijvoorbeeld wanneer een gebruiker deze opent vanuit de Fabric-portal), gebruikt u de ingesloten modus in plaats van de pop-upstroom:

• Ingesloten modus haalt de sessie via postMessage op uit het bovenliggende frame.
• Er wordt geen pop-up geopend en er is geen gebruikersinteractie vereist, dus het is veilig om dit aan te roepen wanneer de pagina wordt geladen.
• De SDK detecteert de ingesloten modus automatisch aan de hand van ?fabricEmbedded=true in de URL. U kunt dit ook afdwingen door in de opties fabricEmbedded: true in te stellen.

Roep initEmbeddedAuth() vroeg aan bij het opstarten van de app:

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() geeft null terug wanneer de app niet in ingesloten modus wordt uitgevoerd, dus het is veilig om deze onvoorwaardelijk aan te roepen. ensureSignedInWithFabric() probeert ook automatisch eerst de ingesloten modus, voordat wordt teruggevallen op de pop-upflow.

Fabric-verificatie gebruiken in React

Maak een aangepaste hook die aanmelding, registratie en afmelding integreert:

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

Gebruik de haak in uw onderdelen:

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-referentie

ensureSignedInWithFabric

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

Implementeert een waterval voor verificatie in vier stappen:

1. Retourneert de bestaande sessie als deze al is geverifieerd.
2. Probeert een stille vernieuwing via het vernieuwingstoken.
3. Ingebedde modus—als deze binnen een Fabric-iframe wordt uitgevoerd, wordt de sessie via postMessage van het bovenliggende frame opgehaald.
4. Opent de Fabric-portal in een pop-up (pop-upproces) en wacht op de postMessage overdracht.

Stap 1 tot en met 3 kunnen veilig worden aangeroepen wanneer de pagina wordt geladen. Stap 4 opent een pop-up en moet worden uitgevoerd in een handler voor gebruikersbewegingen.

FabricAuthOptions

Property	Type	Description
workspaceId	string	De Fabric werkruimte-id.
projectId	string	Het item-id van de Fabric-app.
fabricPortalUrl	string	De basis-URL van de Fabric-portal (bijvoorbeeld https://app.fabric.microsoft.com).
returnOrigin	string	De oorsprong van uw app voor postMessage levering (bijvoorbeeld window.location.origin). Moet een lege oorsprong zijn (schema en host, geen pad).
fabricEmbedded	boolean (optioneel)	Forceer de ingesloten modus. Automatisch afgeleid uit ?fabricEmbedded=true in de URL.

Ondersteunende functies

Functie	Description
initEmbeddedAuth(auth, options)	Ingesloten verificatie die veilig is tijdens het laden van de pagina. Retourneert de sessie wanneer deze binnen een Fabric-iframe wordt uitgevoerd, en anders null.
initiateFabricLogin(auth, options)	Pop-upstroom op laag niveau. Opent de Fabric-portal in een pop-up met PKCE-parameters en wacht op de postMessage overdracht.
isEmbeddedMode(options)	Retourneert true als de app wordt uitgevoerd in de ingesloten modus (Fabric iframe).

Beveiligingsfuncties

• PKCE S256 : elke stroom genereert een cryptografische codeverificator en uitdaging om het onderscheppen van autorisatiecode te voorkomen.
• Status nonce : een willekeurige nonce koppelt het handoff-antwoord aan het oorspronkelijke tabblad, waardoor vervalsing van aanvragen tussen sites wordt voorkomen.
• postMessage origin-validatie : de SDK valideert event.origin in binnenkomende berichten en weigert berichten van onverwachte oorsprongen.
• Automatische opschoning – de PKCE-status verloopt na 5 minuten en wordt tijdens de volgende flow opgeruimd.
• Flow-time-out – De pop-upflow verloopt na 5 minuten als er geen handoff-bericht wordt ontvangen.

Verificatieproblemen oplossen

Pop-up geblokkeerd

Het venster van de Fabric portal is geblokkeerd in de browser. Zorg ervoor dat ensureSignedInWithFabric() wordt aangeroepen vanuit een synchrone handler voor een gebruikersactie (bijvoorbeeld de knop onClick). Roep deze niet aan bij het laden van pagina's of in een asynchrone keten voordat de gebruiker interactie heeft.

Sessie blijft niet behouden

Controleer of de RayfinClient configuratie is geconfigureerd met de juiste baseUrl en publishableKey. Het tabblad voor callbacks en het oorspronkelijke tabblad moeten dezelfde oorsprong delen om BroadcastChannel en localStorage te laten werken.

Verificatie mislukt na een lange vertraging

De aanmeldingsstroom verloopt na 5 minuten. Als u het aanmeldingsproces start, maar het niet binnen die tijd voltooit, mislukt het proces. Sluit het pop-upvenster en selecteer de aanmeldingsknop opnieuw om een nieuwe stroom te starten.

Verwante inhoud

• Verificatie configureren
• Implementeren naar Fabric
• Gegevensmodellen definiëren