Konfigurer Fabric SSO-autentificering til din Fabric-app

Opsæt Fabric single sign-on (SSO) til en Fabric-app, så brugere kan logge ind med Microsoft Entra ID via Fabric-portalen. Denne artikel forklarer handoff-flowet og viser, hvordan man aktiverer den nødvendige konfiguration og SDK-integration for deployerede apps.

Forudsætninger

• Et Fabric Apps-projekt med autentificering aktiveret. Se Konfigurér autentificering.
• Et deployeret Fabric Apps-element. Se Deploy to Fabric.

Hvordan Fabric SSO fungerer

Fabric single sign-on (SSO) bruger en sikker postMessage-baseret overførsel mellem din applikation og Fabric-portalen. Der er ingen omdirigerings- eller callback-side:

1. Din app åbner Fabric-portalen i en popup og registrerer en postMessage-lytter.
2. Brugeren autentificerer sig via Microsoft Entra ID inde i Fabric-portalen.
3. Den Fabric udvidelse sender overdragelseskoden tilbage til din app via window.opener.postMessage().
4. SDK'en udveksler handoff-koden for Rayfin-sessionstokens og opretter en session.
5. Fabric-popupen lukker automatisk.

Flowet sikres med PKCE (Proof Key for Code Exchange), state nonces og postMessage oprindelsesvalidering for at forhindre aflytning af autorisationskoder og forfalskning af cross-site anmodninger.

Aktivér Fabric-autentificering

Tilføj Fabric autentificeringskonfigurationen til din rayfin/rayfin.yml-fil:

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

For deployerede applikationer, redeploy for at flytte de opdaterede indstillinger:

npx rayfin up

For deployerede apps tilføjer npx rayfin up din deployed app callback-URL til .allowedRedirectUris

Installer Fabric-autentificeringsudbyderen (valgfrit)

Projekter, der er stilladseret med npm create @microsoft/rayfin@latest , inkluderer @microsoft/rayfin-auth-provider-fabricallerede . Installer det manuelt kun hvis du tilføjer Fabric-autentificering til et projekt, der ikke allerede har pakken:

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

Tilføj login-ind og tilmelding til din app

Fabric SSO bruger et enkelt API til både ind- og tilmelding: ensureSignedInWithFabric(). Når en bruger logger ind for første gang, opretter Fabric automatisk en Rayfin-session for dem baseret på deres Microsoft Entra ID-identitet – der er ikke noget separat tilmeldingskald. Den samme kodesti håndterer tilbagevendende brugere.

Du kan tilføje denne kode manuelt eller generere den med GitHub Copilot i VS Code.

Tilføj login-ind manuelt

Kald ensureSignedInWithFabric() fra en bruger-gestushandler (for eksempel et knapvalg):

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 skal kaldes fra en synkron bruger-gestushandler for at undgå popup-blokkere. At kalde det ved sideindlæsning eller i en asynkron kæde før brugerinteraktion udløser browser-popup-beskyttelse.

returnOrigin skal være en nøgen oprindelse (skema og vært, ingen sti)—for eksempel https://app.contoso.com. SDK'en bruger det til at validere indkommende postMessage begivenheder.

Tilføj udlogging manuelt

Kald client.auth.signOut() for at afslutte sessionen og rydde cachede tokens:

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

Abonner på sessionsændringer for at opdatere dit brugerinterface, når login eller udlogging er færdig:

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

Generer login-ind og tilmelding med GitHub Copilot

Hvis du bruger GitHub Copilot i VS Code, så åbn Copilot Chat i dit Fabric Apps-projekt og brug prompts som disse til at støtte autentificeringskoden. Copilot følger mønstrene i Rayfin-færdigheden, som følger med Fabric VS Code-udvidelsen.

Efter Copilot har genereret koden, gennemgå redigeringerne og sørg for:

• Kaldet ensureSignedInWithFabric() kører inde i en bruger-gestushandler (for eksempel, onClick)—ikke under sideindlæsning.
• returnOriginer en nøgen oprindelse og matcher et af posterne i allowedRedirectUris .rayfin/rayfin.yml
• Importerne kommer fra @microsoft/rayfin-auth-provider-fabric (ikke de forældede callback-hjælpere).

Brug embedded mode inde i en Fabric iframe

Når din app indlæses i en Fabric-iframe (for eksempel når en bruger åbner den fra Fabric-portalen), brug embedded mode i stedet for popup-flowet:

• Indlejret tilstand opsamler sessionen til postMessage den overordnede ramme.
• Den åbner ikke en popup og kræver ikke en brugergestus, så det er sikkert at kalde ved sideindlæsning.
• SDK'en registrerer automatisk indlejret tilstand fra ?fabricEmbedded=true URL'en. Du kan også tvinge det ved at sætte fabricEmbedded: true indstillingerne ind.

Ring initEmbeddedAuth() tidligt i app-opstart:

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 kører i indlejret tilstand, så det er sikkert at kalde ubetinget. ensureSignedInWithFabric() Forsøger også automatisk indlejret tilstand, før den falder tilbage til popup-flowet.

Brug Fabric-autentificering i React

Opret en brugerdefineret hook, der integrerer login, tilmelding og udskrivning:

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

Brug krogen i dine 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-reference

ensureSignedInWithFabric

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

Implementerer et firetrins autentificeringsvandfald:

1. Returnerer den eksisterende session, hvis den allerede er autentificeret.
2. Forsøger en stille opdatering via refresh-tokenet.
3. Indlejret tilstand—hvis den kører inde i en Fabric iframe, modtager sessionen gennem postMessage til forældrerammen.
4. Åbner Fabric-portalen i en popup (popup-flow) og venter på postMessage overdragelsen.

Trin 1 til 3 er sikre at kalde ved sideindlæsning. Trin 4 åbner en popup og skal køre inde i en bruger-gestus-handler.

FabricAuthOptions

Hjælper-funktioner

Sikkerhedsfunktioner

• PKCE S256 – Hver flow genererer en kryptografisk kode-verifikator og udfordrer for at forhindre opsnapning af autorisationskoder.
• Tilstands-nonce – En tilfældig nonce knytter handoff-svaret til den oprindelige fane og forhindrer forfalskning af cross-site anmodninger.
• postMessage oprindelsesvalidering – SDK'en validerer event.origin på indkommende beskeder og afviser beskeder fra uventede oprindelser.
• Automatisk oprydning – PKCE-tilstanden udløber efter 5 minutter og bliver affaldssamlet ved næste strøm.
• Flow-timeout – Popup-flowet går ud efter 5 minutter, hvis der ikke modtages en handoff-besked.

Foretag fejlfinding af godkendelsesproblemer

Popup blokeret

Browseren blokerede Fabric-portalvinduet. Ensure ensureSignedInWithFabric() kaldes fra en synkron bruger-gestushåndtering (for eksempel knap onClick). Kald det ikke ved sideindlæsning eller inde i en asynkron kæde før brugerinteraktion.

Sessionen består ikke

Bekræft at er RayfinClient konfigureret med de korrekte baseUrl og publishableKey. Callback-fanen og den oprindelige fane skal have samme oprindelse for BroadcastChannel og localStorage for at fungere.

Autentificeringen fejler efter lang forsinkelse

Login-flowet udløber efter 5 minutter. Hvis du starter login-processen, men ikke gennemfører den inden for den tid, fejler flowet. Luk popup-vinduet og vælg login-knappen igen for at starte et nyt flow.

Relateret indhold

• Konfigurer godkendelse
• Udrul til Fabric
• Definér datamodeller