Konfigurera Fabric SSO-autentisering för din Fabric-app

Konfigurera Fabric enkel inloggning (SSO) för en Fabric-app så att användarna kan logga in med Microsoft Entra ID via Fabric-portalen. Den här artikeln förklarar överlämningsflödet och visar hur du aktiverar den konfiguration och SDK-integrering som krävs för distribuerade appar.

Förutsättningar

Ett Fabric Apps-projekt med autentisering aktiverat. Se Konfigurera autentisering.
Ett distribuerat Fabric Apps-objekt. Se Distribuera till Fabric.

Så här fungerar Fabric SSO

Fabric enkel inloggning (SSO) använder en säker postMessage-baserad överlämning mellan ditt program och Fabric-portalen. Det finns ingen omdirigerings- eller motringningssida:

Appen öppnar Fabric-portalen i ett popup-fönster och registrerar en postMessage lyssnare.
Användaren autentiserar via Microsoft Entra ID i Fabric portalen.
Tillägget Fabric skickar tillbaka överlämningskoden till din app via window.opener.postMessage().
SDK:t utbyter överlämningskoden för Rayfin-sessionstoken och skapar en session.
Fabric-popupfönstret stängs automatiskt.

Flödet skyddas med PKCE (Proof Key for Code Exchange), state-nonser och postMessage ursprungsvalidering för att förhindra avlyssning av auktoriseringskoder och förfalskning av förfrågningar mellan webbplatser.

Aktivera Fabric-autentisering

Lägg till konfigurationen för Fabric-autentisering i filen rayfin/rayfin.yml:

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

För distribuerade applikationer distribuerar du om dem för att skicka ut de uppdaterade inställningarna:

npx rayfin up

För distribuerade appar lägger npx rayfin up till URL:en för återanrop för den distribuerade appen i allowedRedirectUris.

Installera Fabric-autentiseringsprovidern (valfritt)

Projekt som skapats med npm create @microsoft/rayfin@latest innehåller redan @microsoft/rayfin-auth-provider-fabric. Installera den endast manuellt om du lägger till Fabric autentisering i ett projekt som inte redan har paketet:

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

Fabric SSO använder ett enda API för både inloggning och registrering: ensureSignedInWithFabric(). När en användare loggar in för första gången etablerar Fabric en Rayfin-session för dem automatiskt baserat på deras Microsoft Entra ID identitet – det finns inget separat registreringssamtal. Samma kodväg hanterar även användare som återkommer.

Du kan lägga till den här koden för hand eller generera den med GitHub Copilot i VS Code.

Anropa ensureSignedInWithFabric() i en hanterare för användargest (till exempel när en knapp väljs):

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

Funktionen måste anropas från en synkron användargesthanterare för att undvika popup-blockerare. Om du anropar det när sidan läses in eller i en asynkron anropskedja innan användaren interagerar utlöses webbläsarens popupskydd.

returnOrigin måste vara ett tomt ursprung (schema och värd, ingen sökväg)– till exempel https://app.contoso.com. SDK använder det för att verifiera inkommande postMessage händelser.

Lägga till utloggning manuellt

Anropa client.auth.signOut() för att avsluta sessionen och rensa cachelagrade token:

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

Prenumerera på sessionsändringar för att uppdatera användargränssnittet när inloggningen eller utloggning slutförs:

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

Om du använder GitHub Copilot i VS Code öppnar du Copilot Chat i projektet Fabric Apps och använder sådana här uppmaningar för att skapa autentiseringskoden. Copilot följer mönstren i Rayfin-skillen som medföljer VS Code-tillägget Fabric.

Mål	Exempel på Copilot-uppmaning
Lägg till en inloggningsknapp	`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.`
Lägg till en utloggningsknapp	`Add a Sign out button that calls client.auth.signOut() and updates the UI when the session ends.`
Lägga till en autentiseringsmedveten React-krok	`Create a useFabricAuth React hook that exposes session, signIn, signOut, and isAuthenticated, using ensureSignedInWithFabric and client.auth.onSessionChange.`
Stöd för inbäddat läge	`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.`
Begränsa åtkomst till en rutt	`Wrap the /dashboard route so it calls ensureSignedInWithFabric before rendering and redirects unauthenticated users to a sign-in page.`

När Copilot genererar kod granskar du redigeringarna och kontrollerar att:

Anropet ensureSignedInWithFabric() körs i en användargesthanterare (till exempel onClick)– inte vid sidinläsning.
returnOrigin är ett tomt ursprung och matchar en av posterna i i allowedRedirectUrisrayfin/rayfin.yml.
Importerna kommer från @microsoft/rayfin-auth-provider-fabric (inte de föråldrade hjälpfunktionerna för återanrop).

Använda inbäddat läge i en Fabric iframe

När appen läses in i en Fabric iframe (till exempel när en användare öppnar den från Fabric-portalen) använder du inbäddat läge i stället för popup-flödet:

Inbäddat läge hämtar sessionen via postMessage från den överordnade ramen.
Det öppnar inte ett popup-fönster och kräver ingen användargest, så det är säkert att anropa vid sidinläsning.
SDK identifierar automatiskt inbäddat läge från ?fabricEmbedded=true i URL:en. Du kan också tvinga fram det genom att ange fabricEmbedded: true i alternativen.

Anropa initEmbeddedAuth() tidigt när appen startar:

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() returnerar null när appen inte körs i inbäddat läge, så det är säkert att anropa villkorslöst. ensureSignedInWithFabric() försöker också automatiskt använda inbäddat läge innan det går över till popupflödet.

Använda Fabric-autentisering i React

Skapa en anpassad krok som integrerar inloggning, registrering och utloggning:

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

Använd kroken i dina komponenter:

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

ensureSignedInWithFabric

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

Implementerar ett vattenfall med fyra stegs autentisering:

Returnerar den befintliga sessionen om den redan har autentiserats.
Försöker utföra en tyst uppdatering via uppdateringstoken.
Inbäddat läge – om det körs i en Fabric-iframe hämtas sessionen via postMessage från den överordnade ramen.
Öppnar Fabric-portalen i ett popupfönster (popupflöde) och väntar på postMessage-överlämningen.

Steg 1 till och med 3 är säkra att anropa vid sidinläsning. Steg 4 öppnar ett popup-fönster och måste köras i en användargesthanterare.

FabricAuthOptions

Property	Type	Description
`workspaceId`	`string`	ID:t för Fabric arbetsyta.
`projectId`	`string`	ID:t för Fabric appobjekt.
`fabricPortalUrl`	`string`	Fabric-portalens bas-URL (till exempel `https://app.fabric.microsoft.com`).
`returnOrigin`	`string`	Appens ursprungsserver för `postMessage`-leveransen (till exempel `window.location.origin`). Måste vara ett rent ursprung (protokoll och värdnamn, ingen sökväg).
`fabricEmbedded`	`boolean` (valfritt)	Framtvinga inbäddat läge. Identifieras automatiskt från `?fabricEmbedded=true` i URL:en.

Hjälpfunktioner

Function	Description
`initEmbeddedAuth(auth, options)`	Sidladdningssäker inbäddad autentisering. Returnerar sessionen om den körs inuti en iframe i Fabric, eller `null` annars.
`initiateFabricLogin(auth, options)`	Popup-flöde på låg nivå. Öppnar Fabric-portalen i ett popupfönster med PKCE-parametrar och väntar på överlämningen `postMessage`.
`isEmbeddedMode(options)`	Returnerar `true` om appen körs i inbäddat läge (Fabric iframe).

Säkerhetsfunktioner

PKCE S256 – Varje flöde genererar en kryptografisk kodverifierare och utmaning för att förhindra avlyssning av auktoriseringskod.
State-nonce – En slumpmässig nonce kopplar handoff-svaret till den ursprungliga fliken, vilket förhindrar begärandeförfalskning mellan webbplatser.
postMessage ursprungsvalidering – SDK:et validerar event.origin inkommande meddelanden och avvisar meddelanden från oväntat ursprung.
Automatisk rensning – PKCE-tillståndet upphör att gälla efter 5 minuter och rensas bort vid nästa flöde.
Tidsgräns för flöde – Tidsgränsen för popup-flödet uppnås efter 5 minuter om inget meddelande tas emot.

Felsöka autentiseringsproblem

Webbläsaren blockerade Fabric portalfönstret. Kontrollera att ensureSignedInWithFabric() anropas från en synkron användargesthanterare (till exempel knappen onClick). Anropa det inte vid sidinläsning eller i en asynkron kedja innan användaren interagerar.

Sessionen sparas inte

Bekräfta att RayfinClient har konfigurerats med rätt baseUrl och publishableKey. Återanropsfliken och den ursprungliga fliken måste ha samma ursprung för att BroadcastChannel och localStorage ska fungera.

Autentiseringen misslyckas efter en lång fördröjning

Inloggningsflödet upphör att gälla efter 5 minuter. Om du startar inloggningsprocessen men inte slutför den inom den tiden misslyckas flödet. Stäng popup-fönstret och välj inloggningsknappen igen för att starta ett nytt flöde.

Feedback

Var den här sidan till hjälp?

Last updated on 2026-06-02