Configuración de la autenticación de SSO de Fabric para la aplicación de Fabric

Configure el inicio de sesión único (SSO) de Fabric para una aplicación de Fabric para que los usuarios puedan iniciar sesión con Microsoft Entra ID desde el portal de Fabric. En este artículo se explica el flujo de entrega y se muestra cómo habilitar la configuración necesaria y la integración del SDK para las aplicaciones implementadas.

Prerequisites

Un proyecto de Fabric Apps con autenticación habilitada. Consulte Configuración de la autenticación.
Un elemento de Fabric Apps implementado. Consulte Deploy to Fabric.

Funcionamiento del inicio de sesión único de Fabric

El inicio de sesión único (SSO) de Fabric utiliza una transferencia segura basada en postMessage entre tu aplicación y el portal de Fabric. No hay ninguna página de redirección ni de retorno:

La aplicación abre el portal de Fabric en una ventana emergente y registra un escuchador de postMessage.
El usuario se autentica a través de Microsoft Entra ID dentro del portal de Fabric.
La extensión de Fabric envía el código de transferencia a tu aplicación a través de window.opener.postMessage().
El SDK intercambia el código de entrega para los tokens de sesión de Rayfin y crea una sesión.
La ventana emergente de Fabric se cierra automáticamente.

El flujo está protegido con PKCE (Proof Key for Code Exchange), nonces de estado y validación del origen postMessage para evitar la interceptación del código de autorización y la falsificación de solicitudes entre sitios.

Habilitar la autenticación de Fabric

Añada la configuración de autenticación de Fabric a su archivo rayfin/rayfin.yml:

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

En el caso de las aplicaciones implementadas, vuelva a implementar para insertar la configuración actualizada:

npx rayfin up

En el caso de las aplicaciones implementadas, npx rayfin up agrega la dirección URL de devolución de llamada de la aplicación implementada a allowedRedirectUris.

Instalación del proveedor de autenticación Fabric (opcional)

Los proyectos generados con npm create @microsoft/rayfin@latest ya incluyen @microsoft/rayfin-auth-provider-fabric. Instálelo manualmente solo si va a agregar Fabric autenticación a un proyecto que aún no tiene el paquete:

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

Fabric SSO usa una sola API para el inicio de sesión y el registro: ensureSignedInWithFabric(). Cuando un usuario inicia sesión por primera vez, Fabric aprovisiona una sesión de Rayfin automáticamente en función de su identidad de Microsoft Entra ID, no hay ninguna llamada de registro independiente. El mismo flujo de código gestiona a los usuarios recurrentes.

Puede agregar este código manualmente o generarlo con GitHub Copilot en VS Code.

Llamada ensureSignedInWithFabric() desde un controlador de gestos de usuario (por ejemplo, una selección de botón):

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

Se debe llamar a la función desde un controlador síncrono de un gesto del usuario para evitar los bloqueadores de ventanas emergentes. Invocarlo al cargar la página o dentro de una cadena asíncrona antes de que el usuario interactúe activa la protección del navegador contra ventanas emergentes.

returnOrigin debe ser un origen simple (esquema y host, sin ruta), por ejemplo: https://app.contoso.com. El SDK lo usa para validar los eventos entrantes postMessage .

Añadir cierre de sesión manualmente

Llame client.auth.signOut() a para finalizar la sesión y borrar los tokens almacenados en caché:

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

Suscríbase a los cambios de sesión para actualizar la interfaz de usuario cuando finalice el inicio de sesión o cierre de sesión:

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

Si usas GitHub Copilot en VS Code, abre Copilot Chat en tu proyecto de Fabric Apps y utiliza indicaciones como estas para generar el código base de autenticación. Copilot sigue los patrones de la habilidad Rayfin incluida en la extensión de Fabric para VS Code.

Objetivo	Ejemplo de instrucción de Copilot
Agregar un botón de inicio de sesión	`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.`
Agregar un botón de cierre de sesión	`Add a Sign out button that calls client.auth.signOut() and updates the UI when the session ends.`
Añadir un hook de React que tenga en cuenta la autenticación	`Create a useFabricAuth React hook that exposes session, signIn, signOut, and isAuthenticated, using ensureSignedInWithFabric and client.auth.onSessionChange.`
Admite el modo incrustado	`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.`
Puerta de una ruta	`Wrap the /dashboard route so it calls ensureSignedInWithFabric before rendering and redirects unauthenticated users to a sign-in page.`

Después de que Copilot genere código, revise las modificaciones y asegúrese de que:

La ensureSignedInWithFabric() llamada se ejecuta dentro de un controlador de gestos de usuario (por ejemplo, onClick) y no en la carga de página.
returnOrigin es un origen simple y coincide con una de las entradas de allowedRedirectUris en rayfin/rayfin.yml.
Las importaciones proceden de @microsoft/rayfin-auth-provider-fabric (no de las utilidades callback en desuso).

Usa el modo incrustado en un iframe de Fabric

Cuando la aplicación se cargue dentro de un iframe de Fabric (por ejemplo, cuando un usuario lo abra desde el portal de Fabric), use el modo incrustado en lugar del flujo emergente:

El modo incrustado adquiere la sesión a través postMessage del marco primario.
No abre una ventana emergente y no requiere interacción del usuario, por lo que se puede llamar con seguridad al cargar la página.
El SDK detecta automáticamente el modo incrustado a partir de ?fabricEmbedded=true en la URL. También puede forzarlo estableciendo fabricEmbedded: true en las opciones.

Llama a initEmbeddedAuth() al principio del inicio de la aplicación:

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() devuelve null cuando la aplicación no se ejecuta en modo incrustado, por lo que es seguro llamar incondicionalmente. ensureSignedInWithFabric() también intenta el modo incrustado automáticamente antes de volver al flujo emergente.

Uso de la autenticación de Fabric en React

Cree un enlace personalizado que integre el inicio de sesión, el registro y el cierre de sesión:

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

Use el enlace en los componentes:

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

Referencia de las API

ensureSignedInWithFabric

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

Implementa una cascada de autenticación en cuatro pasos:

Devuelve la sesión existente si ya está autenticada.
Intenta una actualización silenciosa a través del token de actualización.
Modo incrustado: si se ejecuta dentro de un iframe de Fabric, adquiere la sesión a través de postMessage al marco primario.
Abre el portal de Fabric en una ventana emergente (flujo en ventana emergente) y espera el traspaso postMessage.

Los pasos 1 a 3 se pueden ejecutar con seguridad al cargar la página. El paso 4 abre una ventana emergente y debe ejecutarse dentro de un controlador de interacción del usuario.

FabricAuthOptions

Propiedad	Tipo	Descripción
`workspaceId`	`string`	Identificador del área de trabajo de Fabric.
`projectId`	`string`	El identificador de elemento de la aplicación Fabric.
`fabricPortalUrl`	`string`	Dirección URL base del portal de Fabric (por ejemplo, `https://app.fabric.microsoft.com`).
`returnOrigin`	`string`	Origen de entrega de su aplicación para `postMessage` (por ejemplo, `window.location.origin`). Debe ser un origen simple (esquema y host, sin ruta).
`fabricEmbedded`	`boolean` (opcional)	Forzar el modo incrustado. Se detecta automáticamente desde `?fabricEmbedded=true` en la dirección URL.

Funciones del asistente

Function	Descripción
`initEmbeddedAuth(auth, options)`	Autenticación integrada segura durante la carga de la página. Devuelve la sesión si se ejecuta dentro de un iframe de Fabric, o `null` de lo contrario.
`initiateFabricLogin(auth, options)`	Flujo de ventanas emergentes de bajo nivel. Abre el portal de Fabric en una ventana emergente con parámetros PKCE y queda a la espera de la transferencia `postMessage`.
`isEmbeddedMode(options)`	Devuelve `true` si la aplicación se ejecuta en modo incrustado (Fabric iframe).

Características de seguridad

PKCE S256 : cada flujo genera un comprobador de código criptográfico y un desafío para evitar la interceptación de código de autorización.
Nonce de estado – un nonce aleatorio vincula la respuesta de transferencia con la pestaña de origen, lo que impide la falsificación de peticiones entre sitios.
postMessage validación de origen : el SDK se valida en los mensajes entrantes event.origin y rechaza los mensajes de orígenes inesperados.
Limpieza automática – el estado de PKCE caduca a los 5 minutos y se elimina en el siguiente flujo.
Tiempo de espera del flujo – El flujo emergente caduca al cabo de 5 minutos si no se recibe ningún mensaje de transferencia.

Solución de problemas de autenticación

El explorador bloqueó la ventana del portal de Fabric. Asegúrese ensureSignedInWithFabric() de que se llama desde un controlador de gestos de usuario sincrónico (por ejemplo, botón onClick). No lo invoques al cargar la página ni dentro de una cadena asíncrona antes de que el usuario interactúe.

Sesión no persistente

RayfinClient Confirme que está configurado con los valores correctos baseUrl y publishableKey. La pestaña de retorno de llamada y la pestaña original deben compartir el mismo origen para que BroadcastChannel y localStorage funcionen.

Se produce un error en la autenticación después de un retraso largo

El flujo de inicio de sesión expira después de 5 minutos. Si inicia el proceso de inicio de sesión, pero no lo completa en ese momento, se produce un error en el flujo. Cierre el elemento emergente y vuelva a seleccionar el botón de inicio de sesión para iniciar un nuevo flujo.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-06-02