Skonfiguruj uwierzytelnianie SSO w aplikacji Fabric

Skonfiguruj logowanie jednokrotne (SSO) Fabric dla aplikacji Fabric, aby użytkownicy mogli logować się przy użyciu Microsoft Entra ID za pośrednictwem portalu Fabric. W tym artykule wyjaśniono przepływ przekazywania i pokazano, jak włączyć wymaganą konfigurację i integrację zestawu SDK dla wdrożonych aplikacji.

Wymagania wstępne

Projekt Fabric Apps z włączonym uwierzytelnianiem. Zobacz Konfigurowanie uwierzytelniania.
Wdrożony element Fabric Apps. Zobacz Wdrażanie do usługi Fabric.

Jak działa funkcja SSO w usłudze Fabric

Logowanie jednokrotne (SSO) w usłudze Fabric wykorzystuje bezpieczny mechanizm przekazywania oparty na postMessage między aplikacją a portalem Fabric. Nie ma strony przekierowania ani strony zwrotnej:

Aplikacja otwiera portal Fabric w oknie podręcznym i rejestruje odbiornik postMessage.
Użytkownik uwierzytelnia się za pośrednictwem Microsoft Entra ID w portalu Fabric.
Rozszerzenie Fabric wysyła kod przekazania z powrotem do Twojej aplikacji za pośrednictwem window.opener.postMessage().
Zestaw SDK wymienia kod przekazywania tokenów sesji Rayfin i tworzy sesję.
Wyskakujące okienko Fabric zostanie automatycznie zamknięte.

Przepływ jest zabezpieczony za pomocą PKCE (Proof Key for Code Exchange), wartości nonce parametru state oraz walidacji pochodzenia postMessage, aby zapobiec przechwyceniu kodu autoryzacyjnego i atakom CSRF (fałszowaniu żądań między witrynami).

Włącz uwierzytelnianie Fabric

Dodaj konfigurację uwierzytelniania Fabric do pliku rayfin/rayfin.yml:

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

W przypadku wdrożonych aplikacji wdróż je ponownie, aby zastosować zaktualizowane ustawienia:

npx rayfin up

W przypadku wdrożonych aplikacji npx rayfin up dodaje adres URL wywołania zwrotnego wdrożonej aplikacji do allowedRedirectUris.

Instalowanie dostawcy uwierzytelniania Fabric (opcjonalnie)

Projekty utworzone przy użyciu npm create @microsoft/rayfin@latest zawierają już @microsoft/rayfin-auth-provider-fabric. Zainstaluj go ręcznie tylko wtedy, jeśli dodajesz uwierzytelnianie Fabric do projektu, który nie ma jeszcze tego pakietu:

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

SSO usługi Fabric korzysta z jednego interfejsu API zarówno do logowania, jak i rejestracji: ensureSignedInWithFabric(). Gdy użytkownik po raz pierwszy się loguje, Fabric automatycznie tworzy dla niego sesję Rayfin na podstawie jego tożsamości Microsoft Entra ID — nie jest wymagane oddzielne wywołanie rejestracji. Ten sam fragment kodu obsługuje powracających użytkowników.

Możesz dodać ten kod ręcznie lub wygenerować go przy użyciu GitHub Copilot w programie VS Code.

Wywołaj ensureSignedInWithFabric() z programu obsługi gestów użytkownika (na przykład wybierz przycisk):

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

Aby uniknąć blokowania wyskakujących okienek, funkcja musi być wywoływana z synchronicznego programu obsługi gestów użytkownika. Wywołanie tego podczas ładowania strony lub w ramach łańcucha operacji asynchronicznych przed interakcją użytkownika powoduje uruchomienie ochrony przeglądarki przed wyskakującymi oknami.

returnOrigin musi być nagim źródłem (schemat i host, bez ścieżki) — na przykład https://app.contoso.com. SDK używa go do weryfikacji przychodzących zdarzeń postMessage.

Dodaj wylogowanie ręcznie

Wywołaj metodę client.auth.signOut() , aby zakończyć sesję i wyczyścić buforowane tokeny:

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

Subskrybowanie zmian sesji w celu zaktualizowania interfejsu użytkownika po zakończeniu logowania lub wylogowania:

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

Jeśli używasz GitHub Copilot w programie VS Code otwórz Copilot Chat w projekcie Fabric Apps i użyj monitów, takich jak te, aby utworzyć szkielet kodu uwierzytelniania. Copilot opiera się na wzorcach z umiejętności Rayfin dołączonej do rozszerzenia Fabric VS Code.

Cel	Przykładowy monit usługi Copilot
Dodawanie przycisku logowania	`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.`
Dodawanie przycisku wylogowywanie	`Add a Sign out button that calls client.auth.signOut() and updates the UI when the session ends.`
Dodaj hook React uwzględniający uwierzytelnianie	`Create a useFabricAuth React hook that exposes session, signIn, signOut, and isAuthenticated, using ensureSignedInWithFabric and client.auth.onSessionChange.`
Obsługa trybu osadzonego	`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.`
Ogranicz dostęp do trasy	`Wrap the /dashboard route so it calls ensureSignedInWithFabric before rendering and redirects unauthenticated users to a sign-in page.`

Gdy Copilot wygeneruje kod, przejrzyj zmiany i upewnij się, że:

Wywołanie ensureSignedInWithFabric() jest uruchamiane wewnątrz programu obsługi gestów użytkownika (na przykład onClick) — nie podczas ładowania strony.
returnOrigin jest samym originem i pasuje do jednego z wpisów w allowedRedirectUris w pliku rayfin/rayfin.yml.
Importy są z @microsoft/rayfin-auth-provider-fabric (nie z wycofanych pomocniczych funkcji callback).

Korzystanie z trybu osadzonego w elemencie iframe platformy Fabric

Gdy aplikacja zostanie załadowana w ramce iframe platformy Fabric (na przykład gdy użytkownik otworzy ją z portalu Fabric), użyj trybu osadzonego zamiast przepływu z wyskakującym oknem:

Tryb osadzony pozyskuje sesję za pośrednictwem postMessage z ramy nadrzędnej.
Nie otwiera wyskakującego okienka i nie wymaga gestu użytkownika, więc bezpieczne jest wywołanie ładowania strony.
SDK automatycznie wykrywa tryb osadzony na podstawie ?fabricEmbedded=true w adresie URL. Możesz również wymusić to, ustawiając fabricEmbedded: true w opcjach.

Wywołaj initEmbeddedAuth() na wczesnym etapie uruchamiania aplikacji:

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() zwraca null, gdy aplikacja nie jest uruchomiona w trybie osadzonym, więc można ją bezpiecznie wywoływać bezwarunkowo. ensureSignedInWithFabric() również automatycznie podejmuje próbę trybu osadzonego przed powrotem do przepływu wyskakującego.

Korzystanie z uwierzytelniania Fabric na platformie React

Utwórz niestandardowy punkt zaczepienia, który integruje logowanie, rejestrację i wylogowywanie:

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

Użyj hooka w swoich komponentach:

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

Odniesienie do API

ensureSignedInWithFabric

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

Implementuje czteroetapową kaskadę uwierzytelniania:

Zwraca istniejącą sesję, jeśli została już uwierzytelniona.
Próbuje odświeżyć w trybie dyskretnym za pośrednictwem tokenu odświeżania.
Tryb osadzony — jeśli jest uruchomiony wewnątrz ramki iframe Fabric, pobiera sesję za pośrednictwem postMessage z ramki nadrzędnej.
Otwiera portal Fabric w wyskakującym oknie (w trybie wyskakującego okna) i czeka na przekazanie do postMessage.

Kroki od 1 do 3 można bezpiecznie wywołać podczas ładowania strony. Krok 4 otwiera okno podręczne i musi zostać uruchomione wewnątrz programu obsługi gestów użytkownika.

FabricAuthOptions

Property	Typ	Opis
`workspaceId`	`string`	Identyfikator obszaru roboczego Fabric.
`projectId`	`string`	Identyfikator elementu aplikacji Fabric.
`fabricPortalUrl`	`string`	Podstawowy adres URL portalu Fabric (na przykład `https://app.fabric.microsoft.com`).
`returnOrigin`	`string`	Źródło pochodzenia aplikacji na potrzeby dostarczania `postMessage` (na przykład `window.location.origin`). Musi zawierać tylko origin (schemat i host, bez ścieżki).
`fabricEmbedded`	`boolean` (opcjonalny)	Wymuś tryb osadzony. Wykryto automatycznie na podstawie elementu `?fabricEmbedded=true` w adresie URL.

Funkcje pomocnicze

Function	Opis
`initEmbeddedAuth(auth, options)`	Osadzone uwierzytelnianie bezpieczne podczas ładowania strony. Zwraca sesję, jeśli jest uruchomione w elemencie iframe platformy Fabric, lub `null` w przeciwnym razie.
`initiateFabricLogin(auth, options)`	Przepływ wyskakujących okienek niskiego poziomu. Otwiera portal Fabric w wyskakującym okienku z parametrami PKCE i nasłuchuje przekazywania `postMessage`.
`isEmbeddedMode(options)`	Zwraca `true`, jeśli aplikacja jest uruchomiona w trybie osadzonym (Fabric iframe).

Funkcje zabezpieczeń

PKCE S256 — każdy przepływ generuje weryfikator kodu kryptograficznego i wyzwanie, aby zapobiec przechwyceniu kodu autoryzacji.
Stan nonce – Losowa wartość nonce wiąże odpowiedź przekazania z kartą źródłową, zapobiegając fałszowaniu żądań między witrynami.
postMessage weryfikacja źródła — zestaw SDK weryfikuje event.origin komunikaty przychodzące i odrzuca komunikaty z nieoczekiwanych źródeł.
Automatyczne czyszczenie — stan PKCE wygasa po 5 minutach i jest zbierany w następnym przepływie.
Limit czasu przepływu — przepływ wyskakujących okienek jest przekroczony po 5 minutach, jeśli nie zostanie odebrany komunikat przekazywania.

Rozwiązywanie problemów z uwierzytelnianiem

Przeglądarka zablokowała okno portalu Fabric. Upewnij się, że ensureSignedInWithFabric() jest wywoływana z synchronicznego programu obsługi gestów użytkownika (na przykład przycisku onClick). Nie należy wywoływać go podczas ładowania strony ani wewnątrz łańcucha asynchronicznego przed interakcją użytkownika.

Sesja nie jest utrwalana

Upewnij się, że element RayfinClient jest skonfigurowany z poprawnymi baseUrl i publishableKey. Karta callbacku i oryginalna karta muszą mieć to samo pochodzenie, aby BroadcastChannel i localStorage działały.

Uwierzytelnianie kończy się niepowodzeniem po długim opóźnieniu

Przepływ logowania wygasa po 5 minutach. Jeśli uruchomisz proces logowania, ale nie ukończysz go w tym czasie, przepływ zakończy się niepowodzeniem. Zamknij wyskakujące okno i ponownie wybierz przycisk logowania, aby rozpocząć nowy proces.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-06-02