Konfigurer Fabric SSO-autentisering for Fabric-appen din

Sett opp Microsoft Entra-pålogging for en Fabric-app via Fabric-portalen, en direkte delegert token-utveksling eller en betrodd ekstern moderportal. Disse autentiseringsstiene bruker Microsoft Entra, og de støtter ikke vilkårlige identitetsleverandører.

Forutsetninger

• Et Fabric Apps-prosjekt med autentisering aktivert. Se Konfigurer autentisering.
• Et distribuert Fabric Apps-element. Se Deploy to Fabric.

Hvordan Fabric SSO fungerer

Fabric single sign-on (SSO) bruker en sikker postMessage-basert overlevering mellom applikasjonen din og Fabric-portalen. Det finnes ingen omdirigering eller tilbakekallingsside:

1. Appen din åpner Fabric-portalen i en popup og registrerer en postMessage-lytter.
2. Brukeren autentiserer seg via Microsoft Entra ID inne i Fabric-portalen.
3. Fabric-utvidelsen sender overleveringskoden tilbake til appen din via window.opener.postMessage().
4. SDK-en bytter overleveringskoden for Rayfin-sesjonstokene og oppretter en økt.
5. Fabric-popupen lukkes automatisk.

Flyten sikres med PKCE (Proof Key for Code Exchange), state nonces og postMessage opprinnelsesvalidering for å forhindre avskjæring av autorisasjonskoder og forfalskning av forespørsler på tvers av steder.

Aktiver Fabric-autentisering

Legg til Fabric-autentiseringskonfigurasjonen i din rayfin/rayfin.yml-fil:

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

For deployerte applikasjoner, redeploy for å pushe de oppdaterte innstillingene:

npx rayfin up

For distribuerte apper npx rayfin up legger den til din distribuerte app-opprinnelse til allowedRedirectUris. For konfigurasjons- og sikkerhetsveiledning, se Konfigurer autentiseringsomdirigerings-URIs.

Installer Fabric-autentiseringsleverandøren (valgfritt)

Prosjekter stillas med npm create @microsoft/rayfin@latest inkluderer @microsoft/rayfin-auth-provider-fabricallerede . Installer det manuelt kun hvis du legger til Fabric-autentisering i et prosjekt som ikke allerede har pakken:

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

Legg til pålogging og registrering i appen din

Fabric SSO bruker ett enkelt API for både innlogging og påmelding: ensureSignedInWithFabric(). Når en bruker logger inn for første gang, oppretter Fabric automatisk en Rayfin-økt for dem basert på deres Microsoft Entra ID-identitet – det er ingen separat påmeldingssamtale. Den samme kodestien håndterer tilbakevendende brukere.

Du kan legge til denne koden for hånd eller generere den med GitHub Copilot i VS Code.

Legg til pålogging manuelt

Kall ensureSignedInWithFabric() fra en bruker-gesthåndtering (for eksempel et knappevalg):

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

Funksjonen må kalles fra en synkron bruker-gesthåndtering for å unngå popup-blokkere. Å kalle det under sidelasting eller inne i en asynkron kjede før brukerinteraksjon utløser nettleser-popup-beskyttelse.

returnOrigin må være en naken opprinnelse (skjema og vert, ingen sti)—for eksempel, https://app.contoso.com. SDK-en bruker den til å validere innkommende postMessage hendelser.

Legg til utlogging manuelt

Kall client.auth.signOut() for å avslutte økten og slette bufrede tokens:

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

Abonner på øktendringer for å oppdatere brukergrensesnittet ditt når inn- eller utlogging er fullført:

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

Generer pålogging og registrer deg med GitHub Copilot

Hvis du bruker GitHub Copilot i VS Code, åpne Copilot Chat i Fabric Apps-prosjektet ditt og bruk slike prompts for å støtte autentiseringskoden. Copilot følger mønstrene i Rayfin-ferdigheten som følger med Fabric VS Code-utvidelsen.

Etter at Copilot har generert kode, gjennomgå endringene og sørg for:

• Kallet ensureSignedInWithFabric() kjører inne i en bruker-gesthåndtering (for eksempel onClick)—ikke ved sidelasting.
• returnOriginer en naken opprinnelse og samsvarer med ett av oppføringene i allowedRedirectUris i .rayfin/rayfin.yml
• Importene kommer fra @microsoft/rayfin-auth-provider-fabric (ikke de foreldede callback-hjelperne).

Bruk innebygd modus inne i en Fabric iframe

Når appen din laster inn i en Fabric iframe (for eksempel når en bruker åpner den fra Fabric-portalen), bruk innebygd modus i stedet for popup-flyten:

• Innebygd modus henter sesjonen gjennom postMessage til foreldrerammen.
• Den åpner ikke en popup og krever ikke brukerbevegelse, så det er trygt å kalle på sideinnlasting.
• SDK-en oppdager automatisk innebygd modus fra ?fabricEmbedded=true URL-en. Du kan også tvinge det ved å sette fabricEmbedded: true innstillingene.

Ring initEmbeddedAuth() tidlig i app-oppstart:

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 kjører i innebygd modus, så det er trygt å kalle ubetinget. ensureSignedInWithFabric() Prøver også automatisk innebygd modus før den faller tilbake til popup-flyten.

Bruk Fabric-autentisering i React

Lag en tilpasset krok som integrerer pålogging, påmelding og utlogging:

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

Bruk kroken i komponentene dine:

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

Logg inn med en eksisterende Microsoft Entra-token

Bruk signInWithEntraToken() når nettleseren din eller Node.js applikasjon allerede har mottatt en delegert Microsoft Entra tilgangstoken. Den oppretter en Rayfin-økt på din eksisterende client.auth uten popup-, iframe-, omdirigerings- eller overleveringskode.

Aktiver ekstern entra-utveksling

Sett følgende alternativer i målappens rayfin/rayfin.yml fil, og deploy på nytt med npx rayfin up:

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

Det målrettede Fabric-miljøet må støtte ekstern utveksling. Den medfølgende brikken må:

• Vær en delegert brukertilgangstoken, ikke en app-only tjenesteprincipal token.
• Sikt deg mot Fabric- eller Power BI-ressursen som distribueringen aksepterer.
• Inkluder det delegerte Item.Execute.All omfanget.
• Utstedt i målobjektets eier.

Brukeren må også ha Execute-tillatelse på app-elementet. For produksjons-Power BI, be om https://analysis.windows.net/powerbi/api/Item.Execute.All via identitetsbiblioteket ditt. SDK-en skaffer ikke Entra-tokenet eller håndterer samtykket.

Nettleserbruk

Bruk samme pålitelige HTTPS-backend-URL og publiserbare nøkkel som dataklienten din:

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

Send rå tilgangstoken uten Bearer prefiks. Hjelperen bruker klientens backend-base-URL, bevarer distribusjonsstien, og legger /api/auth/v1/brokered/tokentil . Grunn-URL-en må være absolutt HTTPS uten legitimasjon, spørring eller fragment. Ikke bruk den statiske hosting-URL-en, en relativ proxy-URL eller et endepunkt levert av en upålitelig caller.

Den samme klientens data og funksjonskall bruker automatisk den utvekslede Rayfin-sesjonen. Nettleserutveksling krever også at tjenestens CORS-policy tillater din opprinnelse og autorisasjonshodet.

Håndter avviste pålogginger i brukergrensesnittet ditt og vis feilen før du tillater handlinger for den forespurte kontoen. En mislykket utveksling kan etterlate en eldre, uavsluttet økt i minnet; ikke behandle det som vellykket autentisering av den nyvalgte brukeren.

Node.js bruk og sesjonsisolasjon

Du kan importere og bruke hjelperen uten window, document, eller localStorage. For en frittstående SDK-integrasjon, bygg Auth og koble 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();
  }
}

Bruk en betrodd konfigurert rayfinEndpointURL, ikke en URL-styrt av anroperen. Lag separate instanser per bruker eller forespørsel, hold øktene i minnet, og ødelegg dem når de ikke lenger er nødvendige. Del aldri en foranderlig innlogget klient mellom brukere. Med RayfinClient, bruk authStorage: false for samme hukommelsesbaserte oppførsel. RayfinServerClient eksponerer auth ikke og kan ikke sendes direkte til denne hjelperen.

SDK-en opprettholder ikke den medfølgende Entra-tokenen. Normal sesjonsoppdatering bruker Rayfin-oppdateringstoken; hvis oppfriskning ikke lenger er mulig, skaff en ny Entra-token og bytt den eksplisitt.

Embed inn en ekstern foreldreportal

Bruk @microsoft/rayfin-embed-host når en portal utenfor Fabric legger inn appen din og allerede har en delegert entra-identitet. Forelderen megler autentisering; iframen mottar kun en engangs-overleveringskode, ikke forelderens Entra-token.

Aktiver externalEntraExchange og oppfyll de delegerte token-, leietaker-, scope- og item Execute-forutsetningene beskrevet tidligere. Å gi tilgang til en foreldreside gir ikke tilgang til Fabric-appen.

Installer vertspakken i foreldreportalen:

npm install @microsoft/rayfin-embed-host

Registrer verten før du monterer iframen fordi iframen bare sender sitt beredskapssignal é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();
  };
}

Tilby en token-innsamlingsfunksjon for den nåværende foreldrebrukeren. I den innebygde appen, kall og vent initEmbeddedAuth() før du gjenoppretter en lagret sesjon eller gjengir autentisert innhold, selv når getSession() du allerede rapporterer en bruker. Den lagrede brukeren kan være annerledes enn forelderens nåværende bruker. Vertsbekreftelsen oppdager ekstern innbedding; ingen fabricEmbedded spørringsflagg er nødvendig for denne stien.

Bruk nøyaktige pålitelige opprinnelser, inkludert scheme, host og port, i allowedOrigins. Verten validerer både den nettleserattesterte iframe-meldingsopprinnelsen og den forespurte returopprinnelsen før autorisasjonskallet forestår. Ikke aksepter en vilkårlig tillatelsesliste levert av innringere. Behold Entra-tokenet i foreldreautorisasjonsstien, aldri send det gjennom postMessage, og kall host.dispose() når du fjerner embed-en.

API-referanse

ensureSignedInWithFabric

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

Implementerer et firetrinns autentiseringsfossefall:

1. Returnerer den eksisterende sesjonen hvis den allerede er autentisert.
2. Forsøker en stille oppdatering via oppdateringstokenet.
3. Innebygd modus—hvis den kjøres inne i en Fabric iframe, henter sesjonen gjennom postMessage til foreldrerammen.
4. Åpner Fabric-portalen i en popup (popup-flyt) og venter på postMessage overlevering.

Trinn 1 til 3 er trygge å kalle ved sideinnlasting. Trinn 4 åpner en popup og må kjøres inne i en bruker-gesthåndtering.

FabricAuthOptions

Hjelper-funksjoner

Sikkerhetsfunksjoner

• PKCE S256 – Overleveringsflyter genererer en kryptografisk kodeverifikator og utfordrer for å forhindre avskjæring av autorisasjonskode. Direkte Entra token-utveksling bruker ikke PKCE.
• State nonce – En tilfeldig nonce knytter handoff-svaret til den opprinnelige fanen, og forhindrer forfalskning av forespørsler på tvers av steder.
• postMessage Opprinnelsesvalidering – SDK-en validerer event.origin innkommende meldinger og avviser meldinger fra uventede opprinnelser.
• Automatisk opprydding – PKCE-tilstanden utløper etter 5 minutter og samles søppel ved neste flyt.
• Flow-timeout – Popup-flyten går ut etter 5 minutter hvis ingen overleveringsmelding mottas.

Feilsøke godkjenningsproblemer

Popup blokkert

Nettleseren blokkerte Fabric-portalvinduet. Ensure ensureSignedInWithFabric() kalles fra en synkron bruker-gesthåndtering (for eksempel knapp onClick). Ikke kall det på sidelasting eller inne i en asynkron kjede før brukerinteraksjon.

Økt som ikke vedvarer

Bekreft at er RayfinClient konfigurert med riktig baseUrl og publishableKey. Callback-fanen og den opprinnelige fanen må ha samme opprinnelse for BroadcastChannel og localStorage for å fungere.

Autentisering feiler etter lang forsinkelse

Innloggingsflyten utløper etter 5 minutter. Hvis du starter innloggingsprosessen, men ikke fullfører den innen den tiden, feiler flyten. Lukk popup-vinduet og velg innloggingsknappen igjen for å starte en ny flyt.

Relatert innhold

• Konfigurer godkjenning
• Configure authentication redirect URIs
• Deploy til Fabric
• Definer datamodeller