Portail du Programme pour les développeurs

Connected Apps Tutorial

Niveau de difficulté
Intermediate
Fichiers de tutoriel
Get the full code on GitHub
Langages de programmation
JavaScript, HTML

Anthony Alteirac

Goals

The tutorial will help you to understand and implement our new authentication capability, known as “Connect Apps”.

Authentication can be seen as an important technical security piece but it’s also strongly influence the user experience. When comes the time to decide the way you going to handle authentication, security and flexibility are important.
Connected Apps will give you both and will ensure the best user experience with Single Sign-On (SSO). Think about Connected Apps as an authentication abstraction in between your application and Tableau. You don’t need to know by which method your users are authenticated in your application. The only information you’ll need to create a Tableau session is the user id.
It is easy to setup and IDP integrations with Tableau is no longer required, no need to setup SAML/OpenID etc. In some situations it is even impossible to rely on IDP integration, for example when your users are authenticating in you application through various IDP you’re not managing yourself. Cherry on the cake, your network topology is simpler, there’s no need for your application to communicate with Tableau Server or Tableau Online at the moment you create the Tableau session!

The main benefits:

  • Restrict access to which content can be embedded and where that content can be embedded
  • Provide users the ability to access embedded content using single sign-on (SSO) without having to integrate with an identity provider (IdP)
  • Single point of control (delete, rotate secrets...) for a better governance
  • Provide users the ability to authenticate directly from your custom application
  • Secure by design using JWT open standard (RFC7519), defining a self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed using a secret (with the HMAC algorithm)

Connected Apps streamlines the authentication experience with a unique way to to create user sessions (with restricted scopes if you need to narrow the default authorisations) for Tableau Online (TOL) and Tableau Server (on-prem). This especially important for TOL and embedded projects, knowing Trusted Authentication is not supported.

This tutorial will cover the Connected Apps concepts, a sample implementation including manual JWT (JSON Web Token) creation., Finally you’ll have a dashboard with a proper session cookie, without the need for the user to enter credentials and without any direct connection from your webpage to the Tableau Server or TOL.

Let’s start with the concepts!

Connected Apps flow

The diagram below illustrates how authentication works between your custom application (web server and webpage) and connected app.
image.png

  1. User visits the webpage: When a user visits the embedded content on a webpage, webpage sends a request to your custom application to retrieve the HTML on that webpage.
  2. Custom application constructs an authentication token: The custom application constructs a JWT, which contains a secret from the connected app (see Step 3 below for additional JWT requirements) and the scope of user access for the embedded content. The secret is signed by custom application and is used for verification of the trust relationship in a later step.
  3. Custom application responds with authentication token: The custom application responds to the page with the JWT in the embedded content’s URL called by the webpage.
  4. Webpage requests content from Tableau: With the attempt to load the embedded content, the webpage calls the embedded content’s URL, which sends a GET request to Tableau.
  5. Tableau validates the token: Tableau receives the JWT and verifies the trust relationship with the custom application by identifying the connected app and shared secret used in the JWT. Then Tableau creates a session for the user. The session not only respects the embedding scopes defined in the JWT, but also the restrictions specified in the connected app, including the allowed domains and allowed projects.
  6. Tableau returns the content based on the restricted embedding context: The embedded content only loads when the page is under an allowed domain and the content is published to an allowed project (if applicable). The authenticated user can only interact with the embedded content by the scope defined in the JWT.s

Note: The trust relationship is based on the fact the custom application knows the secrets, no direct communication required between custom application and Tableau Server (or TOL)

Background and requirements

You’ll need:

We strongly encourage you to use a sandbox environment, you can get one for free with our Developer Program:

You can follow the official documentation: https://help.tableau.com/current/online/en-us/connected_apps.htm#step-1-create-a-connected-app

Note: it can be automated with REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_connected_app.htm

For this step we’re not going to use any framework but instead build manually the JWT so you can exactly understand the way it is build and the expected shape from a Tableau perspective.

Here’s the structure

HEADER:ALGORITHM & TOKEN TYPE


{
"alg": "HS256", //Encryption, you can use this value
"typ": "JWT", //Type, it is a JWT :-)
"iss": "<THE CONNECTED APP ID>", //GENERATED DURING STEP 1
"kid": "<THE CONNECTED APP SECRET ID>" //IT IS NOT THE SECRET, IT IS SECRET ID !
}

PAYLOAD:DATA


{
"sub": "<THE USER NAME>" //Example: "aalteirac@tableau.com" for TOL,
"aud": "tableau", //MUST BE "tableau"
"jti": "<UNIQUE ID>",//HAS TO BE UNIQUE
"iss": "<THE CONNECTED APP ID>", //SAME AS HEADER, THE CONNECTED APP ID !
"scp": [
"tableau:views:embed" // THIS MUST BE AN ARRAY, even if single entry
],
"exp": <EXPIRATION DATE> // MAX IS 10mn, expressed in seconds, example: 1647339195
}

Now let’s build it in Javascript

The subtlety consist of base64url encoding instead of regular base64. To make the long story short, base64url is base64 plus extra contraints:

  • Replaces “+” by “-” (minus)
  • Replaces “/” by “_” (underline)
  • Does not require a padding character
  • Forbids line separators


    

  
            

    

  
        
  
                  

      

    

      

      

                

          
        

                

                      
Very easy step thanks to the new web component in Embedding API V3.



<script src = "https://myserver/javascripts/api/tableau.embedding.3.latest.js"></script>
<tableau-viz id="tableauViz" 
    src="http://my-server/views/my-workbook/my-view" 
    token="<THE GENERATED JWT">
</tableau-viz>



                        

      

    

  

      

    

  
        
  

              







      

      

              






            

      Resources 
      

      
                    
                          






      

    
Here’s a single page doing the JWT generation and displaying a dashboard.


This example is using the above code with UI to test easily against your developper instance or even your own server.

It’s a simple static page, easy to read and you don’t even need a web server.


WARNING: This sample is all client side for the sake of learning and testing easily. 

NEVER USE SECRETS CLIENT SIDE IN PRODUCTION


https://github.com/aalteirac/jwt_spa

 


    

  
            

    

  
        
  

              







      

      

              
                    
                    

    
  


          

    

  
        
  

            

      
  
  

    
Dernière mise à jour : juillet 29, 2022