Configurare l'autenticazione SSO Fabric per l'app Fabric

Configurare Fabric Single Sign-On (SSO) per un'app Fabric in modo che gli utenti possano accedere con Microsoft Entra ID tramite il portale di Fabric. Questo articolo illustra il flusso di distribuzione e illustra come abilitare la configurazione necessaria e l'integrazione dell'SDK per le app distribuite.

Prerequisiti

• Progetto app Fabric con l'autenticazione abilitata. Vedere Configurare l'autenticazione.
• Elemento Fabric Apps distribuito. Vedere Deploy in Fabric.

Come funziona il Single Sign-On (SSO) di Fabric

Fabric single sign-on (SSO) usa un handoff sicuro basato su postMessage tra l'applicazione e il portale di Fabric. Non esiste alcuna pagina di reindirizzamento o callback:

1. L'app apre il portale di Fabric in un popup e registra un listener postMessage.
2. L'utente esegue l'autenticazione tramite Microsoft Entra ID all'interno del portale di Fabric.
3. L'estensione Fabric invia il codice di handoff alla tua app tramite window.opener.postMessage().
4. L'SDK scambia il codice di consegna per i token di sessione Rayfin e crea una sessione.
5. Il popup Fabric si chiude automaticamente.

Il flusso è protetto con PKCE (Proof Key for Code Exchange), nonce di stato e postMessage convalida dell'origine per impedire l'intercettazione del codice di autorizzazione e la contraffazione di richieste tra siti.

Abilitare l'autenticazione Fabric

Aggiungere la configurazione di autenticazione Fabric al file rayfin/rayfin.yml:

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

Per le applicazioni già distribuite, ridistribuire per applicare le impostazioni aggiornate:

npx rayfin up

Per le app distribuite, npx rayfin up aggiunge l'URL di callback dell'app distribuita a allowedRedirectUris.

Installare il provider di autenticazione Fabric (facoltativo)

I progetti creati con lo scaffolding tramite npm create @microsoft/rayfin@latest includono già @microsoft/rayfin-auth-provider-fabric. Installalo manualmente solo se stai aggiungendo l'autenticazione Fabric a un progetto che non include già il pacchetto:

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

Aggiungi l'accesso e la registrazione alla tua app

Fabric SSO usa una singola API per l'accesso e l'iscrizione: ensureSignedInWithFabric(). Quando un utente accede per la prima volta, Fabric effettua automaticamente il provisioning di una sessione Rayfin in base all'identità Microsoft Entra ID, senza una chiamata di iscrizione separata. Lo stesso percorso di codice gestisce la restituzione degli utenti.

È possibile aggiungere questo codice a mano o generarlo con GitHub Copilot in VS Code.

Aggiungere manualmente l'accesso

Chiama ensureSignedInWithFabric() da un gestore di gesti dell'utente (ad esempio, la selezione di un pulsante):

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

La funzione deve essere chiamata da un gestore di movimenti utente sincrono per evitare blocchi popup. Chiamandola al caricamento della pagina o all'interno di una catena asincrona prima che l'interazione dell'utente attivi la protezione popup del browser.

returnOrigin deve essere un'origine bare (schema e host, nessun percorso), ad esempio https://app.contoso.com. L'SDK lo usa per convalidare gli eventi in ingresso postMessage .

Aggiungi manualmente la disconnessione

Chiamare client.auth.signOut() per terminare la sessione e cancellare i token memorizzati nella cache:

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

Sottoscrivi le modifiche alla sessione per aggiornare l'interfaccia utente quando l'accesso o la disconnessione vengono completati:

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

Generare l'accesso e l'iscrizione con GitHub Copilot

Se si usa GitHub Copilot in VS Code, aprire Copilot Chat nel progetto Fabric Apps e usare richieste simili a queste per eseguire lo scaffolding del codice di autenticazione. Copilot segue gli schemi della skill Rayfin inclusa nell'estensione Fabric VS Code.

Dopo che Copilot ha generato il codice, esamina le modifiche e assicurati che:

• La ensureSignedInWithFabric() chiamata viene eseguita all'interno di un gestore movimenti utente (ad esempio) onClicke non nel caricamento della pagina.
• returnOrigin è un'origine semplice e corrisponde a una delle voci in allowedRedirectUris in rayfin/rayfin.yml.
• Le importazioni provengono da @microsoft/rayfin-auth-provider-fabric (non dagli helper di callback deprecati).

Usare la modalità incorporata all'interno di un iframe Fabric

Quando l'app viene caricata all'interno di un iframe Fabric (ad esempio, quando un utente lo apre dal portale di Fabric), usa la modalità incorporata anziché il flusso popup:

• La modalità incorporata ottiene la sessione dal frame padre tramite postMessage.
• Non apre un popup e non richiede un movimento dell'utente, quindi è sicuro chiamare al caricamento della pagina.
• L'SDK rileva automaticamente la modalità incorporata dall'URL ?fabricEmbedded=true . È anche possibile forzarlo impostando fabricEmbedded: true nelle opzioni.

Chiamare initEmbeddedAuth() all'inizio dell'avvio dell'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() restituisce null quando l'app non è in esecuzione in modalità incorporata, quindi è possibile chiamare in modo incondizionato. ensureSignedInWithFabric() prova automaticamente anche la modalità integrata prima di passare al flusso pop-up.

Usa l'autenticazione di Fabric in React

Creare un hook personalizzato che integra l'accesso, la registrazione e la disconnessione:

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

Usa l'hook nei componenti:

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

Informazioni di riferimento sulle API

ensureSignedInWithFabric

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

Implementa una cascata di autenticazione in quattro passaggi:

1. Restituisce la sessione esistente se già autenticata.
2. Tenta un rinnovo silenzioso tramite il token di aggiornamento.
3. Modalità incorporata: se in esecuzione all'interno di un iframe Fabric, acquisisce la sessione tramite postMessage al frame padre.
4. Apre il portale di Fabric in una finestra popup (flusso popup) e attende il passaggio postMessage.

I passaggi da 1 a 3 possono essere eseguiti in sicurezza durante il caricamento della pagina. Il passaggio 4 apre un popup e deve essere eseguito all'interno di un gestore movimenti utente.

FabricAuthOptions

Funzioni di supporto

Funzionalità di sicurezza

• PKCE S256 : ogni flusso genera un verificatore di codice crittografico e verifica per impedire l'intercettazione del codice di autorizzazione.
• Nonce di stato – Un nonce casuale associa la risposta di handoff alla scheda di origine, impedendo gli attacchi di contraffazione di richieste tra siti.
• postMessage convalida dell'origine : l'SDK convalida i event.origin messaggi in arrivo e rifiuta i messaggi provenienti da origini impreviste.
• Pulizia automatica – lo stato PKCE scade dopo 5 minuti e viene eliminato al flusso successivo.
• Timeout del flusso : si verifica il timeout del flusso popup dopo 5 minuti se non viene ricevuto alcun messaggio di handoff.

Risolvere i problemi di autenticazione

Popup bloccato

Il browser ha bloccato la finestra del portale di Fabric. Assicurarsi che ensureSignedInWithFabric() venga chiamato da un gestore di movimenti utente sincrono ,ad esempio il pulsante onClick. Non chiamarlo al caricamento della pagina o all'interno di una catena asincrona prima dell'interazione dell'utente.

Sessione non persistente

Verificare che sia RayfinClient configurato con i valori corretti baseUrl e publishableKey. La scheda callback e la scheda originale devono condividere la stessa origine per BroadcastChannel e localStorage per funzionare.

L'autenticazione ha esito negativo dopo un lungo ritardo

Il flusso di accesso scade dopo 5 minuti. Se si avvia il processo di accesso ma non lo si completa entro tale intervallo di tempo, il flusso ha esito negativo. Chiudere il popup e selezionare di nuovo il pulsante di accesso per avviare un nuovo flusso.

Contenuti correlati

• Configurare l'autenticazione
• Distribuisci in Fabric
• Definire i modelli di dati