Skonfiguruj uwierzytelnianie SSO w aplikacji Fabric

Ustaw logowanie Microsoft Entra dla aplikacji Fabric przez portal Fabric, bezpośrednią delegowaną wymianę tokenów lub zaufany zewnętrzny portal nadrzędny. Te ścieżki uwierzytelniania wykorzystują Microsoft Entra i nie obsługują arbitralnych dostawców tożsamości.

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:

1. Aplikacja otwiera portal Fabric w oknie podręcznym i rejestruje odbiornik postMessage.
2. Użytkownik uwierzytelnia się za pośrednictwem Microsoft Entra ID w portalu Fabric.
3. Rozszerzenie Fabric wysyła kod przekazania z powrotem do Twojej aplikacji za pośrednictwem window.opener.postMessage().
4. Zestaw SDK wymienia kod przekazywania tokenów sesji Rayfin i tworzy sesję.
5. 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 element npx rayfin up dodaje origin wdrożonej aplikacji do allowedRedirectUris. Aby uzyskać wskazówki dotyczące konfiguracji i bezpieczeństwa, zobacz Konfiguruj przekierowania URI uwierzytelniania.

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

Dodawanie logowania i rejestracji do aplikacji

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.

Ręczne dodawanie logowania

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

Generowanie logowania i tworzenia konta przy użyciu GitHub Copilot

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.

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

Zaloguj się za pomocą istniejącego tokena Microsoft Entra

Używaj signInWithEntraToken(), gdy Twoja przeglądarka lub aplikacja Node.js ma już delegowany token dostępu Microsoft Entra. Ustanawia sesję Rayfin w istniejącym client.auth bez wyskakującego okienka, iframe, przekierowania czy kodu przekazywania.

Włącz zewnętrzną usługę Entra Exchange

Ustaw następujące opcje w pliku rayfin/rayfin.yml aplikacji docelowej i wdroż ponownie za pomocą npx rayfin up:

services:
  auth:
    enabled: true
    fabric:
      enabled: true
      externalEntraExchange: true

Docelowe środowisko Fabric musi wspierać wymianę zewnętrzną. Dostarczony token musi:

• Musi to być token dostępu delegowanego użytkownika, a nie token jednostki usługi typu app-only.
• Wskaż zasób Fabric lub Power BI zaakceptowany w ramach wdrożenia.
• Uwzględnij delegowany Item.Execute.All zakres.
• Zostanie wydany w dzierżawie właściciela elementu docelowego.

Użytkownik musi również mieć uprawnienie Execute do elementu aplikacji. W przypadku produkcyjnego środowiska Power BI zażądaj https://analysis.windows.net/powerbi/api/Item.Execute.All za pośrednictwem biblioteki tożsamości. SDK nie uzyskuje tokena Entra ani nie obsługuje zgody.

Używanie przeglądarki

Użyj tego samego zaufanego HTTPS backendowego URL i klucza publikowalnego co klient danych:

import { signInWithEntraToken } from '@microsoft/rayfin-auth-provider-fabric';
import { client } from './lib/rayfin';

async function signInWithDelegatedToken(entraToken: string) {
  const session = await signInWithEntraToken(client.auth, { entraToken });
  return session;
}

Przekaż surowy token dostępu bez prefiksu Bearer . Pomocnik korzysta z bazowego adresu URL klienta, zachowując ścieżkę wdrożenia, i dodaje /api/auth/v1/brokered/token. Podstawowy adres URL musi być bezwzględnym adresem URL HTTPS, bez danych uwierzytelniających, zapytań czy fragmentów. Nie używaj statycznego adresu URL, względnego proxy ani punktu końcowego dostarczonego przez niezaufanego wywołującego.

Dane i wywołania funkcji tego samego klienta automatycznie używają wymienionej sesji Rayfin. Wymiana w przeglądarce wymaga również, aby polityka CORS usługi zezwalała na Twoje źródło i nagłówek Authorization.

Obsłuż odrzucone próby logowania w interfejsie i pokaż błąd, zanim zezwolisz na wykonanie działań dla żądanego konta. Nieudana wymiana może pozostawić starszą, niewygasłą sesję w pamięci; nie traktuj jej jako udanego uwierzytelnienia nowo wybranego użytkownika.

Użycie Node.js i izolacja sesji

Możesz zaimportować i użyć pomocnika bez window, document, lub localStorage. W przypadku samodzielnej integracji SDK skonstruuj Auth i dołącz go do klienta API:

import { Auth } from '@microsoft/rayfin-auth';
import { ApiClient } from '@microsoft/rayfin-lib';
import { signInWithEntraToken } from '@microsoft/rayfin-auth-provider-fabric';

async function authenticateUser(
  rayfinEndpoint: string,
  publishableKey: string,
  entraToken: string,
) {
  const apiClient = new ApiClient({ baseUrl: rayfinEndpoint, publishableKey });
  const auth = new Auth(apiClient, { storage: false });
  auth.attachToClient(apiClient);

  try {
    const session = await signInWithEntraToken(auth, { entraToken });
    // Perform this user's SDK operations with apiClient inside this scope.
    return session.isAuthenticated;
  } finally {
    auth.destroy();
  }
}

Użyj zaufanego skonfigurowanego adresu URL rayfinEndpoint, a nie adresu URL kontrolowanego przez wywołującego. Twórz osobne instancje dla każdego użytkownika lub żądania, trzymaj sesje w pamięci i niszcz je, gdy nie są już potrzebne. Nigdy nie udostępniaj modyfikowalnego klienta zalogowanego między użytkownikami. W przypadku RayfinClient użyj authStorage: false do tego samego zachowania tylko w pamięci. RayfinServerClient nie udostępnia auth i nie może być bezpośrednio przekazana temu pomocnikowi.

SDK nie zapisuje dostarczonego tokena Entra. Normalne odświeżanie sesji wykorzystuje token odświeżania Rayfin; jeśli odświeżenie nie jest już możliwe, należy zdobyć nowy token Entra i wymienić go w sposób jawny.

Osadź w zewnętrznym portalu nadrzędnym

Używaj@microsoft/rayfin-embed-host, gdy portal poza Fabric osadza Twoją aplikację i już ma delegowaną tożsamość Entra. Element nadrzędny pośredniczy w uwierzytelnianiu; element iframe otrzymuje tylko jednorazowy kod przekazania, a nie token Entra elementu nadrzędnego.

Włącz externalEntraExchange i spełnij opisane wcześniej wymagania wstępne dotyczące delegowanego tokenu, dzierżawy, zakresu i elementu Wykonaj. Przyznanie dostępu do strony nadrzędnej nie daje dostępu do aplikacji Fabric.

Zainstaluj pakiet hosta w portalu nadrzędnym:

npm install @microsoft/rayfin-embed-host

Zarejestruj hosta przed zamontowaniem iframe, ponieważ iframe wysyła sygnał gotowości tylko raz:

import { createEmbedHost } from '@microsoft/rayfin-embed-host';

function mountFabricApp(getAccessToken: () => Promise<string>) {
  const appUrl = 'https://my-fabric-app.example.com';
  const host = createEmbedHost({
    allowedOrigins: [new URL(appUrl).origin],
    getAccessToken,
  });

  const iframe = document.createElement('iframe');
  iframe.src = appUrl;
  document.body.append(iframe);

  return () => {
    iframe.remove();
    host.dispose();
  };
}

Udostępnij funkcję pozyskiwania tokenów dla bieżącego użytkownika macierzystego. W aplikacji osadzonej wywołaj initEmbeddedAuth() i zaczekaj na jego zakończenie przed przywróceniem zapisanej sesji lub renderowaniem uwierzytelnionej treści, nawet jeśli getSession() zgłasza, że użytkownik jest już zalogowany. Zapisany użytkownik może różnić się od obecnego użytkownika rodzica. Mechanizm potwierdzania hosta wykrywa osadzenie zewnętrzne; dla tej ścieżki nie jest wymagana flaga zapytania fabricEmbedded.

Użyj dokładnych zaufanych źródeł, w tym schematu, hosta i portu, w allowedOrigins. Host weryfikuje zarówno źródło wiadomości iframe poświadczone przez przeglądarkę, jak i żądane źródło zwrotu przed wykonaniem wywołania autoryzacyjnego. Nie akceptuj arbitralnej listy dozwolonych dostarczonej przez wywołującego. Utrzymuj token Entra na ścieżce autoryzacji rodzica, nigdy go nie wysyłaj przez postMessage, i wywołaj host.dispose() podczas usuwania osadzenia.

Odniesienie do API

ensureSignedInWithFabric

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

Implementuje czteroetapową kaskadę uwierzytelniania:

1. Zwraca istniejącą sesję, jeśli została już uwierzytelniona.
2. Próbuje odświeżyć w trybie dyskretnym za pośrednictwem tokenu odświeżania.
3. Tryb osadzony — jeśli jest uruchomiony wewnątrz ramki iframe Fabric, pobiera sesję za pośrednictwem postMessage z ramki nadrzędnej.
4. 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

Funkcje pomocnicze

Funkcje zabezpieczeń

• PKCE S256 – Przepływy handoff generują kryptograficzny weryfikator kodu i wyzwanie, aby zapobiec przechwyceniu kodu autoryzacyjnego. Bezpośrednia wymiana tokenów Entra nie używa PKCE.
• 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

Wyskakujące okienko zablokowane

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.

Treści powiązane

• Konfiguruj uwierzytelnianie
• Konfiguruj URI przekierowania uwierzytelniania
• Wdróż na Fabric
• Definiowanie modeli danych