stephenlprice / tableau-connected-apps

A collection of Tableau Connected App (JTW authentication) code samples

Tableau Connected Apps

A collection of Tableau Connected Apps code samples. Connected Apps is the latest JWT authentication and SSO method available on the Tableau platform. Authentication via this method is supported for both Tableau's REST API and for displaying visualizations using the Embedding API v3. To understand how these APIs and Connected Apps work together to extend the Tableau platform and add analytical capabilities to your application, refer to the Embedded Analytics Playbook.

Table of Contents

• Tableau Connected Apps
  • Table of Contents
  • Connected Apps
  • Requirements
  • Installation
  • Dependencies
  • Environment Variables

Connected Apps

Tableau Connected Apps enable a seamless and secure authentication experience by facilitating an explicit trust relationship between your Tableau environment and custom applications that embed Tableau content or make use of Tableau's REST API. For a detailed explanation and setup instructions, refer to the official documentation.

The diagram below illustrates how authentication works between custom applications and a Connected App.

1. User visits the webpage
2. Custom application constructs an authentication token
3. Custom application responds with authentication token
4. Webpage requests content from Tableau
5. Tableau validates the token
6. Tableau returns the content based on the restricted embedding context

A similar flow takes place when Connected Apps are used to authenticate into Tableau's REST API. In this case, successful authentication will return an API token that must be added to subsequent requests via an X-Tableau-Auth header.

Requirements

This list covers requirements for local development and deployment to Heroku (note that you are free to deploy this server on other platforms).

• Python version 3.8.8
• Anaconda or some other Python environment manager (optional but recommended)
• Tableau Server or Tableau Online site (a developer site is available for free by signing up for the developer program)

Installation

1. Clone this repository

git clone [e-mail]:stephenlprice/tableau-connected-apps.git
# or
git clone https://github.com/stephenlprice/tableau-connected-apps.git

# navigate inside the project directory
cd tableau-connected-apps

1. Create a conda environment to install all dependencies and activate it (see Dependencies for more info.)

# will create an environment called tableau-webhooks
conda env create -f environment.yml

# activates the environment
conda activate tableau-connected-apps

NOTE: if you are not using conda you can create a requirements.txt file or install the dependencies listed in the environment.yml file manually with pip3.

3. Create a .env file in the project's root directory and add values for each environment variable described in the example file (example-env)

# create the .env file
touch .env

NOTE: the script will raise a RuntimeError if these environment variables are not declared.

4. Run the script

# enter the repo's python folder
cd python
# run the script
python index.py

Dependencies

This project was built with Anaconda, therefore the development environment can be cloned from the environment.yml file. Most dependencies are installed with conda while the last three are installed with pip3.

If you are new to conda I recommend keeping the conda cheatsheet nearby for reference.

name: tableau-connected-apps
channels:
  - defaults
dependencies:
  - python=3.8.8
  - requests=2.28.1
  - pip=21.2.4
  - pip:
    - python-dotenv==0.19.2
    - pyjwt[crypto]==2.4.0

It is possible to recreate this environment without Anaconda, using something like virtualenvwrapper. In that case you can install all dependencies with pip3 and write a requirements.txt file to document your dependencies.

Environment Variables

To protect private data such as JWT secrets, this project relies on environment variables to store this information without pushing them to the public Github repository (via .gitignore). If you are new to this concept I highly recommend that you read Twilio's blog post on the subject.

tldr: create a .env file using the example-env file provided with the repo. python-dotenv will load these variables into index.py to be used in the script.

Your .env file must contain all of the following variables:

TABLEAU_SERVER='tableau-server-or-cloud-domain'
TABLEAU_SITENAME='tableau-sitename'
TABLEAU_RESTAPI_VERSION='tableau-rest-api-version'
TABLEAU_USERNAME='tableau-username'
TABLEAU_CA_CLIENT='tableau-connected-app-client-id'
TABLEAU_CA_SECRET_ID='tableau-connected-app-secret-id'
TABLEAU_CA_SECRET_VALUE='tableau-connected-app-secret-value'

WARNING: Do not push usernames, passwords or personal access tokens to Github as they will be accessible by crawlers and is a well known security risk. Use .gitignore to stop unwanted files from being pushed to a git remote