Verbonden apps configureren met OAuth 2.0-vertrouwensrelatie

Als een Tableau Server-beheerder kunt u een of meer externe autorisatieservers (EAS's) registreren om een vertrouwensrelatie tot stand te brengen tussen uw Tableau Server en de EAS die het OAuth 2.0-standaardprotocol gebruikt.

Belangrijk:

  • Sommige procedures in dit onderwerp vereisen configuratie met software en services van derden. We hebben ons uiterste best gedaan om de procedures voor het inschakelen van de EAS-functie op Tableau Server te verifiëren. Software en services van derden kunnen echter veranderen of uw organisatie kan veranderen. Als u problemen tegenkomt, raadpleegt u de documentatie van derden voor autoritatieve configuratiedetails en ondersteuning.
  • Om insluiting via EAS mogelijk te maken moet Tableau Server worden geconfigureerd voor het gebruik van SSL voor HTTP-verkeer.
  • Om ervoor te zorgen dat het sessietoken geldig is, moeten de klokken van de externe toepassing en de server die de externe toepassing host, worden ingesteld op Coordinated Universal Time (UTC). Als een van beide klokken een andere tijd gebruikt, wordt de verbonden app niet vertrouwd.

Hoe met Tableau-verbonden apps werken met OAuth 2.0-vertrouwensrelatie

De vertrouwensrelatie tussen uw Tableau Server-site en externe toepassingen wordt vastgesteld en geverifieerd via een verificatietoken in de JSON Web Token (JWT)-standaard.

Wanneer ingesloten Tableau-inhoud in uw externe toepassing wordt geladen, wordt Authorization Code Flow, oftewel OAuth-flow gebruikt. Nadat gebruikers zich hebben aangemeld bij de IdP, worden ze automatisch aangemeld bij Tableau Server. Volg de onderstaande stappen om uw EAS te registreren bij Tableau Server .

Belangrijkste onderdelen van een verbonden app

De volgende onderdelen van verbonden apps werken samen met de JWT in uw externe toepassing om gebruikers te verifiëren en ingesloten inhoud weer te geven.

  • EAS (externe autorisatieserver): de server, doorgaans uw IdP, die fungeert als interface tussen de gebruiker en de externe toepassing. De server verifieert en autoriseert gebruikerstoegang tot de beveiligde Tableau-inhoud.

  • Uitgever-URL: de URL die de EAS-instantie op unieke wijze identificeert.

Workflow van verbonden app

Workflows insluiten

Het onderstaande diagram laat zien hoe verificatie tussen uw EAS (externe autorisatieserver), externe toepassing (webserver en webpagina) en de met Tableau verbonden app werkt.

  1. Gebruiker bezoekt de webpagina: wanneer een gebruiker de ingesloten inhoud op een webpagina bezoekt, stuurt de webpagina een GET-verzoek naar de externe toepassing.

  2. Externe toepassing stuurt verzoek door naar EAS: de externe toepassing reageert met een webpagina die doorverwijst naar de EAS (externe autorisatieserver).

  3. Gebruiker verifieert met EAS: de gebruiker verifieert en autoriseert via de EAS.

  4. EAS reageert op webpagina met autorisatiecode: de EAS reageert op de pagina met een autorisatiecode en de gebruiker wordt teruggeleid naar de webpagina.

  5. EAS converteert autorisatiecode naar JWT: de webpagina roept de EAS aan om de autorisatiecode om te zetten in een JWT dat de webpagina in de URL van de ingesloten inhoud plaatst.

  6. Webpagina vraagt inhoud op van Tableau: de webpagina laadt het iFrame en stuurt een GET-verzoek naar Tableau.

  7. Tableau valideert het token: Tableau valideert het JWT in de URL met de handtekening en reageert met de inhoud, waarbij de in het JWT gedefinieerde insluitingsscopes worden gerespecteerd.

Een verbonden app maken

Stap 1: Voordat u begint

Om een EAS bij Tableau Server- te registreren hebt u een geconfigureerde EAS nodig. Bovendien moet de EAS een geldige JSON Web Token (JWT) sturen met de geregistreerde claims en header die in de onderstaande tabel zijn vermeld.

ClaimNaamBeschrijving of vereiste waarde
kidSleutel-IDVereist (in header). Een unieke sleutel-ID van de identiteitsprovider.
issUitgeverVerplicht (in header of als claim). Unieke uitgever-URIdie de vertrouwde verbonden app en de ondertekeningssleutel identificeert.
algAlgoritmeVereist (in header). JWT-ondertekeningsalgoritme. Ondersteunde algoritmenamen worden vermeld op de pagina Klasse JWSAlgoritme(Link wordt in een nieuw venster geopend) in de javadoc.io-documentatie. Het ondertekeningsalgoritme kan worden geconfigureerd met de opdracht vizportal.oauth.external_authorization_server.blocklisted_jws_algorithms.
subOnderwerpGebruikersnaam van de geverifieerde Tableau Server-gebruiker.
audDoelgroep

Waarde moet zijn: tableau

expVervaltijdEen geldige JWT mag niet vervallen zijn. De vervaltijd (in UTC) van de JWT moet binnen de geconfigureerde maximale geldigheidsduur liggen. De maximale geldigheidsperiode kan worden geconfigureerd met de opdracht vizportal.oauth.external_authorization_server.max_expiration_period_in_minutes.
jtiJWT-IDDe JWT-ID-claim biedt een unieke ID voor de JWT en is hoofdlettergevoelig.
scpScope

Voor workflows insluiten zijn de ondersteunde waarden onder meer:

tableau:views:embed
tableau:views:embed_authoring (toegevoegd in Tableau Server 2022.3)
tableau:metrics:embed (buiten gebruik gesteld in Tableau Server 2023.3)
tableau:ask_data:embed (toegevoegd in Tableau Server 2023.1. wordt buiten gebruik gesteld in Tableau Server 2024.2)

Opmerkingen:

  • Waarden moeten worden doorgegeven als lijsttype.
  • Voor tableau:views:embed, respecteert de scope de gebruikersmachtigingen die al in Tableau Server zijn geconfigureerd, en stelt gebruikers in staat om te communiceren met de tools in de ingesloten weergave, mits beschikbaar in de oorspronkelijke weergave.
  • We raden aan dat de insluitcode de werkbalkparameter uitsluit. Zie Bekende problemen (alleen workflows insluiten) hieronder voor meer informatie.

Zie REST API-autorisatieworkflows voor REST API-methoden die JWT-autorisatie ondersteunen.

Voor Metadata-API-workflows die de REST API voor verificatie gebruiken is de enige ondersteunde scope tableau:content:read.

https://tableau.com/groupsLidmaatschap van dynamische groepAlleen voor workflows insluiten.

De waarde moet overeenkomen met de naam van een of meer groepen in Tableau Server. Zie de sectie Dynamisch groepslidmaatschap (alleen workflows insluiten) hieronder voor meer informatie.

Opmerking: de bovenstaande JWT-claims zijn gedocumenteerd in de sectie Geregistreerde claimnamen(Link wordt in een nieuw venster geopend) in de documentatie die wordt gedistribueerd door de Internet Engineering Task Force (IETF)-organisatie.

Stap 2: Registreer uw EAS bij Tableau Server

Door uw EAS te registreren bij Tableau Server brengt u een vertrouwensrelatie tot stand tussen de EAS en Tableau Server-. Dit betekent dat wanneer gebruikers toegang krijgen tot Tableau-inhoud die is ingesloten in uw externe toepassing, ze worden omgeleid om zich te verifiëren bij de IdP. De EAS genereert de verificatietoken, dat aan Tableau Server wordt doorgegeven voor verificatie. Nadat de vertrouwensrelatie is geverifieerd, krijgen gebruikers toegang tot de ingesloten inhoud.

Opmerking: sommige EAS ondersteunen de optie om een toestemmingsdialoogvenster weer te geven waarin gebruikers om goedkeuring wordt gevraagd voor toegang door de toepassing tot Tableau-inhoud. Om de beste ervaring voor uw gebruikers te garanderen raden we u aan uw EAS zodanig te configureren dat deze namens gebruikers automatisch instemt met het verzoek van de externe toepassing.

EAS op siteniveau

Vanaf Tableau Server 2024.2 kunt u EAS op siteniveau configureren. Om een EAS op siteniveau te registreren moeten verbonden apps zijn ingeschakeld in Tableau Server Manager (TSM).

Er zijn twee manieren waarop u serverbrede EAS kunt registreren: via de TSM-webgebruikersinterface of via TSM-CLI.

Na registratie van de EAS is de tot stand gebrachte vertrouwensrelatie van toepassing op alle sites op Tableau Server.

Optie 1: TSM-webinterface gebruiken

  1. Meld u als Tableau Server-beheerder aan bij de webinterface van Tableau Services Manager (TSM). Zie Aanmelden bij webgebruikersinterface van Tableau Services Manager voor meer informatie.

  2. Voer een van de volgende handelingen uit:

    • In Tableau Server 2024.2 en hoger gaat u naar de pagina Gebruikersidentiteit en toegang > tabblad Verbonden apps.

    • In Tableau Server 2023.3 en eerder gaat u naar de pagina Gebruikersidentiteit en toegang > tabblad Autorisatieserver.

  3. Voer een van de volgende handelingen uit:
    • In Tableau Server 2024.2 en later:

      1. Schakel het selectievakje Verbonden apps inschakelen in.

      2. Schakel het tweede keuzerondje Verbonden apps toestaan (configureren op siteniveau) en serverbrede OAuth 2.0-vertrouwensrelatie toestaan (hieronder configureren) in.

      3. Plak de uitgever-URL van de EAS in het tekstvak Uitgever-URL.

      4. Klik op de knop Lopende wijzigingen opslaan.

    • In Tableau Server 2023.3 en eerder:

      1. Schakel het selectievakje OAuth-toegang inschakelen voor ingesloten inhoud in.

      2. Plak de uitgever-URL van de EAS in het tekstvak Uitgever-URL.

      3. Klik op de knop Lopende wijzigingen opslaan.

  4. Wanneer u klaar bent, doet u het volgende:
    1. Klik rechtsboven op de pagina op de knop Lopende wijzigingen.

    2. Klik in de rechterbenedenhoek van de pagina op de knop Wijzigingen toepassen en opnieuw opstarten om Tableau Server te stoppen en opnieuw te starten.

Optie 2: TSM-CLI gebruiken

  1. Open een opdrachtprompt als beheerder op het eerste knooppunt (waar TSM is geïnstalleerd) in het cluster.
  2. Voer de volgende opdrachten uit:

    tsm configuration set -k vizportal.oauth.external_authorization.enabled -v true
    tsm configuration set -k vizportal.oauth.external_authorization_server.issuer -v "<issuer_url_of_EAS>"
    tsm restart

Vanaf Tableau Server 2024.2 kunt u voor een site een of meer EAS's registreren. Na registratie van de EAS op siteniveau geldt de tot stand gebrachte vertrouwensrelatie alleen voor de site.

Opmerking: een vereiste voor het configureren van EAS op siteniveau is dat in TSM verbonden apps zijn ingeschakeld.

Stap 1: Verbonden apps inschakelen

  1. Meld u als Tableau Server-beheerder aan bij de webinterface van Tableau Services Manager (TSM). Zie Aanmelden bij webgebruikersinterface van Tableau Services Manager voor meer informatie.

  2. Ga naar de pagina Gebruikersidentiteit en -toegang > tabblad Verbonden apps.

  3. Schakel het selectievakje Verbonden apps inschakelen in.

  4. Voer een van de volgende handelingen uit:

    • Selecteer het eerste keuzerondje Verbonden apps toestaan (configureren op siteniveau) om registratie van EAS's alleen op siteniveau mogelijk te maken.

    • (Standaard) Schakel het tweede keuzerondje Verbonden apps toestaan (configureren op siteniveau) en serverbrede OAuth 2.0-vertrouwensrelatie (hieronder configureren) in om het registreren van EAS's zowel op siteniveau als serverbreed mogelijk te maken. Als u deze optie kiest, zorg er dan voor dat de uitgevers-URL die op siteniveau is opgegeven, verschilt van de serverbrede uitgevers-URL.

  5. Klik op de knop Lopende wijzigingen opslaan.

  6. Wanneer u klaar bent, doet u het volgende:
    1. Klik rechtsboven op de pagina op de knop Lopende wijzigingen.

    2. Klik in de rechterbenedenhoek van de pagina op de knop Wijzigingen toepassen en opnieuw opstarten om Tableau Server te stoppen en opnieuw te starten.

Stap 2: Registreer de EAS

  1. Meld u als Tableau Server-beheerder aan bij Tableau Server.

  2. Selecteer in het linkerdeelvenster Instellingen > Verbonden apps.

  3. Klik op de vervolgkeuzepijl Nieuwe verbonden app en selecteer OAuth 2.0-vertrouwensrelatie.

  4. Doe in het dialoogvenster Verbonden app maken het volgende:
    1. Voer in het tekstvak Naam een naam voor de verbonden app in.

    2. Plak de uitgever-URL van de EAS in het tekstvak Uitgever-URL.

    3. Selecteer Verbonden app inschakelen. Om veiligheidsredenen wordt een verbonden app bij het maken standaard uitgeschakeld.

    4. Wanneer u klaar bent, klikt u op de knop Maken.

  5. Nadat de verbonden app is gemaakt, kopieert u de site-ID van de verbonden app. De site-ID wordt gebruikt voor de aud-claim (doelgroep) van JWT, zoals beschreven in stap 1 hierboven.

Stap 3: Volgende stappen

Workflows insluiten

Als u na het configureren van Tableau Server- uw EAS wilt gebruiken, moet u insluitcode aan uw externe toepassing toevoegen. Zorg ervoor dat u de geldige JWT die door uw EAS is gegenereerd, opneemt in de webcomponent die uw externe toepassing aanroept, zoals beschreven in stap 1.

Zie voor meer informatie over het insluiten van Tableau-inhoud een of beide van de volgende onderwerpen:

Opmerking: Om ervoor te zorgen dat gebruikers zich succesvol kunnen verifiëren wanneer ze toegang krijgen tot ingesloten inhoud, moeten browsers worden geconfigureerd om cookies van externe partijen toe te staan.

Bepalen waar inhoud kan worden ingesloten met behulp van de toelatingslijst voor domeinen voor insluiting

Vanaf Tableau Server 2023.3 kunnen u en uw gebruikers met behulp van de methode Update Embedding Settings for Site in Tableau REST API bepalen of Tableau-inhoud zonder beperking kan worden ingesloten of beperkt moet worden tot bepaalde domeinen.

Standaard is de site-instelling unrestrictedEmbedding voor insluiten ingesteld op true om onbeperkte insluiting mogelijk te maken. Als alternatief kunnen u en uw gebruikers de instelling op false zetten en de domeinen opgeven waar Tableau-inhoud in externe toepassingen kan worden ingesloten met de parameter allowList.

Zie een of beide van de volgende items voor meer informatie:

Voor REST API-autorisatieworkflows

Nadat de JWT is geconfigureerd, moet u de geldige JWT toevoegen aan het REST API-aanmeldingsverzoek voor geautoriseerde toegang. Zie Toegangsbereiken voor verbonden apps voor meer informatie.

Voor Tableau-metadata-API-workflows

Nadat de JWT is geconfigureerd, moet u de geldige JWT toevoegen aan het REST API-aanmeldingsverzoek. Zie Toegangsbereiken voor verbonden apps voor meer informatie.

Een verbonden app beheren

Dynamisch groepslidmaatschap (alleen workflows insluiten)

Vanaf Tableau Server 2024.2, kunt u, als verbonden apps zijn geconfigureerd en de instelling van deze optie is ingeschakeld, het groepslidmaatschap dynamisch beheren via aangepaste claims die zijn opgenomen in de JWT die door de externe toepassing is verzonden.

Indien hiervoor geconfigureerd, verzendt de externe toepassing tijdens gebruikersverificatie de JWT die twee aangepaste claims voor groepslidmaatschap bevat: groep (https://tableau.com/groups) en groepsnamen (bijvoorbeeld "Groep1" en "Groep2") waarin de gebruiker zich moet bevinden. Tableau valideert de JWT en maakt vervolgens toegang mogelijk tot de groepen en de inhoud waarvan de machtigingen afhankelijk zijn van die groepen.

Zie Lidmaatschap van een dynamische groep met behulp van beweringen voor meer informatie.

Bekende problemen (alleen workflows insluiten)

Er zijn een aantal bekende problemen bij het gebruik van verbonden apps die in een toekomstige release zullen worden aangepakt.

  • Functies van de werkbalk: Als bij ingesloten inhoud de werkbalkparameter is gedefinieerd, werken niet alle werkbalkfuncties. Om dit probleem te omzeilen, raden we u aan de werkbalkparameter te verbergen, zoals in het onderstaande voorbeeld.

    <tableau-viz id='tab-viz' src='https://<your_server>/t/<your_site>/...'
    	toolbar='hidden'>
    </tableau-viz>

  • Gepubliceerde databronnen: Gepubliceerde databronnen die voor databasereferenties zijn ingesteld op Gebruiker vragen, worden niet weergegeven. Om dit probleem te omzeilen, raden we eigenaren van databronnen aan om in plaats daarvan hun databasereferenties in te sluiten.

  • Ingesloten weergaven op meerdere sites: In Tableau Server 2023.1 en eerder veroorzaakt het schakelen tussen weergaven op verschillende sites in dezelfde browser fout 1008: Kan geheim voor verbonden app niet ophalen. Om dit probleem te omzeilen, kunt u upgraden naar Tableau Server 2023.3 of hoger.

Problemen oplossen

Wanneer ingesloten inhoud niet wordt weergegeven in uw externe toepassing of de Tableau REST API-autorisatie mislukt, kunt u de ontwikkelaarstools van een browser gebruiken om foutcodes te inspecteren en te identificeren die mogelijk verband houden met de ingeschakelde EAS-functie op Tableau Server-.

Raadpleeg de onderstaande tabel om de beschrijving van de foutcode en de mogelijke oplossing te bekijken.

FoutcodeSamenvattingBeschrijvingMogelijke oplossing of verklaring
5SYSTEM_USER_NOT_FOUNDKan Tableau-gebruiker niet vinden
Om dit probleem op te lossen controleert u of de claimwaarde sub (onderwerp) in de JWT 'username' is voor de geverifieerde Tableau Server. Deze waarde is hoofdlettergevoelig.
16LOGIN_FAILEDInloggen is misluktDeze fout wordt doorgaans veroorzaakt door een van de volgende problemen met claims in de JWT:
67FEATURE_NOT_ENABLEDOn-demand toegang wordt niet ondersteundOn-demand toegang is alleen beschikbaar via gelicentieerde Tableau Cloud-sites.
10081COULD_NOT_RETRIEVE_IDP_METADATAOntbrekend EAS-metadata-eindpuntOm dit probleem op te lossen controleert u of de EAS correct is geconfigureerd en of de juiste uitgever wordt aangeroepen.
10082AUTHORIZATION_SERVER_ISSUER_NOT_SPECIFIEDOntbrekende uitgeverOm dit probleem op te lossen controleert u of de juiste uitgever wordt aangeroepen. Om de URL van de uitgever te wijzigen kunt u de opdracht vizportal.oauth.external_authorization_server.issuer gebruiken.
10083BAD_JWTJWT-header bevat problemenDe claims kid (geheim-ID) of clientId (uitgever) ontbreken in de JWT-header. Om dit probleem op te lossen zorgt u ervoor dat deze informatie wordt opgenomen.
10084JWT_PARSE_ERRORJWT bevat problemenControleer het volgende om dit probleem op te lossen:
  • De waarde aud (doelgroep) waarnaar in de JWT wordt verwezen, gebruikt de waarde 'tableau'. Deze waarde is hoofdlettergevoelig.
  • De aud (publiek) en sub (onderwerp) zijn in de JWT opgenomen.
10085COULD_NOT_FETCH_JWT_KEYSJWT kan de sleutels niet vindenKan het geheim niet vinden.

Om dit probleem op te lossen controleert u of de juiste uitgever wordt aangeroepen. Om de URL van de uitgever te wijzigen kunt u de opdracht vizportal.oauth.external_authorization_server.issuer gebruiken.

10087BLOCKLISTED_JWS_ALGORITHM_USED_TO_SIGNProbleem met het JWT-ondertekeningsalgoritmeOm het probleem op te lossen kunt u het ondertekeningsalgoritme verwijderen. Zie vizportal.oauth.external_authorization_server.blocklisted_jws_algorithms voor meer informatie.
10088RSA_KEY_SIZE_INVALIDProbleem met JWT-ondertekeningsvereistenOm dit probleem op te lossen moet u bij de EAS of IdP verifiëren of de JWT is ondertekend met een RSA-sleutelgrootte van 2048.
10091JTI_ALREADY_USEDUnieke JWT vereistDe JWT wordt al gebruikt in het verificatieproces. Om dit probleem op te lossen moet de EAS of IdP een nieuwe JWT genereren.
10092NOT_IN_DOMAIN_ALLOW_LISTHet domein van de ingesloten inhoud is niet gespecificeerdOm dit probleem op te lossen zorgt u ervoor dat de unrestrictedEmbedding is ingesteld op true en of de parameter domainAllowlist de domeinen omvat waarin Tableau-inhoud is ingesloten met behulp van de methode Insluitingsinstellingen voor de site bijwerken(Link wordt in een nieuw venster geopend) in de Tableau REST API.
10094MISSING_REQUIRED_JTIOntbrekende JWT-IDOm dit probleem op te lossen controleert u of de jti (JWT-ID) is opgenomen in de JWT.
10096JWT_EXPIRATION_EXCEEDS_CONFIGURED_EXPIRATION_PERIOD De exp (vervaltijd) overschrijdt de standaard maximale geldigheidsperiode. Om dit probleem op te lossen bekijkt u geregistreerde claims(Link wordt in een nieuw venster geopend) die zijn vereist voor een geldige JWT en controleert u of de juiste waarde is gebruikt. Om de maximale geldigheidsduur te wijzigen kunt u gebruikmaken van de opdracht vizportal.oauth.external_authorization_server.max_expiration_period_in_minutes.
10097SCOPES_MALFORMEDProblemen met bereikclaimDeze fout kan optreden wanneer de claim scp (scope) in de JWT ontbreekt of niet wordt doorgegeven als lijsttype. Om dit probleem op te lossen controleert u of scp in de JWT is opgenomen en doorgegeven als lijsttype. Voor hulp bij het oplossen van problemen met een JWT raadpleegt u Debugger(Link wordt in een nieuw venster geopend) op de auth0-site.
10098JWT_UNSIGNED_OR_ENCRYPTEDJWT is niet ondertekend of versleuteldTableau ondersteunt geen niet-ondertekende of niet-versleutelde JWT.
10099SCOPES_MISSING_IN_JWTClaim voor ontbrekende scopesDe vereiste claim scp (scope) ontbreekt in de JWT. Om dit probleem op te lossen controleert u of scp in de JWT is opgenomen. Voor hulp bij het oplossen van problemen met een JWT raadpleegt u Debugger(Link wordt in een nieuw venster geopend) op de auth0-site.
10100JTI_PERSISTENCE_FAILEDOnverwachte JWT-ID-foutEr is een onverwachte fout opgetreden met de jti (JWT-ID). Om dit probleem op te lossen moet er een nieuwe JWT met een nieuwe jti worden gegenereerd.
10103JWT_MAX_SIZE_EXCEEDEDJWT overschrijdt de maximale grootteDeze fout kan optreden als de JWT-grootte meer is dan 8000 bytes. Om dit probleem op te lossen moet u ervoor zorgen dat alleen de noodzakelijke claims worden doorgegeven aan Tableau Server.
Bedankt voor uw feedback.De feedback is verzonden. Dank u wel.