Konfigurer Fabric SSO-autentificering til din Fabric-app

Opsæt Microsoft Entra-login-ind for en Fabric-app via Fabric-portalen, en direkte delegeret tokenudveksling eller en betroet ekstern moderportal. Disse autentificeringsveje bruger Microsoft Entra, og de understøtter ikke vilkårlige identitetsudbydere.

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øjes npx rayfin up din deployed-app-oprindelse til allowedRedirectUris. For konfigurations- og sikkerhedsvejledning, se Konfigurer autentificeringsomdirigerings-URI'er.

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

Log ind med en eksisterende Microsoft Entra-token

Brug signInWithEntraToken() den, når din browser eller Node.js applikation allerede har fået en delegeret Microsoft Entra adgangstoken. Den opretter en Rayfin-session på din eksisterende client.auth løsning uden en popup, iframe, omdirigering eller overførselskode.

Aktiver ekstern entra-udveksling

Indstil følgende muligheder i målappens rayfin/rayfin.yml fil, og genudrul med npx rayfin up:

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

Det målrettede Fabric-miljø skal understøtte ekstern udveksling. Den medfølgende token skal:

• Vær en delegeret brugeradgangstoken, ikke en app-only service principal token.
• Målrett den Fabric- eller Power BI-ressource, som implementeringen accepterer.
• Inkluder det delegerede Item.Execute.All omfang.
• Udstedt i målobjektets ejerlejer.

Brugeren skal også have Execute-tilladelse på app-elementet. For produktions-Power BI, anmod https://analysis.windows.net/powerbi/api/Item.Execute.All via dit identitetsbibliotek. SDK'et erhverver ikke Entra-tokenet eller håndterer samtykke.

Browserbrug

Brug den samme betroede HTTPS backend-URL og publicerbare nøgle som din dataklient:

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

Giv rå adgangstoken uden præfiks.Bearer Hjælperen bruger klientens backend-base-URL, bevarer dens deploymentsti, og tilføjer /api/auth/v1/brokered/token. Den grundlæggende URL skal være absolut HTTPS uden legitimationsoplysninger, forespørgsler eller fragmenter. Brug ikke den statisk-hostende URL, en relativ proxy-URL eller et endpoint leveret af en ubetroet opkalder.

Den samme klients data og funktionskald bruger automatisk den udvekslede Rayfin-session. Browser Exchange kræver også, at tjenestens CORS-politik tillader din oprindelse og autorisationsheaderen.

Håndter afviste logins i dit UI og vis fejlen, før du tillader handlinger for den ønskede konto. En fejlslagen udveksling kan efterlade en ældre, uudløbet session i hukommelsen; behandl det ikke som en vellykket autentificering af den nyvalgte bruger.

Node.js brug og sessionsisolering

Du kan importere og bruge hjælperen uden window, document, eller localStorage. For en selvstændig SDK-integration, konstruer Auth og tilknyt den til API-klienten:

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

Brug en betroet konfigureret rayfinEndpointURL, ikke en opkaldskontrolleret URL. Opret separate instanser pr. bruger eller anmodning, behold sessioner i hukommelsen, og delad dem, når de ikke længere er nødvendige. Del aldrig en foranderlig logget klient mellem brugere. Med RayfinClient, brug authStorage: false for samme hukommelses-only adfærd. RayfinServerClient eksponerer auth ikke og kan ikke gives direkte til denne hjælper.

SDK'en opbevarer ikke den medfølgende Entra-token. Normal sessionsopdatering bruger Rayfin-opdateringstokenet; hvis opdatering ikke længere er mulig, erhverves en ny Entra-token og udveksles den eksplicit.

Indlejr en ekstern overordnet portal

Brug @microsoft/rayfin-embed-host den, når en portal uden for Fabric indlejrer din app og allerede har en delegeret Entra-identitet. Moderselskabet mægler autentificering; iframen modtager kun en engangs-handoff-kode, ikke moderselskabets Entra-token.

Aktiver externalEntraExchange og opfyld de delegerede token-, lejer-, scope- og item Execute-forudsætninger , som beskrevet tidligere. At give adgang til en forældreside giver ikke adgang til Fabric-appen.

Installer værtspakken i forældreportalen:

npm install @microsoft/rayfin-embed-host

Registrer værten , før du monterer iframen, fordi iframen kun sender sit beredskabssignal én gang:

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

Giv en token-indsamlingsfunktion til den nuværende overordnede bruger. I den indlejrede app, kald og vent initEmbeddedAuth() , før du gendanner en lagret session eller gengiver autentificeret indhold, selv når getSession() du allerede rapporterer en bruger. Den gemte bruger kan være anderledes end forælderens nuværende bruger. Værtsbekræftelsen registrerer ekstern indlejring; der kræves ikke noget fabricEmbedded forespørgselsflag for denne sti.

Brug nøjagtige betroede oprindelser, inklusive scheme, host og port, i allowedOrigins. Værten validerer både den browser-attesterede iframe-beskedoprindelse og den anmodede returoprindelse, før autorisationskaldet foretages. Accepter ikke en vilkårlig tilladelsesliste fra opkaldene. Behold Entra-tokenet i forældreautorisationsstien, send det aldrig igennem postMessage, og kald host.dispose() når du fjerner embed'en.

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 – Handoff-flows genererer en kryptografisk kode-verificeringsenhed og udfordrer for at forhindre opsnapning af autorisationskoder. Direkte Entra token-udveksling bruger ikke PKCE.
• 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
• Konfigurer autentificering af omdirigerings-URI'er
• Udrul til Fabric
• Definér datamodeller