Zugriffsbereiche für verbundene Apps

Ab Tableau Server-Version 2022.3 können Sie mit verbundenen Tableau-Apps über Ihre benutzerdefinierte Anwendung im Namen von Tableau Server-Benutzern die Tableau-REST API programmgesteuert aufrufen und darauf zugreifen. Der Zugriff auf die REST API wird durch ein JSON Web Token (JWT) ermöglicht, das im Rahmen der anfänglichen Anmeldeanforderung definiert wird. Das JWT muss Bereiche enthalten, die die REST API-Methoden definieren, die für Ihre benutzerdefinierte Anwendung und deren Benutzer über die verbundene App verfügbar sind.

Den Zugriff auf die REST API mithilfe verbundener Apps autorisieren Sie aus den folgenden Gründen:

• Erhöhte Sicherheit – die Verwendung eines JWT als Bearer-Token ist von Natur aus sicherer als das Speichern und Verwalten von Admin-Benutzerkennwörtern über .env-Dateien in Tresoren
• Steigerung der Effizienz – Die Verwendung eines JWT als Trägertoken ermöglicht einen vereinfachten Identitätswechsel mit einer einzigen Anfrage an den Anmeldungsendpunkt anstelle von zwei Anfragen.
• Erweiterung und Automatisierung komplexer Tableau-Integrationen und Backend-Abfragen – Dazu gehören zum Beispiel das dynamische Abrufen von Inhalten und erweitertes Filtern.

Bereichs-Aktionen

Verbundene Apps verwenden Bereiche, die Zugriff auf Aktionen für Inhalte oder administrative Aktion über die REST API-Methoden, die JWT-Autorisierung unterstützen (siehe unten). Ein Bereich ist eine durch Doppelpunkte unterteilte Zeichenfolge, die mit dem Namespace tableau beginnt, gefolgt von der Tableau-Ressource, auf die Zugriff gewährt wird (z. B. datasources), und am Schluss ist die Aktion aufgeführt, die für die Ressource erlaubt ist (z. B. update).

Zu den Aktionen, die ein Bereich ausführen kann, gehören:

• create
• read
• run
• update
• download
• delete

Ein Bereich, der es Ihrer benutzerdefinierten Anwendung ermöglicht, die Update Data Source(Link wird in neuem Fenster geöffnet)-Methode aufzurufen, würde zum Beispiel so aussehen:

tableau:datasources:update

Typen von Bereichen

Welche Art von Bereich Sie verwenden, hängt von den Inhalten oder administrativen Aktionen ab, die Sie aktivieren möchten. Bereiche fallen im Allgemeinen in einen der folgenden Typen: Inhalt gelesen, individuell, Platzhalter und kategorieübergreifend.

• Inhaltslesebereich : Der Inhaltslesebereich, tableau:content:read, aktiviert unterstützte GET-Methoden für Tableau-Inhalte. Wenn Sie diesen Bereich verwenden, aktivieren Sie Aktionen in allen REST-API-Kategorien. Genauer gesagt aktivieren Sie mit diesem Bereich GET-Methoden für Datenquellen, Metriken, Ansichten, Arbeitsmappen, Projekte und Websites.

  Hinweis: Um GET-Methoden für administrative Aktionen wie Benutzer und Gruppen zu aktivieren, können Sie ihre individuellen Geltungsbereiche verwenden.

• Individuelle Geltungsbereiche: Um unterstützte Inhalte und Verwaltungsaktionen zu aktivieren, können Sie ihre individuellen Geltungsbereiche verwenden. Ein individueller Geltungsbereich ist im Allgemeinen einer einzelnen Methode und REST-API-Kategorie zugeordnet.

  Beispiele:

  • Um die Aktion zum Veröffentlichen oder Aktualisieren einer Datenquelle zu aktivieren, können Sie den individuellen Geltungsbereich tableau:datasources:create oder tableau:datasources:update verwenden.
  • Für administrative Aktionen wie das Hinzufügen oder Entfernen von Benutzern können Sie die den individuellen Geltungsbereich tableau:users:create oder tableau:users:delete verwenden

  Hinweis: Es gibt einige einzelne Bereiche, die Aktionen über REST-API-Kategorien hinweg ermöglichen können. Zum Beispiel ermöglicht tableau:views:download Aktionen in den REST-API-Kategorien zum Anzeigen von Daten und Arbeitsmappen.

• Platzhalterbereiche: Für bestimmte Bereiche können Sie die Aktion durch das Platzhalterzeichen (*) ersetzen, um unterstützte Aktionen innerhalb einer bestimmten REST-API-Kategorie zu aktivieren.

  Beispiele:

  • Sie können den Platzhalterbereich tableau:projects:* dazu benutzen, die Aktionen zum Erstellen, Löschen und Aktualisieren in der REST-API-Kategorie des Projekts zu aktivieren.
  • Sie können den Platzhalterbereich tableau:users:* dazu benutzen, die Aktionen zum Abfragen, Hinzufügen, Löschen und Aktualisieren in der REST-API-Kategorie des Projekts zu aktivieren.

• Kategorieübergreifende Bereiche: Zusätzlich zum Inhaltslesebereich gibt es einige zusätzliche Bereiche, die, wenn sie verwendet werden, unterstützte Aktionen über verschiedene REST-API-Kategorien hinweg ermöglichen.

  Beispiele:

  • Bei Verwendung des Bereichs tableau:tasks:run aktivieren Sie Aktionen in den REST-API-Kategorien für Datenquellen und Arbeitsmappen.
  • Oder bei Verwendung des Bereichs tableau:views:download aktivieren Sie Aktionen in den REST-API-Kategorien für die Anzeige von Daten und Arbeitsmappen.
  • Bei Verwendung von Berechtigungsbereichen wietableau:permissions:update odertableau:permissions:delete aktivieren Sie Aktionen in den REST-API-Kategorien für Datenquellen, Arbeitsmappen und Projekte.

Zusammenfassung zur Autorisierung von Zugriff mithilfe der REST API

In der folgenden Liste sind die Schritte zusammengefasst, mit denen der Zugriff auf die REST API über ein JWT angefordert wird:

1. Erstellen Sie eine verbundene App auf eine der folgenden Weisen:
   • Konfigurieren von mit Tableau verbundenen Apps, um SSO für eingebettete Inhalte zu aktivieren
   • Registrieren eines EAS, um SSO für eingebettete Inhalte zu ermöglichen
2. Generieren eines gültigen JWTs – Ihre benutzerdefinierte App generiert zur Laufzeit ein gültiges JWT, das mit den von Ihnen eingetragenen Bereichen konfiguriert ist.
3. Stellen einer Anmeldeanforderung(Link wird in neuem Fenster geöffnet) – Ihre benutzerdefinierte Anwendung stellt mit dem JWT eine Anmeldeanforderung, damit ein Tableau-Zugangstoken und eine Site-ID (LUID) zurückgegeben wird.
4. Verwenden des Tableau-Zugangstokens in nachfolgenden Anforderungen – In darauf folgenden REST API-Aufrufen verwenden Sie 1.) das Tableau-Zugangstoken als Headerwert für X-Tableau-Auth(Link wird in neuem Fenster geöffnet) und 2.) die Site-ID (LUID) im Anforderungs-URI.

Beispiel

Sie erstellen eine verbundene App mittels direkter Vertrauensstellung. Bei direkter Vertrauensstellung generiert Ihre benutzerdefinierte App, die die REST API aufruft, ein gültiges JWT unter Verwendung der Client-ID und des geheimen Clientschlüssels, die von der verbundenen App generiert wurden.

Bereiche im JWT

Um Zugriff auf die REST API erfolgreich zu autorisieren, muss das JWT auch die Bereiche enthalten, die die REST API-Funktionen definieren. Um beispielsweise verschiedene datenquellenbezogene Methoden zu aktivieren, könnten Sie die folgenden Bereiche in das JWT aufnehmen:

"tableau:content:read","tableau:datasources:create","tableau:datasources:update","tableau:datasources:download","tableau:tasks:run"

Oder

"tableau:content:read","tableau:datasources:*","tableau:tasks:run"

Hinweis: Werte müssen als ein Listentyp übergeben werden.

Anmeldeanforderungs-URI

Um die REST API aufzurufen, muss Ihre benutzerdefinierte Anwendung zuerst eine Anmeldeanforderung stellen, damit ein Tableau-Anmeldeinformationen-Token generiert wird.

POST https://myco/api/3.17/auth/signin

Anforderungstext

Um REST API-Zugriff mithilfe eines JWT zu autorisieren, muss der Textteil der Anmeldeanforderung das gültige JWT enthalten, wie im folgenden Beispiel gezeigt.

<tsRequest>
   <credentials jwt="eyJpc3MiOiI4ZTFiNzE3Mi0zOWMzLTRhMzItODg3ZS1mYzJiNDExOWY1NmQiLCJhbGciOiJIUzI1NiIsImtpZCI6ImIwMTE1YmY5LTNhNGItNGM5MS1iMDA5LWNmMGMxNzBiMWE1NiJ9.eyJhdWQiOiJ0YWJsZWF1Iiwic3ViIjoicm1vaGFuQHRhYmxlYXUuY29tIiwic2NwIjpbInRhYmxlYXU6c2l0ZXM6cmVhZCJdLCJpc3MiOiI4ZTFiNzE3Mi0zOWMzLTRhMzItODg3ZS1mYzJiNDExOWY1NmQiLCJleHAiOjE2NDg2Njg0MzksImp0aSI6IjY1ZWFmMmYxLTNmZTgtNDc5Ny1hZmRiLTMyODMzZDVmZGJkYSJ9.mUv2o4gtBTrMVLEXY5XTpzDQTGvfE2LGi-3O2vdGfT8">
    <site contentUrl="mycodotcom"/>
   </credentials>
</tsRequest>

Antworttext

Die Anmeldeanforderung erzeugt den folgenden Antworttext, der das Tableau-Anmeldeinformationen-Token enthält.

<tsResponse>
   <credentials token="12ab34cd56ef78ab90cd12ef34ab56cd">
    <site id="9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d" contentUrl=""/>
    <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
   </credentials>
</tsResponse>

Nachdem das Tableau-Zugangstoken generiert wurde, fügen Sie das Tableau-Anmeldeinformationen-Token dem Header aller nachfolgenden REST-API-Anforderungen hinzu.

Header

X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd

Alle nachfolgenden REST API-Anforderungen, die das Tableau-Zugangstoken verwenden, werden dann durch die Bereiche im JWT begrenzt.

REST API-Methoden, die JWT-Autorisierung unterstützen

Die folgenden Bereiche können der verbundenen App zugeordnet werden, um den Zugriff und die Methoden zu definieren, die Ihre benutzerdefinierte Anwendung im Namen der Benutzer auf die REST API(Link wird in neuem Fenster geöffnet) haben bzw. verwenden kann.

Hinweise:

• Für andere REST API-Funktionen, die in der folgenden Tabelle nicht aufgeführt sind, können Sie andere Autorisierungsmechanismen verwenden, um auf die Methoden zuzugreifen. Weitere Informationen finden Sie unter Authentifizierungsmethoden(Link wird in neuem Fenster geöffnet) in der Hilfe zur Tableau-REST API.
• Informationen zu Bereichen, die von der Embedding-API v3 unterstützt werden, finden Sie an einer der folgenden beiden Stellen:
  • Konfigurieren von mit Tableau verbundenen Apps, um SSO für eingebettete Inhalte zu aktivieren
  • Registrieren eines EAS, um SSO für eingebettete Inhalte zu ermöglichen

Fehlerbehebung für Bereiche

401001 - Anmeldefehler

Wenn der Fehler 401001 auftritt, wird an den Anmelde-Antworttext einer der folgenden zusätzlichen spezifischen Fehlercodes für verbundene Apps angehängt: 16, 10084 oder 10085.

Im folgenden Antworttext ist beispielsweise "10084" der Fehlercode für verbundene Apps, den Sie verwenden können, um Probleme bei der Anmeldung bei Tableau Server unter Verwendung eines JWT für die REST-API-Autorisierung zu beheben.

<error code="401001">  
  "summary": "Signin Error",
  "detail": "Error signing in to Tableau Cloud (10084)"
</error>

Informationen zur Behebung des Problems finden Sie in der Beschreibung des entsprechenden Fehlercodes und seiner möglichen Ursachen.

• 16: Benutzer konnte nicht gefunden werden – Dieser Fehler kann auftreten, weil die falsche "sub" (Benutzername) angegeben wurde

• 10084: Zugangstoken konnte nicht geparst werden – Dieser Fehler kann aus folgenden Gründen auftreten:

  • Das JWT ist ungültig oder es ist ein unerwartetes Problem aufgetreten
  • Falsches "aud" (Publikum) wurde angegeben
  • Bei direktem Vertrauen gab es ein Problem beim Signieren des Geheimnisses

• 10085: Geheimnis zum Verifizieren der Signatur für die Client-ID konnte nicht abgerufen werden – Dieser Fehler kann aus folgenden Gründen auftreten:

  • Falsche Client-ID in "iss" angegeben
  • Für direktes Vertrauen wurde eine falsche "kid" (geheime ID) angegeben
  • Für EAS können Schlüssel nicht von der JWKSource abgerufen werden

401002 – Fehler wegen nicht autorisiertem Zugriff

Wenn der Fehler 401002 auftritt und Sie bestätigt haben, dass Sie über die erforderlichen Berechtigungen zum Stellen der Anforderung verfügen, stellen Sie sicher, dass der im JWT enthaltene Bereich korrekt ist und mit der Anforderung übereinstimmt, die Sie zu stellen versuchen. Eine Liste der Endpunkte und unterstützten Bereiche finden Sie im Abschnitt REST API-Methoden, die JWT-Autorisierung unterstützen oben.