Configure a autenticação SSO do Fabric para a sua aplicação Fabric

Configure o login único (SSO) Fabric para uma aplicação Fabric para que os utilizadores possam iniciar sessão com o Microsoft Entra ID através do portal Fabric. Este artigo explica o fluxo de transferência e mostra como ativar a configuração necessária e a integração do SDK para aplicações implementadas.

Pré-requisitos

Como funciona o Fabric SSO

Fabric login único (SSO) utiliza uma transferência segura baseada em postMessage entre a sua aplicação e o portal Fabric. Não há página de redirecionamento nem de retorno:

  1. A sua aplicação abre o portal Fabric num popup e regista um ouvinte postMessage.
  2. O utilizador autentica-se através do Microsoft Entra ID dentro do portal Fabric.
  3. A extensão Fabric envia o código de transferência de volta para a sua aplicação por intermédio de window.opener.postMessage().
  4. O SDK troca o código de handoff por tokens de sessão da Rayfin e cria uma sessão.
  5. O pop-up do Fabric fecha-se automaticamente.

O fluxo é protegido com PKCE (Proof Key for Code Exchange), nonces de estado e validação de origem postMessage para evitar a interceção de código de autorização e a falsificação de pedidos entre sites.

Ativar a autenticação do Fabric

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

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

Para aplicações já implementadas, reimplemente para aplicar as definições atualizadas:

npx rayfin up

Para aplicações implantadas, npx rayfin up adiciona o URL de callback da sua aplicação implantada a allowedRedirectUris.

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

Os projetos estruturados com npm create @microsoft/rayfin@latest já incluem @microsoft/rayfin-auth-provider-fabric. Instale-o manualmente apenas se estiver a adicionar autenticação Fabric a um projeto que ainda não tenha o pacote:

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

Adicione login e registo à sua aplicação

Fabric SSO utiliza uma única API tanto para login como para registo: ensureSignedInWithFabric(). Quando um utilizador inicia sessão pela primeira vez, o Fabric fornece automaticamente uma sessão Rayfin com base na sua identidade Microsoft Entra ID — não existe uma chamada de inscrição separada. O mesmo fluxo de execução processa os utilizadores que regressam.

Podes adicionar este código manualmente ou gerá-lo com o GitHub Copilot no VS Code.

Adicionar login manualmente

Chame ensureSignedInWithFabric() a partir de um processador de gestos do utilizador (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 a partir de um handler síncrono de gestos do utilizador para evitar bloqueadores de popups. Invocá-lo ao carregar a página ou numa cadeia assíncrona antes da interação do utilizador ativa a proteção contra pop-ups do navegador.

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

Adicionar terminar sessão manualmente

Chamada client.auth.signOut() para terminar a sessão e limpar tokens em cache:

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

Subscreva as alterações de sessão para atualizar a sua interface de utilizador quando o login ou desconexão terminar:

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

Gerar login e registo com o GitHub Copilot

Se usares GitHub Copilot no VS Code, abre Copilot Chat no teu projeto Fabric Apps e usa prompts como estes para apoiar o código de autenticação. O Copilot segue os padrões da habilidade Rayfin incluída na extensão Fabric VS Code.

Goal Exemplo de prompt do Copilot
Adicionar um botão de início de sessão 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 desconexão Add a Sign out button that calls client.auth.signOut() and updates the UI when the session ends.
Adiciona um hook React com reconhecimento de autenticação Create a useFabricAuth React hook that exposes session, signIn, signOut, and isAuthenticated, using ensureSignedInWithFabric and client.auth.onSessionChange.
Suporte ao modo embutido 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 de o Copilot gerar código, revê as edições e certifica-te:

  • A ensureSignedInWithFabric() chamada é executada dentro de um handler de gestos de utilizador (por exemplo, onClick)—não durante o carregamento da página.
  • returnOrigin é uma origem simples e corresponde a uma das entradas em allowedRedirectUris em rayfin/rayfin.yml.
  • As importações provêm de @microsoft/rayfin-auth-provider-fabric (não das funções auxiliares de callback obsoletas).

Use o modo embutido dentro de um iframe Fabric

Quando a sua aplicação carrega dentro de um iframe Fabric (por exemplo, quando um utilizador a abre a partir do portal Fabric), use o modo embutido em vez do fluxo pop-up:

  • O modo incorporado obtém a sessão através de postMessage para o frame pai.
  • Não abre um pop-up nem requer um gesto do utilizador, por isso é seguro chamá-lo ao carregar a página.
  • O SDK deteta automaticamente o modo embutido a partir ?fabricEmbedded=true da URL. Também podes forçá-lo definindo fabricEmbedded: true nas opções.

Chame initEmbeddedAuth() no início do arranque da aplicação:

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 a aplicação não está a correr em modo embutido, por isso é seguro ligar incondicionalmente. ensureSignedInWithFabric() Também tenta o modo embutido automaticamente antes de voltar ao fluxo popup.

Utilizar a autenticação do Fabric no React

Crie um gancho personalizado que integre log-in, cadastro e desligamento:

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

Utilize o hook nos 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 da API

ensureSignedInWithFabric

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

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

  1. Devolve a sessão existente se já estiver autenticada.
  2. Tenta uma atualização silenciosa através do token de atualização.
  3. Modo incorporado — se estiver a correr dentro de um iframe do Fabric, obtém a sessão através de postMessage junto do frame principal.
  4. Abre o portal Fabric num popup (popup flow) e espera pela transferência postMessage.

Os passos 1 a 3 são seguros para chamar durante o carregamento da página. O Passo 4 abre um popup e tem de ser executado dentro de um handler de gestos de utilizador.

FabricAuthOptions

Property Tipo Description
workspaceId string O ID do espaço de trabalho do Fabric.
projectId string O ID do item da aplicação Fabric.
fabricPortalUrl string A URL base do portal Fabric (por exemplo, https://app.fabric.microsoft.com).
returnOrigin string A origem da sua aplicação para distribuição em postMessage (por exemplo, window.location.origin). Deve ser uma origem simples (esquema e hospedeiro, sem caminho).
fabricEmbedded boolean (opcional) Forçar modo incorporado. Detetado automaticamente a partir ?fabricEmbedded=true da URL.

Funções auxiliares

Função Description
initEmbeddedAuth(auth, options) Autenticação embutida segura para carregamento de páginas. Devolve a sessão se estiver a correr dentro de um iframe Fabric, ou null caso contrário.
initiateFabricLogin(auth, options) Fluxo de pop-up de baixo nível. Abre o portal do Fabric numa janela pop-up com parâmetros PKCE e aguarda a transferência postMessage.
isEmbeddedMode(options) Devolve true se a aplicação estiver a correr em modo embutido (Fabric iframe).

Elementos de segurança

  • PKCE S256 – Cada fluxo gera um verificador de código criptográfico e um desafio para evitar a interceção de códigos de autorização.
  • State nonce – Um nonce aleatório liga a resposta de handoff ao separador de origem, prevenindo a falsificação de pedidos entre sites.
  • postMessage validação de origem – O SDK valida event.origin mensagens recebidas e rejeita mensagens de origens inesperadas.
  • Limpeza automática – o estado PKCE expira ao fim de 5 minutos e é eliminado no fluxo seguinte.
  • Tempo limite do fluxo – O pop-up expira após 5 minutos se não for recebida nenhuma mensagem de encaminhamento.

Solucionar problemas de autenticação

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

Sessão não persistente

Confirme que o RayfinClient está configurado com o correto baseUrl e publishableKey. O separador de callback e o separador original devem partilhar 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 iniciar o processo de início de sessão, mas não o concluir dentro desse prazo, o fluxo falhará. Feche o pop-up e selecione novamente o botão de iniciar sessão para iniciar um novo fluxo.

Conteúdo relacionado

  • Last updated on