Ρύθμιση παραμέτρων ελέγχου ταυτότητας Fabric SSO για την εφαρμογή Fabric

Ρυθμίστε την καθολική σύνδεση (SSO) Fabric για μια εφαρμογή Fabric, ώστε οι χρήστες να μπορούν να συνδεθούν με το Microsoft Entra ID μέσω της πύλης Fabric. Αυτό το άρθρο εξηγεί τη ροή παράδοσης και δείχνει πώς μπορείτε να ενεργοποιήσετε την απαιτούμενη ρύθμιση παραμέτρων και την ενοποίηση SDK για αναπτυγμένες εφαρμογές.

Προϋποθέσεις

Ένα έργο Fabric Apps με ενεργοποιημένο τον έλεγχο ταυτότητας. Δείτε Διαμόρφωση ελέγχου ταυτότητας.
Ένα αναπτυγμένο στοιχείο Fabric Apps. Δείτε Ανάπτυξη σε Fabric.

Πώς λειτουργεί το Fabric SSO

Fabric καθολική σύνδεση (SSO) χρησιμοποιεί μια ασφαλή παράδοση βάσει postMessage μεταξύ της εφαρμογής σας και της πύλης Fabric. Δεν υπάρχει σελίδα ανακατεύθυνσης ή επανάκλησης:

Η εφαρμογή σας ανοίγει την πύλη Fabric σε ένα αναδυόμενο παράθυρο και καταχωρεί έναν ακροατή postMessage.
Ο χρήστης πραγματοποιεί έλεγχο ταυτότητας μέσω του Microsoft Entra ID εντός της πύλης Fabric.
Η επέκταση Fabric στέλνει τον κωδικό παράδοσης πίσω στην εφαρμογή σας μέσω window.opener.postMessage().
Το SDK ανταλλάσσει τον κωδικό παράδοσης για διακριτικά περιόδου λειτουργίας Rayfin και δημιουργεί μια περίοδο λειτουργίας.
Το αναδυόμενο παράθυρο Fabric κλείνει αυτόματα.

Η ροή είναι ασφαλής με PKCE (Proof Key for Code Exchange), state nonces και επικύρωση προέλευσης postMessage για να αποτραπεί η υποκλοπή κωδικού εξουσιοδότησης και η πλαστογράφηση αιτημάτων μεταξύ τοποθεσιών.

Ενεργοποίηση ελέγχου ταυτότητας Fabric

Προσθέστε τη διαμόρφωση ελέγχου ταυτότητας Fabric στο αρχείο rayfin/rayfin.yml:

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

Για εφαρμογές που έχουν αναπτυχθεί, αναπτύξτε ξανά για να προωθήσετε τις ενημερωμένες ρυθμίσεις:

npx rayfin up

Για εφαρμογές που έχουν αναπτυχθεί, npx rayfin up το προσθέτει τη διεύθυνση URL επιστροφής κλήσης της εφαρμογής που έχετε αναπτύξει στο allowedRedirectUris.

Εγκατάσταση της υπηρεσίας παροχής ελέγχου ταυτότητας Fabric (προαιρετικό)

Τα έργα με npm create @microsoft/rayfin@latest σκαλωσιές περιλαμβάνουν @microsoft/rayfin-auth-provider-fabricήδη. Εγκαταστήστε το με μη αυτόματο τρόπο μόνο εάν προσθέτετε έλεγχο ταυτότητας Fabric σε ένα έργο που δεν έχει ήδη το πακέτο:

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

Fabric SSO χρησιμοποιεί ένα μόνο API τόσο για την είσοδο όσο και για την εγγραφή: ensureSignedInWithFabric(). Όταν ένας χρήστης συνδέεται για πρώτη φορά, το Fabric παρέχει αυτόματα μια περίοδο λειτουργίας Rayfin για αυτόν με βάση την ταυτότητα του Microsoft Entra ID—δεν υπάρχει ξεχωριστή κλήση εγγραφής. Η ίδια διαδρομή κώδικα χειρίζεται τους χρήστες που επιστρέφουν.

Μπορείτε να προσθέσετε αυτόν τον κώδικα με το χέρι ή να τον δημιουργήσετε με το GitHub Copilot στο VS Code.

Κλήση ensureSignedInWithFabric() από έναν χειριστή χειρονομιών χρήστη (για παράδειγμα, μια επιλογή κουμπιού):

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

Η συνάρτηση πρέπει να καλείται από έναν σύγχρονο χειριστή χειρονομιών χρήστη για να αποφευχθούν οι αποκλεισμοί αναδυόμενων παραθύρων. Η κλήση του κατά τη φόρτωση της σελίδας ή μέσα σε μια ασύγχρονη αλυσίδα πριν από την αλληλεπίδραση με τον χρήστη ενεργοποιεί την προστασία αναδυόμενων παραθύρων του προγράμματος περιήγησης.

returnOrigin πρέπει να είναι γυμνή αρχή (σχήμα και κεντρικός υπολογιστής, χωρίς διαδρομή)—για παράδειγμα, https://app.contoso.com. Το SDK το χρησιμοποιεί για την επικύρωση εισερχόμενων postMessage συμβάντων.

Προσθήκη αποσύνδεσης με μη αυτόματο τρόπο

Κλήση client.auth.signOut() για τερματισμό της συνεδρίας και εκκαθάριση διακριτικών στην κρυφή μνήμη:

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

Εγγραφείτε στις αλλαγές περιόδων σύνδεσης, για να ενημερώσετε το περιβάλλον εργασίας χρήστη όταν ολοκληρωθεί η είσοδος ή η έξοδος:

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

Εάν χρησιμοποιείτε GitHub Copilot στο VS Code, ανοίξτε Copilot Chat στο έργο Fabric Apps και χρησιμοποιήστε προτροπές όπως αυτές για να δημιουργήσετε τον κώδικα ελέγχου ταυτότητας. Το Copilot ακολουθεί τα μοτίβα της δεξιότητας Rayfin που συνοδεύει την επέκταση Fabric VS Code.

Στόχος	Παράδειγμα προτροπή Copilot
Προσθήκη κουμπιού σύνδεσης	`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.`
Προσθήκη κουμπιού αποσύνδεσης	`Add a Sign out button that calls client.auth.signOut() and updates the UI when the session ends.`
Προσθέστε ένα άγκιστρο React με επίγνωση ελέγχου ταυτότητας	`Create a useFabricAuth React hook that exposes session, signIn, signOut, and isAuthenticated, using ensureSignedInWithFabric and client.auth.onSessionChange.`
Υποστήριξη ενσωματωμένης λειτουργίας	`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.`
Πύλη διαδρομής	`Wrap the /dashboard route so it calls ensureSignedInWithFabric before rendering and redirects unauthenticated users to a sign-in page.`

Αφού το Copilot δημιουργήσει κώδικα, ελέγξτε τις αλλαγές και βεβαιωθείτε:

Η ensureSignedInWithFabric() κλήση εκτελείται μέσα σε ένα πρόγραμμα χειρισμού χειρονομιών χρήστη (για παράδειγμα, onClick) - όχι κατά τη φόρτωση της σελίδας.
returnOriginείναι μια γυμνή προέλευση και ταιριάζει με μία από τις καταχωρήσεις στο allowedRedirectUris .rayfin/rayfin.yml
Οι εισαγωγές προέρχονται από @microsoft/rayfin-auth-provider-fabric (όχι τους καταργημένους βοηθούς επανάκλησης).

Χρήση ενσωματωμένης λειτουργίας μέσα σε ένα iframe Fabric

Όταν η εφαρμογή σας φορτώνεται μέσα σε ένα iframe Fabric (για παράδειγμα, όταν ένας χρήστης την ανοίγει από την πύλη Fabric), χρησιμοποιήστε την ενσωματωμένη λειτουργία αντί για την αναδυόμενη ροή:

Η λειτουργία Embedded μεταφέρει τη συνεδρία στο postMessage γονικό πλαίσιο.
Δεν ανοίγει αναδυόμενο παράθυρο και δεν απαιτεί χειρονομία χρήστη, επομένως είναι ασφαλές να καλέσετε κατά τη φόρτωση της σελίδας.
Το SDK εντοπίζει αυτόματα την ενσωματωμένη λειτουργία από ?fabricEmbedded=true το URL. Μπορείτε επίσης να το αναγκάσετε ορίζοντας fabricEmbedded: true τις επιλογές.

Καλέστε initEmbeddedAuth() νωρίς κατά την εκκίνηση της εφαρμογής:

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() Επιστρέφει null όταν η εφαρμογή δεν εκτελείται σε ενσωματωμένη λειτουργία, επομένως είναι ασφαλές να καλέσετε άνευ όρων. ensureSignedInWithFabric() Επίσης, επιχειρεί αυτόματα την ενσωματωμένη λειτουργία πριν επιστρέψει στην αναδυόμενη ροή.

Χρήση ελέγχου ταυτότητας Fabric στο React

Δημιουργήστε ένα προσαρμοσμένο άγκιστρο που ενσωματώνει την είσοδο, την εγγραφή και την έξοδο:

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

Χρησιμοποιήστε το άγκιστρο στα εξαρτήματά σας:

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

εξασφαλίστεSignedInWithFabric

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

Υλοποιεί έναν καταρράκτη ελέγχου ταυτότητας τεσσάρων βημάτων:

Επιστρέφει την υπάρχουσα συνεδρία εάν έχει ήδη γίνει έλεγχος ταυτότητας.
Επιχειρεί μια αθόρυβη ανανέωση μέσω του διακριτικού ανανέωσης.
Ενσωματωμένη λειτουργία—Εάν εκτελείται μέσα σε ένα Fabric iframe, αποκτά τη συνεδρία μέσω postMessage στο γονικό πλαίσιο.
Ανοίγει την πύλη Fabric σε ένα αναδυόμενο παράθυρο (αναδυόμενη ροή) και περιμένει την παράδοση postMessage.

Τα βήματα 1 έως 3 είναι ασφαλή για κλήση κατά τη φόρτωση της σελίδας. Το βήμα 4 ανοίγει ένα αναδυόμενο παράθυρο και πρέπει να εκτελείται μέσα σε έναν χειριστή χειρονομιών χρήστη.

Επιλογές FabricAuthOptions

Ιδιοκτησία	Δακτυλογραφώ	Περιγραφή
`workspaceId`	`string`	Το αναγνωριστικό χώρου εργασίας Fabric.
`projectId`	`string`	Το αναγνωριστικό στοιχείου της εφαρμογής Fabric.
`fabricPortalUrl`	`string`	Η βασική διεύθυνση URL της πύλης Fabric (για παράδειγμα, `https://app.fabric.microsoft.com`).
`returnOrigin`	`string`	Την προέλευση της εφαρμογής σας για `postMessage` την προβολή (για παράδειγμα, `window.location.origin`). Πρέπει να είναι γυμνή προέλευση (σχήμα και κεντρικός υπολογιστής, χωρίς μονοπάτι).
`fabricEmbedded`	`boolean` (προαιρετικός)	Αναγκαστική ενσωματωμένη λειτουργία. Αυτόματος εντοπισμός από `?fabricEmbedded=true` το URL.

Βοηθητικές λειτουργίες

Συνάρτηση	Περιγραφή
`initEmbeddedAuth(auth, options)`	Ενσωματωμένος έλεγχος ταυτότητας με ασφάλεια φόρτωσης σελίδας. Επιστρέφει την περίοδο λειτουργίας εάν εκτελείται μέσα σε ένα Fabric iframe ή `null` διαφορετικά.
`initiateFabricLogin(auth, options)`	Αναδυόμενη ροή χαμηλού επιπέδου. Ανοίγει την πύλη Fabric σε ένα αναδυόμενο παράθυρο με παραμέτρους PKCE και ακούει την παράδοση `postMessage`.
`isEmbeddedMode(options)`	Επιστρέφει `true` εάν η εφαρμογή εκτελείται σε ενσωματωμένη λειτουργία (Fabric iframe).

Δυνατότητες ασφαλείας

PKCE S256 – Κάθε ροή δημιουργεί έναν επαληθευτή κρυπτογραφικού κώδικα και πρόκληση για την αποτροπή υποκλοπής κωδικού εξουσιοδότησης.
Κατάσταση nonce – Ένα τυχαίο nonce συνδέει την απόκριση παράδοσης με την καρτέλα προέλευσης, αποτρέποντας την πλαστογράφηση αιτημάτων μεταξύ τοποθεσιών.
postMessage επικύρωση προέλευσης – Το SDK επικυρώνει event.origin τα εισερχόμενα μηνύματα και απορρίπτει μηνύματα από μη αναμενόμενες προελεύσεις.
Αυτόματος καθαρισμός – Η κατάσταση PKCE λήγει μετά από 5 λεπτά και συλλέγεται από τα σκουπίδια στην επόμενη ροή.
Χρονικό όριο ροής – Το χρονικό όριο της αναδυόμενης ροής λήγει μετά από 5 λεπτά, εάν δεν ληφθεί μήνυμα παράδοσης.

Αντιμετώπιση προβλημάτων ελέγχου ταυτότητας

Το πρόγραμμα περιήγησης απέκλεισε το παράθυρο της πύλης Fabric. Βεβαιωθείτε ότι ensureSignedInWithFabric() καλείται από ένα σύγχρονο πρόγραμμα χειρισμού χειρονομιών χρήστη (για παράδειγμα, κουμπί onClick). Μην το καλείτε κατά τη φόρτωση της σελίδας ή μέσα σε μια ασύγχρονη αλυσίδα πριν από την αλληλεπίδραση με τον χρήστη.

Η συνεδρία δεν επιμένει

Επιβεβαιώστε ότι το RayfinClient έχει ρυθμιστεί με το σωστό baseUrl και publishableKey. Η καρτέλα επιστροφής κλήσης και η αρχική καρτέλα πρέπει να έχουν την ίδια προέλευση και BroadcastChannellocalStorage να λειτουργούν.

Ο έλεγχος ταυτότητας αποτυγχάνει μετά από μεγάλη καθυστέρηση

Η ροή εισόδου λήγει μετά από 5 λεπτά. Εάν ξεκινήσετε τη διαδικασία εισόδου, αλλά δεν την ολοκληρώσετε εντός αυτού του χρονικού διαστήματος, η ροή αποτυγχάνει. Κλείστε το αναδυόμενο παράθυρο και επιλέξτε ξανά το κουμπί εισόδου για να ξεκινήσετε μια νέα ροή.

Σχόλια

Ήταν χρήσιμη αυτή η σελίδα;

Last updated on 2026-06-02