Konfigurer Fabric SSO-autentisering for Fabric-appen din

Sett opp Fabric single sign-on (SSO) for en Fabric-app slik at brukere kan logge inn med Microsoft Entra ID via Fabric-portalen. Denne artikkelen forklarer overleveringsflyten og viser hvordan man aktiverer nødvendig konfigurasjon og SDK-integrasjon for distribuerte apper.

Forutsetninger

Et Fabric Apps-prosjekt med autentisering aktivert. Se Konfigurer autentisering.
Et distribuert Fabric Apps-element. Se Deploy to Fabric.

Hvordan Fabric SSO fungerer

Fabric single sign-on (SSO) bruker en sikker postMessage-basert overlevering mellom applikasjonen din og Fabric-portalen. Det finnes ingen omdirigering eller tilbakekallingsside:

Appen din åpner Fabric-portalen i en popup og registrerer en postMessage-lytter.
Brukeren autentiserer seg via Microsoft Entra ID inne i Fabric-portalen.
Fabric-utvidelsen sender overleveringskoden tilbake til appen din via window.opener.postMessage().
SDK-en bytter overleveringskoden for Rayfin-sesjonstokene og oppretter en økt.
Fabric-popupen lukkes automatisk.

Flyten sikres med PKCE (Proof Key for Code Exchange), state nonces og postMessage opprinnelsesvalidering for å forhindre avskjæring av autorisasjonskoder og forfalskning av forespørsler på tvers av steder.

Aktiver Fabric-autentisering

Legg til Fabric-autentiseringskonfigurasjonen i din rayfin/rayfin.yml-fil:

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

For deployerte applikasjoner, redeploy for å pushe de oppdaterte innstillingene:

npx rayfin up

For distribuerte apper npx rayfin up legger den til din distribuerte app-callback-URL til .allowedRedirectUris

Installer Fabric-autentiseringsleverandøren (valgfritt)

Prosjekter stillas med npm create @microsoft/rayfin@latest inkluderer @microsoft/rayfin-auth-provider-fabricallerede . Installer det manuelt kun hvis du legger til Fabric-autentisering i et prosjekt som ikke allerede har pakken:

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

Fabric SSO bruker ett enkelt API for både innlogging og påmelding: ensureSignedInWithFabric(). Når en bruker logger inn for første gang, oppretter Fabric automatisk en Rayfin-økt for dem basert på deres Microsoft Entra ID-identitet – det er ingen separat påmeldingssamtale. Den samme kodestien håndterer tilbakevendende brukere.

Du kan legge til denne koden for hånd eller generere den med GitHub Copilot i VS Code.

Kall ensureSignedInWithFabric() fra en bruker-gesthåndtering (for eksempel et knappevalg):

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

Funksjonen må kalles fra en synkron bruker-gesthåndtering for å unngå popup-blokkere. Å kalle det under sidelasting eller inne i en asynkron kjede før brukerinteraksjon utløser nettleser-popup-beskyttelse.

returnOrigin må være en naken opprinnelse (skjema og vert, ingen sti)—for eksempel, https://app.contoso.com. SDK-en bruker den til å validere innkommende postMessage hendelser.

Legg til utlogging manuelt

Kall client.auth.signOut() for å avslutte økten og slette bufrede tokens:

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

Abonner på øktendringer for å oppdatere brukergrensesnittet ditt når inn- eller utlogging er fullført:

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

Hvis du bruker GitHub Copilot i VS Code, åpne Copilot Chat i Fabric Apps-prosjektet ditt og bruk slike prompts for å støtte autentiseringskoden. Copilot følger mønstrene i Rayfin-ferdigheten som følger med Fabric VS Code-utvidelsen.

Mål	Eksempel på Copilot-spørsmål
Legg til en påloggingsknapp	`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.`
Legg til en utloggingsknapp	`Add a Sign out button that calls client.auth.signOut() and updates the UI when the session ends.`
Legg til en autentiseringsbevisst React-hook	`Create a useFabricAuth React hook that exposes session, signIn, signOut, and isAuthenticated, using ensureSignedInWithFabric and client.auth.onSessionChange.`
Støtte innebygd 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.`
Gate en rute	`Wrap the /dashboard route so it calls ensureSignedInWithFabric before rendering and redirects unauthenticated users to a sign-in page.`

Etter at Copilot har generert kode, gjennomgå endringene og sørg for:

Kallet ensureSignedInWithFabric() kjører inne i en bruker-gesthåndtering (for eksempel onClick)—ikke ved sidelasting.
returnOriginer en naken opprinnelse og samsvarer med ett av oppføringene i allowedRedirectUris i .rayfin/rayfin.yml
Importene kommer fra @microsoft/rayfin-auth-provider-fabric (ikke de foreldede callback-hjelperne).

Bruk innebygd modus inne i en Fabric iframe

Når appen din laster inn i en Fabric iframe (for eksempel når en bruker åpner den fra Fabric-portalen), bruk innebygd modus i stedet for popup-flyten:

Innebygd modus henter sesjonen gjennom postMessage til foreldrerammen.
Den åpner ikke en popup og krever ikke brukerbevegelse, så det er trygt å kalle på sideinnlasting.
SDK-en oppdager automatisk innebygd modus fra ?fabricEmbedded=true URL-en. Du kan også tvinge det ved å sette fabricEmbedded: true innstillingene.

Ring initEmbeddedAuth() tidlig i app-oppstart:

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() Returnerer null når appen ikke kjører i innebygd modus, så det er trygt å kalle ubetinget. ensureSignedInWithFabric() Prøver også automatisk innebygd modus før den faller tilbake til popup-flyten.

Bruk Fabric-autentisering i React

Lag en tilpasset krok som integrerer pålogging, påmelding og utlogging:

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

Bruk kroken i komponentene dine:

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

ensureSignedInWithFabric

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

Implementerer et firetrinns autentiseringsfossefall:

Returnerer den eksisterende sesjonen hvis den allerede er autentisert.
Forsøker en stille oppdatering via oppdateringstokenet.
Innebygd modus—hvis den kjøres inne i en Fabric iframe, henter sesjonen gjennom postMessage til foreldrerammen.
Åpner Fabric-portalen i en popup (popup-flyt) og venter på postMessage overlevering.

Trinn 1 til 3 er trygge å kalle ved sideinnlasting. Trinn 4 åpner en popup og må kjøres inne i en bruker-gesthåndtering.

FabricAuthOptions

Eiendom	Type:	Beskrivelse
`workspaceId`	`string`	Fabric arbeidsområdets ID.
`projectId`	`string`	Fabric-appens vare-ID.
`fabricPortalUrl`	`string`	Den Fabric portalbaserte URL-en (for eksempel `https://app.fabric.microsoft.com`).
`returnOrigin`	`string`	Appens opprinnelse for `postMessage` levering (for eksempel, `window.location.origin`). Må være en naken opprinnelse (skjema og vert, ingen sti).
`fabricEmbedded`	`boolean` (valgfritt)	Tving innebygd modus. Automatisk oppdaget fra `?fabricEmbedded=true` URL-en.

Hjelper-funksjoner

Funksjonen	Beskrivelse
`initEmbeddedAuth(auth, options)`	Sideinnlastingssikker innebygd autentisering. Returnerer sesjonen hvis den kjører inne i en Fabric iframe, eller `null` ellers.
`initiateFabricLogin(auth, options)`	Lavnivå popup-flyt. Åpner Fabric-portalen i en popup med PKCE-parametere og lytter etter `postMessage` overlevering.
`isEmbeddedMode(options)`	Returnerer `true` hvis appen kjører i innebygd modus (Fabric iframe).

Sikkerhetsfunksjoner

PKCE S256 – Hver flyt genererer en kryptografisk kodeverifikator og utfordring for å forhindre avskjæring av autorisasjonskode.
State nonce – En tilfeldig nonce knytter handoff-svaret til den opprinnelige fanen, og forhindrer forfalskning av forespørsler på tvers av steder.
postMessage Opprinnelsesvalidering – SDK-en validerer event.origin innkommende meldinger og avviser meldinger fra uventede opprinnelser.
Automatisk opprydding – PKCE-tilstanden utløper etter 5 minutter og samles søppel ved neste flyt.
Flow-timeout – Popup-flyten går ut etter 5 minutter hvis ingen overleveringsmelding mottas.

Feilsøke godkjenningsproblemer

Nettleseren blokkerte Fabric-portalvinduet. Ensure ensureSignedInWithFabric() kalles fra en synkron bruker-gesthåndtering (for eksempel knapp onClick). Ikke kall det på sidelasting eller inne i en asynkron kjede før brukerinteraksjon.

Økt som ikke vedvarer

Bekreft at er RayfinClient konfigurert med riktig baseUrl og publishableKey. Callback-fanen og den opprinnelige fanen må ha samme opprinnelse for BroadcastChannel og localStorage for å fungere.

Autentisering feiler etter lang forsinkelse

Innloggingsflyten utløper etter 5 minutter. Hvis du starter innloggingsprosessen, men ikke fullfører den innen den tiden, feiler flyten. Lukk popup-vinduet og velg innloggingsknappen igjen for å starte en ny flyt.

Tilbakemeldinger

Var denne siden nyttig?

Last updated on 2026-06-02