Mengonfigurasi autentikasi SSO Fabric untuk aplikasi Fabric Anda

Siapkan single sign-on (SSO) Fabric untuk aplikasi Fabric agar pengguna dapat masuk menggunakan Microsoft Entra ID melalui portal Fabric. Artikel ini menjelaskan alur handoff dan menunjukkan cara mengaktifkan konfigurasi yang diperlukan serta melakukan integrasi SDK untuk aplikasi yang telah di-deploy.

Prasyarat

Proyek Fabric Apps dengan autentikasi diaktifkan. Lihat Mengonfigurasi autentikasi.
Item Aplikasi Fabric yang diterapkan. Lihat Sebarkan ke Fabric.

Cara kerja SSO Fabric

Fabric single sign-on (SSO) menggunakan pengalihan aman berbasis postMessage antara aplikasi Anda dan portal Fabric. Tidak ada halaman pengalihan atau panggilan balik:

Aplikasi Anda membuka portal Fabric di popup dan mendaftarkan pendengar postMessage.
Pengguna mengautentikasi melalui Microsoft Entra ID di dalam portal Fabric.
Ekstensi Fabric mengirimkan kode penyerahan kembali ke aplikasi Anda melalui window.opener.postMessage().
SDK menukar kode handoff dengan token sesi Rayfin dan membuat sesi.
Popup Fabric ditutup secara otomatis.

Alur diamankan dengan PKCE (Proof Key for Code Exchange), state nonces, dan postMessage validasi asal untuk mencegah penyadapan kode otorisasi dan pemalsuan permintaan lintas situs.

Mengaktifkan autentikasi Fabric

Tambahkan konfigurasi autentikasi Fabric ke file rayfin/rayfin.yml Anda:

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

Untuk aplikasi yang sudah di-deploy, deploy ulang untuk menerapkan pengaturan yang diperbarui:

npx rayfin up

Untuk aplikasi yang telah diterapkan, npx rayfin up menambahkan URL panggilan balik aplikasi Anda ke allowedRedirectUris.

Menginstal penyedia autentikasi Fabric (opsional)

Proyek yang dibuat menggunakan npm create @microsoft/rayfin@latest sudah menyertakan @microsoft/rayfin-auth-provider-fabric. Instal secara manual hanya jika Anda menambahkan autentikasi Fabric ke proyek yang belum memiliki paket:

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

Fabric SSO menggunakan satu API untuk masuk dan mendaftar: ensureSignedInWithFabric(). Saat pengguna masuk untuk pertama kalinya, Fabric menyediakan sesi Rayfin untuk mereka secara otomatis berdasarkan identitas Microsoft Entra ID mereka—tidak ada panggilan pendaftaran terpisah. Alur kode yang sama digunakan untuk menangani pengguna yang kembali.

Anda dapat menambahkan kode ini secara manual atau menghasilkannya dengan GitHub Copilot di Visual Studio Code.

Panggilan ensureSignedInWithFabric() dari handler gerakan pengguna (misalnya, tombol pilih):

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

Fungsi harus dipanggil dari handler gerakan pengguna yang sinkron untuk menghindari pemblokir popup. Menjalankannya saat halaman dimuat atau dalam rangkaian proses asinkron sebelum interaksi pengguna akan memicu perlindungan pop-up browser.

returnOrigin harus berupa origin dasar (skema dan host, tanpa jalur)—misalnya, https://app.contoso.com. SDK menggunakannya untuk memvalidasi peristiwa masuk postMessage .

Tambahkan keluar dari akun secara manual

Panggil client.auth.signOut() untuk mengakhiri sesi dan menghapus token cache:

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

Berlangganan perubahan sesi untuk memperbarui UI Anda saat masuk atau keluar selesai:

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

Jika Anda menggunakan GitHub Copilot di VS Code, buka Copilot Chat di proyek Fabric Apps Anda dan gunakan prompt seperti berikut untuk menyusun kerangka kode autentikasi. Copilot mengikuti pola yang ada pada skill Rayfin yang disertakan dengan ekstensi Fabric VS Code.

Maksud	Contoh perintah Copilot
Menambahkan tombol masuk	`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.`
Menambahkan tombol keluar	`Add a Sign out button that calls client.auth.signOut() and updates the UI when the session ends.`
Tambahkan hook React yang memahami autentikasi	`Create a useFabricAuth React hook that exposes session, signIn, signOut, and isAuthenticated, using ensureSignedInWithFabric and client.auth.onSessionChange.`
Dukungan untuk mode tersemat	`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.`
Batasi akses ke rute	`Wrap the /dashboard route so it calls ensureSignedInWithFabric before rendering and redirects unauthenticated users to a sign-in page.`

Setelah Copilot menghasilkan kode, tinjau pengeditan dan pastikan:

Panggilan ensureSignedInWithFabric() berjalan di dalam handler gerakan pengguna (misalnya, onClick)—bukan pada pemuatan halaman.
returnOrigin adalah origin dasar dan sesuai dengan salah satu entri di allowedRedirectUris dalam rayfin/rayfin.yml.
Impor berasal dari @microsoft/rayfin-auth-provider-fabric (bukan pembantu panggilan balik yang tidak digunakan lagi).

Menggunakan mode tersemat di dalam iframe Fabric

Saat aplikasi Anda dimuat di dalam iframe Fabric (misalnya, saat pengguna membukanya dari portal Fabric), gunakan mode tersemat alih-alih alur popup:

Mode tersemat memperoleh sesi melalui postMessage dari frame induk.
Ini tidak membuka popup dan tidak memerlukan gerakan pengguna, sehingga aman untuk memanggil pemuatan halaman.
SDK mendeteksi mode tersemat secara otomatis dari ?fabricEmbedded=true dalam URL. Anda juga dapat memaksanya dengan mengatur fabricEmbedded: true dalam opsi.

Panggil initEmbeddedAuth() di awal startup aplikasi:

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() mengembalikan null saat aplikasi tidak berjalan dalam mode tersemat, sehingga aman untuk dipanggil tanpa syarat. ensureSignedInWithFabric() juga mencoba mode terintegrasi secara otomatis sebelum beralih ke alur pop-up.

Menggunakan autentikasi Fabric di React

Buat hook kustom yang mengintegrasikan masuk, mendaftar, dan keluar:

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

Gunakan kait di komponen Anda:

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

Referensi API

ensureSignedInWithFabric

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

Menerapkan air terjun autentikasi empat langkah:

Mengembalikan sesi yang ada jika sudah diautentikasi.
Mencoba melakukan penyegaran senyap melalui token penyegaran.
Mode tertanam—jika berjalan di dalam iframe Fabric, mendapatkan sesi melalui postMessage dari frame induk.
Membuka portal Fabric di jendela pop-up (alur pop-up) dan menunggu postMessage pengalihan.

Langkah ke-1 sampai ke-3 aman untuk dipanggil saat halaman dimuat. Langkah 4 membuka jendela pop-up dan harus dijalankan dalam penanganan gestur pengguna.

FabricAuthOptions

Property	Tipe	Deskripsi
`workspaceId`	`string`	ID ruang kerja Fabric.
`projectId`	`string`	ID item aplikasi Fabric.
`fabricPortalUrl`	`string`	URL dasar portal Fabric (misalnya, `https://app.fabric.microsoft.com`).
`returnOrigin`	`string`	Sumber asal aplikasi Anda untuk pengiriman `postMessage` (misalnya, `window.location.origin`). Harus berupa origin murni (skema dan host, tanpa path).
`fabricEmbedded`	`boolean` (pilihan)	Paksa mode tersemat. Terdeteksi secara otomatis dari `?fabricEmbedded=true` dalam URL.

Fungsi pembantu

Function	Deskripsi
`initEmbeddedAuth(auth, options)`	Autentikasi tersemat yang aman saat pemuatan halaman. Mengembalikan sesi jika berjalan di dalam iframe Fabric, atau `null` jika tidak.
`initiateFabricLogin(auth, options)`	Aliran popup tingkat rendah. Membuka portal Fabric di jendela pop-up dengan parameter PKCE dan mendeteksi handoff `postMessage`.
`isEmbeddedMode(options)`	Mengembalikan `true` jika aplikasi berjalan dalam mode tersemat (Fabric iframe).

Fitur keamanan

PKCE S256 – Setiap alur menghasilkan pemverifikasi kode kriptografi dan tantangan untuk mencegah penyadapan kode otorisasi.
Nonce status – Nonce acak mengaitkan respons handoff dengan tab asal, sehingga mencegah pemalsuan permintaan lintas situs.
postMessage validasi asal – SDK memvalidasi event.origin pesan masuk dan menolak pesan dari asal yang tidak terduga.
Pembersihan otomatis – state PKCE kedaluwarsa setelah 5 menit dan akan dibersihkan saat alur berikutnya berjalan.
Batas waktu alur – Waktu alur popup habis setelah 5 menit jika tidak ada pesan handoff yang diterima.

Memecahkan masalah autentikasi

Browser memblokir jendela portal Fabric. Pastikan ensureSignedInWithFabric() dipanggil dari handler gerakan pengguna sinkron (misalnya, tombol onClick). Jangan memanggilnya saat halaman dimuat atau di dalam rangkaian asinkron sebelum interaksi pengguna.

Sesi tidak bertahan

Pastikan RayfinClient dikonfigurasi dengan baseUrl dan publishableKey yang benar. Tab panggilan balik dan tab asli harus berbagi asal yang sama untuk BroadcastChannel dan localStorage agar berfungsi.

Autentikasi gagal setelah penundaan panjang

Proses masuk akan kedaluwarsa setelah 5 menit. Jika Anda memulai proses masuk tetapi tidak menyelesaikannya dalam waktu tersebut, alur gagal. Tutup popup dan pilih lagi tombol masuk untuk memulai alur baru.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-06-02