Configurer l’authentification SSO Fabric pour votre application Fabric

Configurez Fabric’authentification unique (SSO) pour une application Fabric afin que les utilisateurs puissent se connecter avec Microsoft Entra ID via le portail Fabric. Cet article explique le flux de transfert et montre comment activer la configuration requise et l’intégration du Kit de développement logiciel (SDK) pour les applications déployées.

Prerequisites

Un projet Fabric Apps avec l’authentification activée. Consultez Configurer l’authentification.
Élément déployé de Fabric Apps. Consultez Deploy to Fabric.

Fonctionnement de l’authentification unique Fabric

L’authentification unique (SSO) de Fabric utilise une transmission sécurisée basée sur postMessage entre votre application et le portail Fabric. Il n’existe aucune page de redirection ou de rappel :

Votre application ouvre le portail Fabric dans une fenêtre contextuelle et inscrit un écouteur postMessage.
L’utilisateur s’authentifie via Microsoft Entra ID à l’intérieur du portail Fabric.
L’extension Fabric renvoie le code de remise à votre application via window.opener.postMessage().
Le Kit de développement logiciel (SDK) échange le code de transfert pour les jetons de session Rayfin et crée une session.
La fenêtre contextuelle Fabric se ferme automatiquement.

Le flux est sécurisé à l’aide de PKCE (Proof Key for Code Exchange), de nonces d’état et de la validation d’origine postMessage afin d’empêcher l’interception du code d’autorisation et les attaques de falsification de requêtes intersites.

Activer l’authentification Fabric

Ajoutez la configuration d’authentification Fabric à votre fichier rayfin/rayfin.yml :

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

Pour les applications déployées, redéployez-les pour appliquer les paramètres mis à jour :

npx rayfin up

Pour les applications déployées, npx rayfin up ajoute l’URL de rappel de votre application déployée à allowedRedirectUris.

Installer le fournisseur d’authentification Fabric (facultatif)

Les projets générés avec npm create @microsoft/rayfin@latest incluent déjà @microsoft/rayfin-auth-provider-fabric. Installez-le manuellement uniquement si vous ajoutez Fabric'authentification à un projet qui n'a pas déjà le package :

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

Fabric SSO utilise une seule API pour se connecter et s’inscrire : ensureSignedInWithFabric(). Lorsqu'un utilisateur se connecte pour la première fois, Fabric approvisionne automatiquement une session Rayfin en fonction de son identité Microsoft Entra ID ; il n'existe aucun appel d'inscription distinct. La même branche de code gère les utilisateurs qui reviennent.

Vous pouvez ajouter ce code manuellement ou le générer avec GitHub Copilot dans VS Code.

Appelez ensureSignedInWithFabric() depuis un gestionnaire de gestes de l’utilisateur (par exemple, lors de la sélection d’un bouton) :

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 fonction doit être appelée à partir d’un gestionnaire synchrone de mouvements utilisateur pour éviter les bloqueurs de fenêtres contextuelles. L’appeler au chargement de la page ou dans une chaîne asynchrone avant toute interaction de l’utilisateur déclenche la protection du navigateur contre les fenêtres contextuelles.

returnOrigin doit être une origine nue (schéma et hôte, aucun chemin d’accès), par exemple https://app.contoso.com. Le Kit de développement logiciel (SDK) l’utilise pour valider les événements entrants postMessage .

Ajouter la déconnexion manuellement

Appelez client.auth.signOut() pour mettre fin à la session et effacer les jetons mis en cache :

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

S’abonner aux modifications de session pour mettre à jour votre interface utilisateur lorsque la connexion ou la déconnexion se termine :

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

Si vous utilisez GitHub Copilot dans VS Code, ouvrez Copilot Chat dans votre projet Fabric Apps et utilisez des instructions comme celles-ci pour ébaucher le code d’authentification. Copilot s’aligne sur les modèles du skill Rayfin inclus dans l’extension Fabric pour VS Code.

Objectif	Exemple de requête Copilot
Ajouter un bouton de connexion	`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.`
Ajouter un bouton de déconnexion	`Add a Sign out button that calls client.auth.signOut() and updates the UI when the session ends.`
Ajouter un hook React prenant en compte l’authentification	`Create a useFabricAuth React hook that exposes session, signIn, signOut, and isAuthenticated, using ensureSignedInWithFabric and client.auth.onSessionChange.`
Prise en charge du mode intégré	`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.`
Contrôler l’accès à une route	`Wrap the /dashboard route so it calls ensureSignedInWithFabric before rendering and redirects unauthenticated users to a sign-in page.`

Après Copilot génère du code, passez en revue les modifications et vérifiez les points suivants :

L’appel ensureSignedInWithFabric() s’exécute à l’intérieur d’un gestionnaire de mouvements utilisateur (par exemple, onClick) et non au chargement de page.
returnOrigin est une origine nue et correspond à l’une des entrées dans allowedRedirectUrisrayfin/rayfin.yml.
Les importations proviennent de @microsoft/rayfin-auth-provider-fabric (et non des fonctions utilitaires de rappel déconseillées).

Utiliser le mode incorporé à l’intérieur d’un iframe Fabric

Lorsque votre application se charge à l’intérieur d’un iframe Fabric (par exemple, lorsqu’un utilisateur l’ouvre à partir du portail Fabric), utilisez le mode incorporé au lieu du flux contextuel :

Le mode intégré récupère la session via le postMessage cadre parent.
Il n’ouvre pas de fenêtre pop-up et ne nécessite aucune interaction de l’utilisateur ; il peut donc être appelé au chargement de la page.
Le SDK détecte automatiquement le mode intégré à partir de ?fabricEmbedded=true dans l’URL. Vous pouvez également la forcer en définissant fabricEmbedded: true dans les options.

Appelez initEmbeddedAuth() tôt au démarrage de l’application :

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() retourne null lorsque l’application ne s’exécute pas en mode incorporé, il est donc sûr d’appeler sans condition. ensureSignedInWithFabric() essaie également automatiquement d’utiliser le mode intégré avant de basculer sur la fenêtre contextuelle.

Utiliser l’authentification Fabric dans React

Créez un hook personnalisé qui intègre la connexion, l’inscription et la déconnexion :

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

Utilisez le hook dans vos composants :

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

Référence d’API

ensureSignedInWithFabric

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

Implémente une cascade d’authentification en quatre étapes :

Retourne la session existante si elle est déjà authentifiée.
Tente une actualisation silencieuse via le jeton d’actualisation.
Mode intégré — s’il s’exécute dans une iframe Fabric, récupère la session via postMessage auprès du frame parent.
Ouvre le portail Fabric dans une fenêtre contextuelle (flux contextuel) et attend le transfert postMessage.

Les étapes 1 à 3 peuvent être appelées sans risque au chargement de la page. L’étape 4 ouvre une fenêtre contextuelle et doit s’exécuter à l’intérieur d’un gestionnaire de mouvements utilisateur.

FabricAuthOptions

Propriété	Type	Description
`workspaceId`	`string`	ID de l’espace de travail Fabric.
`projectId`	`string`	Identifiant de l’élément de l’application Fabric.
`fabricPortalUrl`	`string`	URL de base du portail Fabric (par exemple, `https://app.fabric.microsoft.com`).
`returnOrigin`	`string`	Origine de votre application pour la diffusion via `postMessage` (par exemple, `window.location.origin`). Doit être une origine nue (protocole et hôte, sans chemin).
`fabricEmbedded`	`boolean` (facultatif)	Forcer le mode incorporé. Détecté automatiquement à partir de `?fabricEmbedded=true` dans l’URL.

Fonctions d’assistance

Function	Description
`initEmbeddedAuth(auth, options)`	Authentification intégrée compatible avec le chargement de la page. Renvoie la session si l’exécution a lieu dans un iframe Fabric, ou `null` sinon.
`initiateFabricLogin(auth, options)`	Flux de popup de bas niveau. Ouvre le portail Fabric dans une fenêtre contextuelle avec des paramètres PKCE et attend la transmission `postMessage`.
`isEmbeddedMode(options)`	Retourne `true` si l’application s’exécute en mode incorporé (Fabric iframe).

Fonctionnalités de sécurité

PKCE S256 : chaque flux génère un vérificateur de code de chiffrement et un défi pour empêcher l’interception du code d’autorisation.
Nonce d’état : une nonce aléatoire lie la réponse de transfert à l’onglet d’origine, empêchant la falsification de requête intersite.
postMessage validation d’origine : le Kit de développement logiciel (SDK) valide les messages entrants event.origin et rejette les messages provenant d’origines inattendues.
Nettoyage automatique – l’état de PKCE expire après 5 minutes et est supprimé automatiquement lors du flux suivant.
Expiration du flux – Le flux de fenêtre contextuelle expire au bout de 5 minutes si aucun message de transfert n’est reçu.

Résoudre les problèmes d’authentification

Le navigateur a bloqué la fenêtre du portail Fabric. Vérifiez que ensureSignedInWithFabric() est appelé à partir d’un gestionnaire synchrone de geste utilisateur (par exemple, le bouton onClick). Ne l’appelez pas au chargement de page ou à l’intérieur d’une chaîne asynchrone avant l’interaction de l’utilisateur.

Session non persistante

Vérifiez que l’option RayfinClient est configurée avec la valeur correcte baseUrl et publishableKey. L’onglet rappel et l’onglet d’origine doivent partager la même origine pour BroadcastChannel et localStorage pour fonctionner.

L’authentification échoue après un long délai

Le flux de connexion expire après 5 minutes. Si vous démarrez le processus de connexion mais que vous ne la terminez pas dans ce temps, le flux échoue. Fermez la fenêtre contextuelle et sélectionnez à nouveau le bouton de connexion pour démarrer un nouveau flux.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-06-02