Määritä Fabric SSO -tunnistautuminen Fabric-sovelluksellesi

Aseta Fabric single sign-on (SSO) Fabric-sovellukselle, jotta käyttäjät voivat kirjautua sisään Microsoft Entra ID:llä Fabric-portaalin kautta. Tässä artikkelissa selitetään, miten luovutusprosessi ja näytetään, miten vaadittu konfigurointi ja SDK-integraatio voidaan ottaa käyttöön käyttöönotetuille sovelluksille.

Edellytykset

Miten Fabric SSO toimii

Fabric kertakirjautuminen (SSO) käyttää turvallista postMessage-pohjaista siirtoa sovelluksesi ja Fabric-portaalin välillä. Ei ole uudelleenohjaus- tai takaisinsoittosivua:

  1. Sovelluksesi avaa Fabric-portaalin ponnahdusikkunassa ja rekisteröi postMessage kuuntelijan.
  2. Käyttäjä tunnistautuu Microsoft Entra ID:n kautta Fabric-portaalin sisällä.
  3. Fabric-laajennus lähettää siirtokoodin takaisin sovellukseesi window.opener.postMessage():n kautta.
  4. SDK vaihtaa siirtokoodin Rayfin-istuntotokenien kanssa ja luo istunnon.
  5. Fabric-ponnahdusikkuna sulkeutuu automaattisesti.

Prosessi on suojattu PKCE:llä (Proof Key for Code Exchange), tila-nonces-toiminnoilla ja postMessage origin-validaatiolla, joka estää valtuutuskoodin sieppauksen ja poikkipaikkaisten pyyntöjen väärentämisen.

Ota Fabric-tunnistautuminen käyttöön

Lisää Fabric todennuskonfiguraatio rayfin/rayfin.yml-tiedostoosi:

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

Käytössä oleville sovelluksille otetaan, jotta päivitetyt asetukset voidaan asettaa:

npx rayfin up

Käyttöönotetuille sovelluksille lisää npx rayfin up käyttöön otetun sovelluksen takaisinkutsu-URL osoitteeseen allowedRedirectUris.

Asenna Fabric-todennuspalveluntarjoaja (valinnainen)

Projektit, jotka on npm create @microsoft/rayfin@latest jo rakennettu, sisältävät @microsoft/rayfin-auth-provider-fabric. Asenna se manuaalisesti vain, jos lisäät Fabric-tunnistautumisen projektiin, jossa ei vielä ole pakettia:

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

Lisää kirjautuminen ja rekisteröityminen sovellukseesi

Fabric SSO käyttää yhtä API:ta sekä kirjautumiseen että rekisteröitymiseen: ensureSignedInWithFabric(). Kun käyttäjä kirjautuu sisään ensimmäistä kertaa, Fabric tarjoaa hänelle automaattisesti Rayfin-istunnon Microsoft Entra ID -identiteettinsä perusteella – erillistä rekisteröitymiskutsua ei ole. Sama koodipolku käsittelee palaavia käyttäjiä.

Voit lisätä tämän koodin käsin tai luoda sen GitHub Copilot -ohjelmalla VS Codessa.

Lisää kirjautuminen manuaalisesti

Puhelu ensureSignedInWithFabric() käyttäjän eleen käsittelijältä (esimerkiksi napin valinta):

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

Funktio täytyy kutsua synkronisesta käyttäjä-eleenkäsittelijästä, jotta ponnahdusikkunan estäjät välttyvät. Kutsumalla sitä sivun latauksen yhteydessä tai asynkronisessa ketjussa ennen käyttäjän vuorovaikutusta käynnistää selaimen ponnahdusikkunan suojan.

returnOrigin on oltava pelkkä origo (skeema ja isäntä, ei polkua)—esimerkiksi https://app.contoso.com. SDK käyttää sitä saapuvien postMessage tapahtumien validointiin.

Lisää uloskirjautuminen manuaalisesti

Kutsu client.auth.signOut() session lopettamiseksi ja välimuistissa olevien tokenien tyhjentämiseksi:

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

Tilaa istuntomuutokset päivittääksesi käyttöliittymäsi, kun kirjautuminen tai uloskirjautuminen on valmis:

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

Luo kirjautuminen ja rekisteröityminen GitHub Copilot -ohjelmalla

Jos käytät GitHub Copilot VS Code:ssa, avaa Copilot Chat Fabric Apps -projektissasi ja käytä tällaisia kehotuksia vahvistaaksesi autentiikkakoodin. Copilot noudattaa Rayfin-taidon kaavoja, jotka sisältyvät Fabric VS Code -laajennukseen.

Päämäärä Esimerkki Copilot-kehote
Lisää kirjautumispainike 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.
Lisää uloskirjautumispainike Add a Sign out button that calls client.auth.signOut() and updates the UI when the session ends.
Lisää autentikointitietoinen React-koukku Create a useFabricAuth React hook that exposes session, signIn, signOut, and isAuthenticated, using ensureSignedInWithFabric and client.auth.onSessionChange.
Tuki sulautettua tilaa 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.
Gate a reitti Wrap the /dashboard route so it calls ensureSignedInWithFabric before rendering and redirects unauthenticated users to a sign-in page.

Kun Copilot on luonut koodin, tarkista muokkaukset ja varmista:

  • Kutsu ensureSignedInWithFabric() toimii käyttäjän eleen käsittelylaitteessa (esimerkiksi onClick)—ei sivun latauksessa.
  • returnOrigin on pelkkä origo ja vastaa yhtä merkinnästä joukossa allowedRedirectUrisrayfin/rayfin.yml.
  • Tuonnit tulevat @microsoft/rayfin-auth-provider-fabric (eivät vanhentuneilta callback-avustajilta).

Käytä upotettua tilaa Fabric iframen sisällä

Kun sovelluksesi latautuu Fabric-iframeen (esimerkiksi kun käyttäjä avaa sen Fabric-portaalista), käytä upotettua tilaa ponnahdusikkunan sijaan:

  • Upotettu tila siirtää istunnon aina postMessage vanhemmalle kehykselle.
  • Se ei avaa ponnahdusikkunaa eikä vaadi käyttäjän elettä, joten on turvallista kutsua sivun latautuessa.
  • SDK tunnistaa automaattisesti upotetun tilan URL-osoitteesta ?fabricEmbedded=true . Voit myös pakottaa sen asettamalla fabricEmbedded: true asetukset.

Soita initEmbeddedAuth() sovelluksen käynnistyksen alussa:

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() palautetaan null , kun sovellus ei ole sulautetussa tilassa, joten on turvallista soittaa ehdoitta. ensureSignedInWithFabric() Yrittää myös upotettua tilaa automaattisesti ennen kuin palaa ponnahdusikkunan virtaan.

Käytä Fabric-tunnistautumista Reactissa

Luo mukautettu hook, joka yhdistää kirjautumisen, rekisteröitymisen ja uloskirjautumisen:

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

Käytä koukkua komponenteissasi:

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

Ohjelmointirajapinnan viittaus

ensureSignedWithFabric

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

Toteuttaa nelivaiheisen todennusvesiputouksen:

  1. Palauttaa olemassa olevan istunnon, jos se on jo autentikoitu.
  2. Yrittää hiljaista päivitystä päivitystokenin kautta.
  3. Upotettu tila—jos se ajetaan Fabric iframessa, istunto siirtyy postMessage kautta emokehykseen.
  4. Avaa Fabric-portaalin ponnahdusikkunassa (ponnahdusikkunan virtaus) ja odottaa postMessage -siirtoa.

Vaiheet 1–3 ovat turvallisia kutsua sivun latauksen yhteydessä. Vaihe 4 avaa ponnahdusikkunan ja sen täytyy toimia käyttäjän eleiden käsittelijässä.

FabricAuthOptions

Ominaisuus Tyyppi Description
workspaceId string Fabric-työtilan tunnus.
projectId string Fabric-sovelluksen tuote-ID.
fabricPortalUrl string Fabric portaalin perus-URL (esimerkiksi https://app.fabric.microsoft.com).
returnOrigin string Sovelluksesi toimituslähde postMessage (esimerkiksi, window.location.origin). Täytyy olla pelkkä alkuperä (skeema ja isäntä, ei polkua).
fabricEmbedded boolean (valinnainen) Pakotettu upotettu tila. Automaattinen tunnistettu ?fabricEmbedded=true URL-osoitteesta.

Aputoiminnon toiminnot

Toiminto Description
initEmbeddedAuth(auth, options) Sivun latausturvallinen upotettu autentikointi. Palauttaa istunnon, jos se pyörii Fabric iframessa, tai null muuten.
initiateFabricLogin(auth, options) Matalan tason ponnahdusikkunan virtaus. Avaa Fabric-portaalin ponnahdusikkunassa, jossa on PKCE-parametrit, ja kuuntelee postMessage-siirtoa.
isEmbeddedMode(options) Palauttaa true, jos sovellus pyörii sulautetussa tilassa (Fabric iframe).

Suojausominaisuudet

  • PKCE S256 – Jokainen prosessi luo kryptografisen koodin varmennusaineen ja haasteen estääkseen valtuutuskoodin sieppauksen.
  • State nonce – Satunnainen nonce sitoo siirtovastauksen alkuperäiseen välilehteen, estäen poikkipaikkaisten pyyntöjen väärentämisen.
  • postMessage alkuperän validointi – SDK validoi event.origin saapuvia viestejä ja hylkää odottamattomista lähtökohdista tulevia viestejä.
  • Automaattinen puhdistus – PKCE-tila vanhenee 5 minuutin jälkeen ja seuraavalla virtauksella kerätään roskat.
  • Virtausaikakatkaisu – Ponnahdusikkunan virtaus päättyy 5 minuutin jälkeen, jos siirtoviestiä ei tule.

Todentamisongelmien vianmääritys

Selain esti Fabric-portaalin ikkunan. Ensure ensureSignedInWithFabric() kutsutaan synkronisesta käyttäjä-eleiden käsittelijästä (esimerkiksi painike onClick). Älä kutsu sitä sivun latauksessa tai asynkronisessa ketjussa ennen käyttäjän vuorovaikutusta.

Istunto ei jatku

Varmista, RayfinClient että on konfiguroitu oikealla baseUrl ja publishableKey. Callback-välilehden ja alkuperäisen välilehden täytyy jakaa sama alkuperä toimiakseen BroadcastChannel ja localStorage toimiakseen.

Tunnistautuminen epäonnistuu pitkän viiveen jälkeen

Kirjautumisvirta päättyy viiden minuutin kuluttua. Jos aloitat kirjautumisprosessin, mutta et saa sitä valmiiksi siinä ajassa, prosessi epäonnistuu. Sulje ponnahdusikkuna ja valitse kirjautumispainike uudelleen aloittaaksesi uuden flow'n.

Liittyvä sisältö

  • Last updated on