Generieren eines Einbettungstokens

  • Artikel

GILT FÜR: Die App besitzt die Daten Der Benutzer besitzt die Daten

Token generieren ist eine REST-API, mit der Sie ein Token zum Einbetten eines Power BI-Berichts oder semantischen Modells in eine Web-App oder ein Portal generieren können. Sie kann ein Token für ein einzelnes Element oder für mehrere Berichte oder semantische Modelle generieren. Mithilfe des Tokens wird Ihre Anforderung für den Power BI-Dienst autorisiert.

Die API „Token generieren“ verwendet zum Generieren eines Tokens für einen einzelnen Benutzer eine einzelne Identität (Hauptbenutzer oder Dienstprinzipal), die von den Anmeldeinformationen des Benutzers in der App (effektive Identität) abhängig ist.

Nach erfolgreicher Authentifizierung wird der Zugriff auf die entsprechenden Daten gewährt.

Hinweis

Token generieren ist die neuere API, Version 2, die sowohl für Berichte und semantische Modelle als auch für einzelne oder mehrere Elemente funktioniert. Sie wird gegenüber den Legacy-APIs der Version 1 bevorzugt. Verwenden Sie für Dashboards und Kacheln Dashboards GenerateTokenInGroup und Kacheln GenerateTokenInGroup von V1.

Schützen Ihrer Daten

Wenn Sie Daten von mehreren Kunden verarbeiten, gibt es zwei Hauptansätze zum Sichern Ihrer Daten: Workspace-basierte Isolierung und sicherheitsbasierte Isolierung auf Zeilenebene. Sie finden einen detaillierten Vergleich zwischen beiden unter Dienstprinzipalprofile und Sicherheit auf Zeilenebene.

Wir empfehlen die Verwendung der Workspace-basierten Isolierung mit Profilen, aber wenn Sie den RLS-Ansatz verwenden möchten, lesen Sie den RLS-Abschnitt am Ende dieses Artikels.

Token-Berechtigungen und Sicherheit

In den APIs zum Generieren von Token werden die Tokenberechtigungen im Abschnitt GenerateTokenRequest definiert.

Zugriffsebene

  • Verwenden Sie den Parameter allowEdit, um dem Benutzer Anzeige- oder Bearbeitungsberechtigungen zu gewähren.

  • Fügen Sie dem Einbettungstoken die Arbeitsbereichs-ID hinzu, damit der Benutzer neue Berichte (entweder SaveAs oder CreateNew) in diesem Arbeitsbereich erstellen kann.

Sicherheit auf Zeilenebene

Bei Sicherheit auf Zeilenebene (Row Level Security, RLS) kann die verwendete Identität von der Identität des Dienstprinzipals oder Hauptbenutzers abweichen, die Sie zum Generieren des Tokens verwenden. Durch die Verwendung verschiedener Identitäten können Sie eingebettete Informationen für den Zielbenutzer anzeigen. Sie können den Benutzer beispielsweise in Ihrer Anwendung auffordern, sich anzumelden, und dann einen Bericht anzeigen, der nur dann Verkaufsinformationen enthält, wenn der angemeldete Benutzer ein Vertriebsmitarbeiter ist.

Wenn Sie RLS verwenden, kann unter Umständen die Identität des Benutzers (der Parameter EffectiveIdentity) fortgelassen werden. Wenn Sie den Parameter EffectiveIdentity nicht verwenden, hat das Token Zugriff auf die gesamte Datenbank. Diese Methode kann verwendet werden, um Benutzer*innen (z. B. Administrator*innen und Manager*innen) Zugriff zu erteilen, die berechtigt sind, das gesamte semantische Modell anzuzeigen. Diese Methode kann jedoch nicht in jedem Szenario angewendet werden. In der folgenden Tabelle sind die verschiedenen RLS-Typen aufgeführt, und es wird gezeigt, welche Authentifizierungsmethode verwendet werden kann, ohne die Identität eines Benutzers anzugeben.

Die Tabelle enthält auch Überlegungen und Einschränkungen zu den einzelnen RLS-Typen.

RLS-Typ Kann ich ein Einbettungstoken generieren, ohne die geltende Benutzer-ID anzugeben? Überlegungen und Einschränkungen
Cloudsicherheit auf Zeilenebene (Cloud-RLS) ✔ Hauptbenutzer
✖ Dienstprinzipal
RDL (paginierte Berichte) ✖ Hauptbenutzer
✔ Dienstprinzipal		 Sie können mit einem Hauptbenutzer kein Einbettungstoken für RDL generieren.
Lokale Liveverbindungen mit Analysis Services (AS) ✔ Hauptbenutzer
✖ Dienstprinzipal		 Der Benutzer, der das Einbettungstoken generiert, benötigt zusätzlich eine der folgenden Berechtigungen:
  • Administratorberechtigungen für das Gateway
  • Berechtigung für Identitätswechsel in der Datenquelle (ReadOverrideEffectiveIdentity)
    		•
    Liveverbindungen mit Azure Analysis Services (AS) ✔ Hauptbenutzer
    ✖ Dienstprinzipal    		 Die Identität des Benutzers, der das Einbettungstoken generiert, kann nicht außer Kraft gesetzt werden. Mithilfe benutzerdefinierter Daten können dynamisches RLS oder sichere Filter implementiert werden.

    Hinweis: Der Dienstprinzipal muss seine Objekt-ID als effektive Identität (RLS-Benutzername) angeben.
    Einmaliges Anmelden (SSO) ✔ Hauptbenutzer
    ✖ Dienstprinzipal    		 Mithilfe der Blobeigenschaft für die Identität können Sie eine explizite Identität (SSO) in einem effektiven Identitätsobjekt bereitstellen.
    SSO und Cloud-RLS ✔ Hauptbenutzer
    ✖ Dienstprinzipal    		 Sie müssen Folgendes angeben:
  • Eine explizite Identität (SSO) in der Blobeigenschaft für die Identität in einem effektiven Identitätsobjekt
  • Effektive (RLS-)Identität (Benutzername)
    		•

    Hinweis

    Dienstprinzipale müssen immer die folgenden Informationen bereitstellen:

    • Eine Identität für ein Element mit einem semantischen RLS-Modell.
    • Für ein semantisches SSO-Modell eine effektive RLS-Identität mit der definierten (SSO-) Kontextidentität.

    DirectQuery für semantische Power BI-Modelle

    Gehen Sie wie folgt vor, um einen Power BI-Bericht einzubetten, der ein semantisches Modell mit einer Direct Query-Verbindung zu einem anderen semantischen Power BI-Modell aufweist:

    Verlängern von Token vor ihrem Ablauf

    Für Token gilt ein Zeitlimit. Dies bedeutet, dass Sie nach dem Einbetten eines Power BI-Elements nur eine begrenzte Zeitspanne mit ihm interagieren können. Um Ihren Benutzern einen unterbrechungsfreien Betrieb zu ermöglichen, verlängern (oder aktualisieren) Sie das Token, bevor es abläuft.

    Dashboards und Kacheln

    Token generieren funktioniert für Berichte und semantische Modelle. Verwenden Sie zum Generieren eines Einbettungstokens für ein Dashboard oder eine Kachel die Dashboards GenerateTokenInGroup- oder Kacheln GenerateTokenInGroup-APIs der Version 1. Diese APIs generieren Token jeweils nur für ein Element. Sie können kein Token für mehrere Elemente generieren.

    Für diese APIs:

    • Verwenden Sie den Parameter accessLevel, um die Zugriffsebene des Benutzers festzulegen.

      • Anzeigen: gewährt dem Benutzer Anzeigeberechtigungen.

      • Bearbeiten: gewährt dem Benutzer Anzeige- und Bearbeitungsberechtigungen (nur beim Generieren eines Einbettungstokens für einen Bericht).

      • Erstellen: gewährt dem Benutzer Berechtigungen zum Erstellen eines Berichts (gilt nur beim Generieren eines Einbettungstokens zum Erstellen eines Berichts). Sie müssen für das Erstellen von Berichten auch den Parameter datasetId angeben.

    • Verwenden Sie den booleschen Wert allowSaveAs, damit Benutzer den Bericht als neuen Bericht speichern können. Diese Einstellung ist standardmäßig auf false festgelegt und gilt nur, wenn ein Einbettungstoken für einen Bericht generiert wird.

    Überlegungen und Einschränkungen

    • Aus Sicherheitsgründen ist die Lebensdauer des Einbettungstokens auf die verbleibende Lebensdauer des Microsoft Entra-Tokens festgelegt, das für den Aufruf der GenerateToken-API verwendet wird. Wenn Sie das gleiche Microsoft Entra-Token zum Generieren mehrerer Einbettungstoken verwenden, wird die Lebensdauer der generierten Einbettungstoken daher mit jedem Aufruf kürzer.

    • Wenn sich das einzubettende semantische Modell und Element in zwei verschiedenen Arbeitsbereichen befinden, muss der Dienstprinzipal oder Hauptbenutzer mindestens Mitglied beider Arbeitsbereiche sein.

    • Sie können kein Einbettungstoken für Mein Arbeitsbereich erstellen.

    Zugehöriger Inhalt