Authentifizierung für Fabric Apps

Fabric Apps enthält einen integrierten Authentifizierungsdienst, der Benutzer anmeldet, ihre Sitzungen verwaltet und ihre Identität jedem Von Ihrer App ausgeführten Daten- und Speicheranruf anfügt. In diesem Artikel werden die Konzepte erläutert, die Sie verstehen müssen, bevor Sie die Authentifizierung für Ihr Projekt konfigurieren.

Details zur Implementierung finden Sie unter:

Authentifizierungsmodi

Bereitgestellte Fabric-Apps authentifizieren sich mit Microsoft Entra ID. Wählen Sie den Integrationspfad basierend darauf, wo die App läuft und wer das Entra-Token erwirbt:

Umgebung Unterstützte Methode Wann wird es verwendet?
Browser-App über das Fabric-Portal Fabric SSO-Popup oder eingebettete Handoff Lassen Sie Fabric interaktive Anmeldungen durchführen oder sich bei einer in Fabric eingebetteten App anmelden.
Browser oder Node.js App, die bereits einen delegierten Entra-Token hat. signInWithEntraToken() Tauschen Sie den bereitgestellten Token gegen eine Rayfin-Sitzung ohne Popup oder Weiterleitung aus.
In ein externes übergeordnetes Portal eingebettete App createEmbedHost() im übergeordneten Element und initEmbeddedAuth() im iframe Lassen Sie einen vertrauenswürdigen, von Entra authentifizierten übergeordneten Broker eine Übergabe vermitteln, ohne sein Token an das iframe zu senden.
Lokale Entwicklung mit lokalem Backend E-Mail und Kennwort Testen Sie mit einem lokalen Backend; diese Methode funktioniert auf einem bereitgestellten Fabric-Backend nicht.

Wichtige Konzepte:

  • Fabric SSO verwendet das Fabric-Portal, um einen Browserbenutzer zu authentifizieren. Die App kann innerhalb von Fabric laufen oder ein Popup von einer eigenständigen Seite verwenden, einschließlich eines lokalen Frontends, das auf ein bereitgestelltes Backend abzielt.
  • Direkter Entra-Austausch und External-Parent-Host-Handoff sind zusätzliche Microsoft Entra-Pfade, keine Unterstützung für beliebige Identitätsanbieter oder die Anmeldung von Serviceprinzipalen nur für Apps.
  • E-Mail und Kennwort sind nur für die lokale Entwicklung vorgesehen. Sie funktioniert nach der Bereitstellung nicht.
  • Die erstmalige Anmeldung stellt den Benutzer fest. Mit Fabric SSO gibt es keinen separaten Registrierungsschritt – Benutzer werden automatisch beim ersten Anmelden erstellt.
  • Die Authentifizierung ist für Fabric Bereitstellungen erforderlich. Das Festlegen von services.auth.enabled auf false führt dazu, dass npx rayfin up fehlschlägt.

Für Tokenanforderungen und Implementierungsbeispiele siehe Direct Entra Token Sign-in und Embed in einem externen Elternportal.

Sitzungen und Identität

Nachdem sich ein Benutzer angemeldet hat, erstellt das SDK eine Sitzung , die den angemeldeten Benutzer darstellt. Sitzungen sind undurchsichtig – Ihre App sollte die zugrunde liegenden Token nicht prüfen. Stattdessen liest Ihre App eine kleine Gruppe von allgemeinen Eigenschaften vor:

  • Gibt an, ob eine Sitzung aktuell authentifiziert ist.
  • Die id und email des Benutzers.
  • Benutzerdefinierte Ansprüche, die Sie in rayfin.yml konfiguriert haben.

Die gleiche Clientinstanz, die den Benutzer automatisch anmeldet, fügt seine Identität jedem Daten- und Speicheraufruf an. Sie reichen Token nicht manuell weiter.

Sitzungen lösen auch Änderungsereignisse aus, sodass Ihre Benutzeroberfläche reagieren kann, wenn sich ein Benutzer anmeldet oder sich abmeldet, ohne die Seite neu zu laden.

Für serverseitige Integrationen verwenden Sie pro Benutzer einen separaten Client und eine ausschließlich im Speicher gehaltene Auth Sitzung (authStorage: false auf RayfinClient, oder { storage: false } auf Auth). Teilen Sie niemals einen veränderbaren, angemeldeten Client zwischen Benutzern. Zerstöre die Authentifizierungsinstanz, wenn ihre Anfrage oder ihr benutzerspezifischer Geltungsbereich endet.

Aktivieren der Authentifizierung in Ihrem Projekt

Die Authentifizierung wird in rayfin/rayfin.yml konfiguriert. Im folgenden Beispiel werden sowohl Fabric SSO (für bereitgestellte Apps) als auch die E-Mail-/Kennwortanmeldung (für die lokale Entwicklung) aktiviert:

services:
  auth:
    enabled: true
    allowedRedirectUris:
      - http://localhost:5173
    fabric:
      enabled: true
      externalEntraExchange: true
    password:
      enabled: true  # Local development only

Wofür die einzelnen Einstellungen zuständig sind:

  • services.auth.enabled – Aktiviert den Authentifizierungsdienst. Erforderlich für jede Fabric-Bereitstellung.
  • allowedRedirectUris – Die Origins, an die der Benutzer nach der Anmeldung weitergeleitet werden darf. Fügen Sie hier Ihre lokale Dev-URL hinzu. npx rayfin up fügt den bereitgestellten App-Ursprung automatisch hinzu.
  • fabric.enabled – Aktiviert Fabric SSO. Erforderlich für bereitgestellte Apps.
  • fabric.externalEntraExchange – Ermöglicht den direkten delegierten Austausch von Entra-Tokens und die Übergabe an den externen übergeordneten Host. Auch die Ziel-Fabric-Umgebung muss den Austausch unterstützen.
  • password.enabled – Ermöglicht die E-Mail- und Kennwortanmeldung für die lokale Entwicklung.

Important

Für Fabric-Bereitstellungen muss die Authentifizierung aktiviert sein. npx rayfin up schlägt fehl, wenn services.auth.enabled auf false gesetzt ist.

Starten Sie nach dem Bearbeiten von rayfin.yml das lokale Backend neu, oder führen Sie npx rayfin up aus, um die Änderung anzuwenden.

Voraussetzungen für extern erworbene Entra-Token

Direkter Austausch und Authentifizierung über externen übergeordneten Host erfordern ein delegiertes Benutzertoken für die Fabric/Power BI-Audience, die von der Zielbereitstellung akzeptiert wird und mit Item.Execute.All im Besitzertenant des Elements ausgestellt wird. Der Benutzer muss außerdem die Berechtigung „Ausführen“ für das App-Element haben. App-only-Token werden von diesen Anmeldepfaden nicht unterstützt.

Ihre Authentifizierungsbibliothek erhält das Token und verwaltet die Einwilligung. Das Rayfin SDK tauscht es gegen eine Rayfin-Sitzung ein; es erwirbt das Entra-Token nicht. Browser-Anrufer benötigen außerdem, dass die CORS-Richtlinie des Dienstes den Ursprung und den Autorisierungsheader zulässt.

Benutzerdefinierte Ansprüche

Mit benutzerdefinierten Claims können Sie jeder Sitzung anwendungsspezifische Metadaten hinzufügen, z. B. einen Mandantennamen, ein Feature-Flag oder eine App-Version. Sie sind nützlich für rollenbasierte Zugriffssteuerung und Feature-Gating, ohne Ihr Datenmodell zu ändern.

services:
  auth:
    enabled: true
    customClaims:
      tenant: default
      app_version: 1.0.0

Benutzerdefinierte Ansprüche werden innerhalb des Sitzungsobjekts angezeigt und können über Ihre Datenberechtigungsregeln referenziert werden.

Was das SDK bereitstellt

Wenn Sie das RayfinClient verwenden, ist der Authentifizierungsdienst unter client.auth verfügbar. Auf konzeptioneller Ebene bietet es Folgendes:

  • Registrieren und Anmelden mit E-Mail und Kennwort während der lokalen Entwicklung.
  • Sign-in und Registrieren über Fabric SSO für bereitgestellte Apps. Derselbe Anruf behandelt sowohl neue als auch zurückgegebene Benutzer.
  • Direkter delegierter Entra-Token-Austausch im Browser- oder Node.js-Code sowie eine Übergabe an einen vertrauenswürdigen externen übergeordneten Host für eingebettete Apps.
  • Melden Sie sich ab, um die aktuelle Sitzung zu beenden.
  • Sitzungsabfragen und Abonnements, sodass Ihre Benutzeroberfläche mit dem Authentifizierungsstatus des Benutzers synchron bleibt.

Für den Code, der diese Funktionen in eine echte App einbindet, siehe Configure Fabric SSO authentication for your Fabric App. Für Hinweise zur Callback- und Handoff-Erlaubnisliste siehe Konfigurieren von Authentifizierungs-Redirect-URIs.

Verwandte Inhalte

  • Zuletzt aktualisiert um