Fabric uygulamanız için Fabric SSO kimlik doğrulamasını yapılandırma

Kullanıcıların Fabric portalı üzerinden Microsoft Entra ID ile oturum açabilmesi için Fabric bir uygulama için Fabric çoklu oturum açma (SSO) ayarlayın. Bu makalede, iletim akışı açıklanır ve dağıtılan uygulamalar için gerekli yapılandırma ve SDK tümleştirmesinin nasıl etkinleştirileceği gösterilir.

Prerequisites

Fabric SSO nasıl çalışır?

Fabric çoklu oturum açma (SSO), uygulamanızla Fabric portalı arasında güvenli postMessage tabanlı bir iletim kullanır. Yeniden yönlendirme veya geri çağırma sayfası yok:

  1. Uygulamanız Fabric portalını açılır pencerede açar ve bir postMessage dinleyicisi kaydeder.
  2. Kullanıcı, Fabric portalının içindeki Microsoft Entra ID aracılığıyla kimlik doğrulaması yapar.
  3. Fabric uzantısı, window.opener.postMessage() aracılığıyla iletim kodunu uygulamanıza geri gönderir.
  4. SDK, Rayfin oturum belirteçleri için iletim kodunu değiştirir ve bir oturum oluşturur.
  5. Fabric açılır penceresi otomatik olarak kapanır.

Akış, yetkilendirme kodunun ele geçirilmesini ve siteler arası istek sahteciliğini önlemek için PKCE (Kod Değişimi için Kanıt Anahtarı), durum nonce değerleri ve postMessage kaynak doğrulaması ile güvence altına alınır.

Fabric kimlik doğrulamasını etkinleştirme

rayfin/rayfin.yml dosyanıza Fabric kimlik doğrulama yapılandırmasını ekleyin:

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

Dağıtılan uygulamalar için güncelleştirilmiş ayarları göndermek için yeniden dağıtın:

npx rayfin up

Dağıtılmış uygulamalar için npx rayfin up, dağıtılmış uygulamanızın geri çağırma URL’sini allowedRedirectUris öğesine ekler.

Fabric kimlik doğrulama sağlayıcısını yükleme (isteğe bağlı)

npm create @microsoft/rayfin@latest ile oluşturulmuş projeler zaten @microsoft/rayfin-auth-provider-fabric içerir. Yalnızca paketi olmayan bir projeye Fabric kimlik doğrulaması ekliyorsanız el ile yükleyin:

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

Uygulamanıza oturum açma ve kaydolma ekleme

Fabric SSO hem oturum açma hem de kaydolma için tek bir API kullanır: ensureSignedInWithFabric(). Bir kullanıcı ilk kez oturum açtığında Fabric, Microsoft Entra ID kimliğine göre otomatik olarak bir Rayfin oturumu sağlar; ayrı bir kaydolma çağrısı yoktur. Aynı kod akışı geri gelen kullanıcıları da ele alır.

Bu kodu el ile ekleyebilir veya VS Code'da GitHub Copilot ile oluşturabilirsiniz.

Oturum açmayı manuel olarak ekleyin

Kullanıcı hareketi işleyicisinden çağrı ensureSignedInWithFabric() (örneğin, bir düğme seçimi):

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

İşlev, açılır pencere engelleyicilerinden kaçınmak için zaman uyumlu bir kullanıcı hareketi işleyicisinden çağrılmalıdır. Bunun sayfa yüklenirken veya kullanıcı etkileşiminden önce eşzamansız bir zincir içinde çağrılması, tarayıcının açılır pencere korumasını tetikler.

returnOrigin bir çıkış noktası (düzen ve konak, yol yok) olmalıdır; örneğin, https://app.contoso.com. SDK, gelen postMessage olayları doğrulamak için bunu kullanır.

Çıkışı manuel olarak ekleyin

Oturumu sonlandırmak ve önbelleğe alınmış belirteçleri temizlemek için client.auth.signOut() çağırın:

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

Oturum açma veya oturum kapatma tamamlandığında kullanıcı arabiriminizi güncelleştirmek için oturum değişikliklerine abone olun:

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

GitHub Copilot ile oturum açma ve kaydolma oluşturma

VS Code’da GitHub Copilot kullanıyorsanız, Fabric Apps projenizde Copilot Chat’i açın ve kimlik doğrulama kodunun iskeletini oluşturmak için bunun gibi istemleri kullanın. Copilot, Fabric VS Code uzantısıyla birlikte sunulan Rayfin yeteneğindeki kalıpları temel alır.

Goal Örnek Copilot istemi
Oturum açma düğmesi ekleme 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.
Oturum kapatma düğmesi ekleme Add a Sign out button that calls client.auth.signOut() and updates the UI when the session ends.
Kimlik doğrulama farkındalığına sahip React kancası ekleme Create a useFabricAuth React hook that exposes session, signIn, signOut, and isAuthenticated, using ensureSignedInWithFabric and client.auth.onSessionChange.
Ekli modu destekleme 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.
Bir rotayı denetle Wrap the /dashboard route so it calls ensureSignedInWithFabric before rendering and redirects unauthenticated users to a sign-in page.

Copilot kod oluşturduktan sonra düzenlemeleri gözden geçirin ve aşağıdakilerden emin olun:

  • ensureSignedInWithFabric() çağrısı, sayfa yüklenirken değil, bir kullanıcı hareketi işleyicisi içinde (örneğin, onClick) çalışır.
  • returnOrigin, yalın bir origin’dir ve rayfin/rayfin.yml içindeki allowedRedirectUris girdilerinden biriyle eşleşir.
  • İçe aktarımlar @microsoft/rayfin-auth-provider-fabric üzerinden yapılır (kullanım dışı bırakılan geri çağırma yardımcılarından değil).

Fabric iframe içinde katıştırılmış modu kullanma

Uygulamanız bir Fabric iframe içine yüklendiğinde (örneğin, bir kullanıcı Fabric portalından açtığında), açılır akış yerine katıştırılmış modu kullanın:

  • Katıştırılmış mod, oturumu üst çerçeve üzerinden postMessage edinir.
  • Açılır pencere oluşturmaz ve kullanıcı etkileşimi gerektirmez, bu nedenle sayfa yüklenirken çağrılması güvenlidir.
  • SDK, URL'deki ?fabricEmbedded=true ifadesinden gömülü modu otomatik olarak algılar. Bunu, seçeneklerde fabricEmbedded: true ayarlayarak da zorlayabilirsiniz.

initEmbeddedAuth() öğesini uygulama başlatma sırasında erken çağırı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() uygulama ekli modda çalışmadığında döndürür null , bu nedenle koşulsuz çağrı yapmak güvenlidir. ensureSignedInWithFabric() ayrıca, açılır pencere akışına başvurmadan önce gömülü modu otomatik olarak dener.

React'te Fabric kimlik doğrulamayı kullanma

Oturum açma, kaydolma ve çıkış yapma işlemlerini entegre eden özel bir kanca oluşturun:

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

Bileşenlerinizde kancayı kullanın:

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

API referansı

ensureSignedInWithFabric

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

Dört aşamalı kimlik doğrulama şelalesi uygular:

  1. Zaten kimlik doğrulaması yapılmışsa mevcut oturumu döndürür.
  2. Yenileme belirteci aracılığıyla sessiz yenilemeyi dener.
  3. Gömülü mod—Fabric bir iframe içinde çalışıyorsa, oturumu üst çerçeveden postMessage aracılığıyla edinir.
  4. Fabric portalını açılır pencerede açar (açılır akış) ve postMessage iletimini bekler.

1'den 3'e kadar olan adımlar, sayfa yüklenirken güvenle çağrılabilir. 4. Adım bir açılır pencere açar ve kullanıcı hareketi işleyicisi içinde çalıştırılmalıdır.

FabricAuthOptions

Property Türü Description
workspaceId string Fabric çalışma alanı kimliği.
projectId string Fabric uygulama öğesinin kimliği.
fabricPortalUrl string Fabric portalı temel URL'si (örneğin, https://app.fabric.microsoft.com).
returnOrigin string postMessage sunumu için uygulamanızın kaynağı (örneğin, window.location.origin). Yalnızca bir origin olmalıdır (şema ve ana makine, yol içermeyen).
fabricEmbedded boolean (isteğe bağlı) Gömülü modu zorla. URL'den ?fabricEmbedded=true otomatik olarak algılandı.

Yardımcı işlevler

Function Description
initEmbeddedAuth(auth, options) Sayfa yükleme sırasında güvenli gömülü kimlik doğrulama. Fabric iframe'i içinde çalışıyorsa oturumu, aksi takdirde null döndürür.
initiateFabricLogin(auth, options) Düşük düzey açılır pencere akışı. Fabric portalını PKCE parametreleri içeren bir açılır pencerede açar ve postMessage iletimini dinler.
isEmbeddedMode(options) Uygulama katıştırılmış modda (Fabric iframe) çalışıyorsa true döndürür.

Güvenlik özellikleri

  • PKCE S256 – Her akış, yetkilendirme kodunun ele geçirilmesini önlemek için kriptografik bir kod doğrulayıcısı ve sorgulaması oluşturur.
  • Durum belirteci (nonce) – Rastgele bir nonce, devir yanıtını isteğin başlatıldığı sekmeye bağlayarak siteler arası istek sahteciliğini önler.
  • postMessage kaynak doğrulama – SDK, gelen iletileri doğrular event.origin ve beklenmeyen kaynaklardan gelen iletileri reddeder.
  • Otomatik temizleme – PKCE durumunun süresi 5 dakika sonra dolar ve bir sonraki akışta çöp toplanır.
  • Akış zaman aşımı – Devir mesajı alınmazsa açılır pencere akışı 5 dakika sonra zaman aşımına uğrar.

Kimlik doğrulaması sorunlarını giderme

Tarayıcı Fabric portalı penceresini engelledi. ensureSignedInWithFabric() öğesinin eşzamanlı bir kullanıcı etkileşimi işleyicisinden (örneğin, düğme onClick) çağrıldığından emin olun. Kullanıcı etkileşiminden önce, sayfa yüklenirken veya bir asenkron zincir içinde bunu çağırmayın.

Oturum kalıcı değil

RayfinClient doğru baseUrl ve publishableKey ile yapılandırıldığını onaylayın. BroadcastChannel ve localStorage öğelerinin çalışabilmesi için geri çağırma sekmesi ile orijinal sekmenin aynı kaynağı paylaşması gerekir.

Kimlik doğrulaması uzun bir gecikmeden sonra başarısız oluyor

Oturum açma akışının süresi 5 dakika sonra sona erer. Oturum açma işlemini başlatır ancak bu süre içinde tamamlayamazsanız akış başarısız olur. Yeni bir akış başlatmak için açılan menüyi kapatın ve yeniden oturum açma düğmesini seçin.

İlgili içerik

  • Last updated on