Konfigurieren Fabric SSO-Authentifizierung für Ihre Fabric-App

Richten Sie Single Sign-On (SSO) für eine Fabric-App ein, damit sich Benutzer über das Fabric-Portal mit Microsoft Entra ID anmelden können. In diesem Artikel wird der Übergabefluss erläutert und erläutert, wie Sie die erforderliche Konfiguration und SDK-Integration für bereitgestellte Apps aktivieren.

Voraussetzungen

Funktionsweise von Fabric SSO

Fabric-Single Sign-On (SSO) verwendet eine sichere postMessage-basierte Weiterleitung zwischen Ihrer Anwendung und dem Fabric-Portal. Es gibt keine Umleitungs- oder Rückrufseite:

  1. Ihre App öffnet das Fabric-Portal in einem Pop-up und registriert einen postMessage-Listener.
  2. Der Benutzer authentifiziert sich über Microsoft Entra ID im Fabric-Portal.
  3. Die Fabric-Erweiterung sendet den Handoffcode über window.opener.postMessage() an Ihre App zurück.
  4. Das SDK wechselt den Übergabecode für Rayfin-Sitzungstoken und erstellt eine Sitzung.
  5. Das Fabric-Pop-up schließt sich automatisch.

Der Ablauf wird mit PKCE (Proof Key for Code Exchange), State-Nonces und postMessage Origin-Validierung abgesichert, um das Abfangen von Autorisierungscodes und siteübergreifende Anfragenfälschung zu verhindern.

Fabric Authentifizierung aktivieren

Fügen Sie der Datei rayfin/rayfin.yml die Fabric-Authentifizierungskonfiguration hinzu:

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

Für bereitgestellte Anwendungen erneut bereitstellen, um die aktualisierten Einstellungen zu übernehmen:

npx rayfin up

Für bereitgestellte Apps fügt npx rayfin up die Rückruf-URL Ihrer bereitgestellten App zu allowedRedirectUris hinzu.

Installieren des Fabric Authentifizierungsanbieters (optional)

Projekte, die mit npm create @microsoft/rayfin@latest erstellt wurden, enthalten bereits @microsoft/rayfin-auth-provider-fabric. Installieren Sie sie manuell nur, wenn Sie Fabric Authentifizierung zu einem Projekt hinzufügen, das noch nicht über das Paket verfügt:

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

Hinzufügen der Anmeldung und Registrierung für Ihre App

Fabric SSO verwendet eine einzelne API sowohl für die Anmeldung als auch für die Registrierung: ensureSignedInWithFabric(). Wenn sich ein Benutzer zum ersten Mal anmeldet, stellt Fabric automatisch eine Rayfin-Sitzung für sie basierend auf ihrer Microsoft Entra ID Identität fest – es gibt keinen separaten Anmeldeanruf. Derselbe Codepfad wird auch für wiederkehrende Benutzer verwendet.

Sie können diesen Code manuell hinzufügen oder mit GitHub Copilot in VS Code generieren.

Manuelles Hinzufügen der Anmeldung

Rufen Sie ensureSignedInWithFabric() in einem Handler für Benutzergesten auf (z. B. bei der Auswahl einer Schaltfläche):

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

Die Funktion muss von einem synchronen Benutzergestenhandler aufgerufen werden, um Popupblocker zu vermeiden. Wird dies beim Laden der Seite oder in einer asynchronen Kette vor der Benutzerinteraktion aufgerufen, wird der Popup-Schutz des Browsers ausgelöst.

returnOrigin muss ein reiner Ursprung sein (nur Schema und Host, ohne Pfad) – zum Beispiel https://app.contoso.com. Das SDK verwendet es zum Überprüfen eingehender postMessage Ereignisse.

Abmelden manuell hinzufügen

Aufrufen client.auth.signOut() zum Beenden der Sitzung und Löschen zwischengespeicherter Token:

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

Abonnieren Sie Sitzungsänderungen, um Ihre Benutzeroberfläche zu aktualisieren, wenn die Anmeldung abgeschlossen ist oder die Abmeldung abgeschlossen ist:

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

Anmeldung und Registrierung mit GitHub Copilot erstellen

Wenn Sie GitHub Copilot in VS Code verwenden, öffnen Sie Copilot Chat in Ihrem Fabric Apps-Projekt, und verwenden Sie Eingabeaufforderungen wie diese, um den Authentifizierungscode zu erstellen. Copilot folgt den Mustern in der Rayfin-Fähigkeit, die mit der Fabric VS Code Erweiterung gebündelt ist.

Zielsetzung Beispiel Copilot-Prompt
Hinzufügen einer Anmeldeschaltfläche 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.
Schaltfläche "Abmelden hinzufügen" Add a Sign out button that calls client.auth.signOut() and updates the UI when the session ends.
Hinzufügen eines Authentifizierungsfähigen React-Hooks Create a useFabricAuth React hook that exposes session, signIn, signOut, and isAuthenticated, using ensureSignedInWithFabric and client.auth.onSessionChange.
Unterstützen des eingebetteten 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.
Eine Route sperren Wrap the /dashboard route so it calls ensureSignedInWithFabric before rendering and redirects unauthenticated users to a sign-in page.

Nachdem Copilot Code generiert hat, überprüfen Sie die Bearbeitungen, und stellen Sie folgendes sicher:

  • Der ensureSignedInWithFabric()-Aufruf wird innerhalb eines Handlers für Benutzergesten ausgeführt (zum Beispiel onClick) – nicht beim Laden der Seite.
  • returnOrigin ist ein reiner Ursprung und entspricht einem der Einträge in allowedRedirectUris in rayfin/rayfin.yml.
  • Importe stammen aus @microsoft/rayfin-auth-provider-fabric (nicht die veralteten Rückrufhilfen).

Einbettungsmodus innerhalb eines Fabric-IFrames verwenden

Wenn Ihre App in einem Fabric iframe geladen wird (z. B. wenn ein Benutzer sie über das Fabric Portal öffnet), verwenden Sie den eingebetteten Modus anstelle des Popupflusses:

  • Der eingebettete Modus übernimmt die Sitzung bis postMessage zum übergeordneten Frame.
  • Es öffnet kein Pop-up und erfordert keine Nutzerinteraktion, daher kann es beim Laden der Seite bedenkenlos aufgerufen werden.
  • Das SDK erkennt den eingebetteten Modus automatisch aus ?fabricEmbedded=true der URL. Sie können sie auch erzwingen, indem Sie sie in den Optionen festlegen fabricEmbedded: true .

Frühzeitiger Anruf initEmbeddedAuth() beim Starten der 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() gibt null zurück, wenn die App nicht im eingebetteten Modus ausgeführt wird, daher kann sie bedenkenlos immer aufgerufen werden. ensureSignedInWithFabric() versucht außerdem automatisch, den eingebetteten Modus zu verwenden, bevor auf den Popup-Ablauf zurückgegriffen wird.

Fabric-Authentifizierung in React verwenden

Erstellen Sie einen benutzerdefinierten Hook, der Die Anmeldung, Registrierung und Abmeldung integriert:

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

Verwenden Sie den Hook in Ihren Komponenten:

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

ensureSignedInWithFabric

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

Implementiert einen Wasserfall mit vier Schritten für die Authentifizierung:

  1. Gibt die vorhandene Sitzung zurück, wenn sie bereits authentifiziert wurde.
  2. Versucht eine stille Aktualisierung über das Refresh-Token.
  3. Eingebetteter Modus – wenn die Ausführung innerhalb eines Fabric-IFrames erfolgt, wird die Sitzung über postMessage vom übergeordneten Frame abgerufen.
  4. Öffnet das Fabric-Portal in einem Popup (Popup-Ablauf) und wartet auf die postMessage-Übergabe.

Die Schritte 1 bis 3 können beim Laden der Seite gefahrlos aufgerufen werden. Schritt 4 öffnet ein Popup und muss innerhalb eines Benutzergestenhandlers ausgeführt werden.

FabricAuthOptions

Property Typ Description
workspaceId string Die ID des Fabric-Arbeitsbereichs.
projectId string Die Fabric App-Element-ID.
fabricPortalUrl string Die Fabric Portalbasis-URL (z. B. https://app.fabric.microsoft.com).
returnOrigin string Der Ursprung Ihrer App für die Bereitstellung von postMessage (z. B. window.location.origin). Muss ein barer Ursprung sein (Schema und Host, kein Pfad).
fabricEmbedded boolean (wahlweise) Eingebetteten Modus erzwingen Automatisch aus ?fabricEmbedded=true in der URL erkannt.

Hilfsfunktionen

Funktion Description
initEmbeddedAuth(auth, options) Seitenladesichere eingebettete Authentifizierung. Gibt die Sitzung zurück, wenn sie in einem Fabric iframe ausgeführt wird, oder null andernfalls.
initiateFabricLogin(auth, options) Popupfluss auf niedriger Ebene. Öffnet das Fabric-Portal in einem Popup mit PKCE-Parametern und wartet auf die postMessage Übergabe.
isEmbeddedMode(options) Gibt true zurück, wenn die App im eingebetteten Modus ausgeführt wird (Fabric iframe).

Sicherheitsfeatures

  • PKCE S256 – Jeder Fluss generiert eine Kryptografiecodeüberprüfung und herausforderung, um die Abfangen von Autorisierungscode zu verhindern.
  • State-Nonce – Eine zufällige Nonce verknüpft die Übergabeantwort mit der ursprünglichen Registerkarte und verhindert Cross-Site-Request-Forgery.
  • postMessage Ursprungsüberprüfung – Das SDK überprüft event.origin eingehende Nachrichten und lehnt Nachrichten von unerwarteten Ursprüngen ab.
  • Automatische Bereinigung – der PKCE-Zustand läuft nach 5 Minuten ab und wird beim nächsten Durchlauf bereinigt.
  • Zeitüberschreitung des Ablaufs – Der Popup-Ablauf wird nach 5 Minuten beendet, wenn keine Übergabe-Nachricht empfangen wird.

Behandeln von Authentifizierungsproblemen

Der Browser hat das Fabric Portalfenster blockiert. Stellen Sie sicher, dass ensureSignedInWithFabric() aus einem synchronen Handler für Benutzergesten aufgerufen wird (z. B. Schaltfläche onClick). Rufen Sie sie nicht beim Laden der Seite oder innerhalb einer asynchronen Kette vor der Benutzerinteraktion auf.

Sitzung wird nicht beibehalten

Bestätigen Sie, dass RayfinClient mit der richtigen baseUrl und publishableKey konfiguriert ist. Der Callback-Tab und der ursprüngliche Tab müssen denselben Ursprung haben, damit BroadcastChannel und localStorage funktionieren.

Die Authentifizierung schlägt nach langer Verzögerung fehl.

Der Anmeldeablauf läuft nach 5 Minuten ab. Wenn Sie den Anmeldevorgang starten, ihn aber nicht innerhalb dieses Zeitraums abschließen, schlägt der Ablauf fehl. Schließen Sie das Popup, und wählen Sie erneut die Anmeldeschaltfläche aus, um einen neuen Fluss zu starten.

Verwandte Inhalte

  • Last updated on