Configurar a autenticação SSO do Fabric para seu aplicativo do Fabric

Configurar o logon único (SSO) do Fabric para um aplicativo do Fabric para que os usuários possam entrar usando o Microsoft Entra ID por meio do portal do Fabric. Este artigo explica o fluxo de entrega e mostra como habilitar a configuração necessária e a integração do SDK para aplicativos implantados.

Pré-requisitos

Um projeto Fabric Apps com a autenticação habilitada. Consulte Configurar autenticação.
Um item do Fabric Apps implantado. Consulte Implantar no Fabric.

Como Fabric SSO funciona

O logon único (SSO) do Fabric usa uma transferência segura baseada em postMessage entre o seu aplicativo e o portal do Fabric. Não há nenhuma página de redirecionamento ou de callback:

Seu aplicativo abre o portal Fabric em um pop-up e registra um ouvinte postMessage.
O usuário é autenticado por meio de Microsoft Entra ID dentro do portal Fabric.
A extensão Fabric envia o código de entrega de volta para seu aplicativo por meio de window.opener.postMessage().
O SDK troca o código de entrega por tokens de sessão do Rayfin e cria uma sessão.
O pop-up Fabric é fechado automaticamente.

O fluxo é protegido por PKCE (Proof Key for Code Exchange), nonces de estado e validação de origem postMessage para evitar a interceptação do código de autorização e a falsificação de solicitações entre sites.

Habilitar a autenticação Fabric

Adicione a configuração de autenticação Fabric ao arquivo rayfin/rayfin.yml:

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

Para aplicações implantadas, reimplante para aplicar as configurações atualizadas:

npx rayfin up

Para aplicativos implantados, npx rayfin up adiciona a URL de retorno de chamada do aplicativo implantado a allowedRedirectUris.

Instalar o provedor de autenticação Fabric (opcional)

Projetos criados com npm create @microsoft/rayfin@latest já incluem @microsoft/rayfin-auth-provider-fabric. Instale-o manualmente somente se você estiver adicionando a autenticação do Fabric a um projeto que ainda não tenha esse pacote:

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

Fabric SSO usa uma única API para entrada e inscrição: ensureSignedInWithFabric(). Quando um usuário faz login pela primeira vez, o Fabric provisiona automaticamente uma sessão do Rayfin para ele com base em sua identidade no Microsoft Entra ID — não há uma chamada de cadastro separada. O mesmo fluxo de código lida com usuários recorrentes.

Você pode adicionar esse código manualmente ou gerá-lo com GitHub Copilot no VS Code.

Chame ensureSignedInWithFabric() em um manipulador de gesto do usuário (por exemplo, a seleção de um botão):

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

A função deve ser chamada de um manipulador de gestos de usuário síncrono para evitar bloqueadores de pop-up. Chamá-lo ao carregar a página ou em uma cadeia assíncrona antes da interação do usuário aciona o bloqueio de pop-up do navegador.

returnOrigin deve ser uma origem nua (esquema e host, sem caminho)— por exemplo, https://app.contoso.com. O SDK o usa para validar eventos de entrada postMessage .

Adicionar logout manualmente

Chame client.auth.signOut() para encerrar a sessão e limpar tokens armazenados em cache:

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

Assine as alterações de sessão para atualizar sua interface do usuário quando a entrada ou saída for concluída:

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

Se você usar GitHub Copilot no VS Code, abra Copilot Chat em seu projeto Fabric Apps e use prompts como esses para estruturar o código de autenticação. O Copilot segue os padrões da habilidade Rayfin incluída na extensão Fabric para VS Code.

Goal	Exemplo de prompt do Copilot
Adicionar um botão de login	`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.`
Adicionar um botão de saída	`Add a Sign out button that calls client.auth.signOut() and updates the UI when the session ends.`
Adicionar um hook do React que reconhece a autenticação	`Create a useFabricAuth React hook that exposes session, signIn, signOut, and isAuthenticated, using ensureSignedInWithFabric and client.auth.onSessionChange.`
Suporte ao modo incorporado	`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.`
Restringir uma rota	`Wrap the /dashboard route so it calls ensureSignedInWithFabric before rendering and redirects unauthenticated users to a sign-in page.`

Depois que o Copilot gerar o código, revise as edições e verifique se:

A ensureSignedInWithFabric() chamada é executada dentro de um manipulador de gestos do usuário (por exemplo, onClick), não na carga da página.
returnOrigin é uma origem simples e corresponde a uma das entradas em allowedRedirectUris em rayfin/rayfin.yml.
As importações vêm de @microsoft/rayfin-auth-provider-fabric (não dos auxiliares de callback descontinuados).

Usar o modo incorporado em um iframe do Fabric

Quando o aplicativo é carregado dentro de uma Fabric iframe (por exemplo, quando um usuário o abre do portal Fabric), use o modo inserido em vez do fluxo pop-up:

O modo incorporado adquire a sessão por meio de postMessage do frame pai.
Ele não abre um pop-up e não exige interação do usuário, portanto é seguro invocá-lo ao carregar a página.
O SDK detecta automaticamente o modo incorporado a partir de ?fabricEmbedded=true na URL. Você também pode forçá-lo definindo-o fabricEmbedded: true nas opções.

Chame initEmbeddedAuth() logo no início da inicialização do aplicativo:

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() retorna null quando o aplicativo não está em execução no modo incorporado, portanto é seguro chamá-lo incondicionalmente. ensureSignedInWithFabric() também tenta automaticamente o modo incorporado antes de recorrer ao fluxo de pop-up.

Usar a autenticação Fabric no React

Crie um gancho personalizado que integre a entrada, a inscrição e a saída:

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 o gancho em seus 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>
    </>
  );
}

Referência de API

ensureSignedInWithFabric

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

Implementa uma cascata de autenticação de quatro etapas:

Retorna a sessão existente se já estiver autenticada.
Tenta uma atualização silenciosa por meio do token de atualização.
Modo incorporado — se estiver em execução dentro de um iframe do Fabric, obtém a sessão por meio de postMessage do frame pai.
Abre o portal do Fabric em uma janela pop-up (fluxo em janela pop-up) e aguarda a transferência postMessage.

As etapas 1 a 3 podem ser chamadas com segurança ao carregar a página. A etapa 4 abre um pop-up e deve ser executada dentro de um manipulador de gestos do usuário.

FabricAuthOptions

Property	Tipo	Description
`workspaceId`	`string`	A ID do workspace Fabric.
`projectId`	`string`	A ID do item do aplicativo Fabric.
`fabricPortalUrl`	`string`	A URL base do portal Fabric (por exemplo, `https://app.fabric.microsoft.com`).
`returnOrigin`	`string`	A origem do aplicativo para `postMessage` entrega (por exemplo, `window.location.origin`). Deve ser uma origem simples (esquema e host, sem caminho).
`fabricEmbedded`	`boolean` (opcional)	Forçar o modo incorporado. Detectado automaticamente a partir de `?fabricEmbedded=true` na URL.

Funções auxiliares

Function	Description
`initEmbeddedAuth(auth, options)`	Autenticação incorporada segura para o carregamento da página. Retorna a sessão se estiver sendo executada em um iframe do Fabric ou `null` caso contrário.
`initiateFabricLogin(auth, options)`	Fluxo de pop-up de baixo nível. Abre o portal do Fabric em um pop-up com parâmetros PKCE e aguarda a transferência `postMessage`.
`isEmbeddedMode(options)`	Retorna `true` se o aplicativo estiver em execução no modo inserido (Fabric iframe).

Recursos de segurança

PKCE S256 – Cada fluxo gera um verificador de código criptográfico e um desafio para impedir a interceptação de código de autorização.
Nonce de estado – Um nonce aleatório associa a resposta de transferência à guia de origem, impedindo a falsificação de solicitações entre sites.
postMessage validação de origem – o SDK valida event.origin em mensagens de entrada e rejeita mensagens de origens inesperadas.
Limpeza automática – o estado PKCE expira após 5 minutos e é coletado no próximo fluxo.
Tempo limite de fluxo – o fluxo de pop-up atingirá o tempo limite após 5 minutos se nenhuma mensagem de entrega for recebida.

Solucionar problemas de autenticação

O navegador bloqueou a janela do portal Fabric. Verifique se ensureSignedInWithFabric() é chamado de um manipulador de gestos de usuário síncrono (por exemplo, botão onClick). Não chame-o no carregamento da página ou dentro de uma cadeia assíncrona antes da interação do usuário.

Sessão não está sendo mantida

Confirme se o RayfinClient está configurado com os baseUrl e publishableKey corretos. A aba de callback e a aba original devem compartilhar a mesma origem para que BroadcastChannel e localStorage funcionem.

A autenticação falha após um longo atraso

O fluxo de entrada expira após 5 minutos. Se você iniciar o processo de entrada, mas não concluí-lo dentro desse tempo, o fluxo falhará. Feche o pop-up e selecione o botão de entrada novamente para iniciar um novo fluxo.

Comentários

Esta página foi útil?

Last updated on 2026-06-02