Tutorial: Configuring Okta as OAuth2 Trust SSO idP for Tableau Embedded Content

Starting from Tableau Server version 2021.4, it’s possible to utilize an Oauth2-compliant External Authorization Server (EAS) to act as an SSO provider for Tableau Server embedded content.

EAS leverages the OAuth 2.0 protocol to control the authorization to access a protected resource like your web app, as well as Embedded content hosted on Tableau Server. Most, if not all major Identity Managament Solutions support this protocol, but in this article we’ll focus on Okta.

Also as of today (v2023.3) EAS for Tableau Server is a server-wide SSO feature (i.e. all Sites/Tenants will share the same EAS), but in the feature it may be possible to use a different EAS for each Site, enabling multi-tenant scenarios. In contrast, the Connected Apps Oauth2 Trust implementation for Tableau Cloud is site-specific, i.e. each Site has it’s own EAS config, pointing to it’s own Okta Oauth2 Trust idp.

Update 15 Dec 2023: You can follow this article for both Tableau Server and Tableau Cloud. The main difference is that the audience attribute is “aud” = “tableau:{site-LLUID}”, instead of “aud” = “tableau”. You can get the site-LLUID from your Connected Apps Oauth2 Trust definition in Tableau Cloud.

In this document you’ll learn how to quickly configure Okta as your EAS to give your users seamless access Tableau Server embedded via SSO. I’ve built a simple demo app that you can use to test it on your own environment.

Let’s look how the user flow with an EAS could look like:

1. User visits your “web portal front end” that contains some Tableau content (e.g. a dashboard that we will refer here as “viz”). “Web portal front end” sends GET request to “web portal back end”.
2. “Web portal back end” responds with a page that redirects the user’s web browser to External Authorization Server (this runs in Okta)
3. User authenticates & authorizes with EAS
4. EAS responds with an authorization code and redirects back to “web portal back end”
5. “web portal back end” calls IdP (Okta) to convert authorization code to access token (JWT). “Web portal back end” puts JWT into Tableau viz URL.
6. The browser attempts to load the Tableau viz iframe, sending a GET request to Tableau Server. Tableau Server validates the JWT in the URL with the signature/shared secret.
7. After successfully validating the JWT, Tableau responds with the viz

The above flow is based on the standard Oauth 2.0 Authorization Code flow, which is typically represented like this:

where “Web App” = “the Web Server you will be embedding Tableau Server content”, “Resource Server” = “Tableau Server”. The access token here (in step 6) comes from the Identity Provider’s “External Authorization Server” (e.g. Okta) and this same token can be passed to Tableau Server when requesting access to some content (e.g. a dashboard or metric).

Most Identity Providers are compliant with Oauth 2.0 nowadays and offer quickstart applications with middleware libraries that make requesting authorization code and access tokens super easy, so they are excellent places to start if you wish to extend it and include a Tableau Embedded Viz.

In this blog post, I’ll show you the step-by-step with Okta using a slighly modified version of their sample Node.js Express app. I’ve included the minimum necessary code to display a Tableau Visualization embedded using our Embedding API v3.

Download my starter app

git clone https://github.com/alexeski/tableau_embed_okta_eas.git

Demo of the finished solution:

Let’s create our own OKTA EAS and Demo App:

a) Create an EAS in Okta that can generate JWT access tokens in the format expected by Tableau Server

Let’s first create an Okta EAS (External Authorization Server), with the appropriate JWT scopes required by Tableau Server:

a.1) If you haven’t done so, first create a free Okta developer account. Then manually create a user that will be login on your Web Portal and eventually in Tableau via EAS SSO. Use the email as username both in Okta and Tableau!

a.2) Go to “Security” → “API” → “Add Authorization Server”.

a.3) “Name” : tableau server (note: any name would work here)

a.4) “Audience”: tableau (Tableau Server ) or tableau:<site_luid> (Tableau Cloud). Note: <site_luid> is NOT your site name, but rather the Site ID shown in the Connected App Oath2 Trust settings screen

a.5) Go to “Scopes” and add all scopes needed for Embedding Tableau content, e.g. tableau:views:embed , tableau:metrics:embed, etc

a.6) Go to “Access Policies” and allow all clients to use this Authorization provider (for now, just for testing). Also create a new rule allowing all scopes (Again, you can restrict it as needed, for now I’m leaving everything on jsut for a quick test. The main bit to enable here is “Grant type” : Authorization Code, Any users, Any Scopes.

a.7) “Access token lifetime is”: 5 minutes (!this is super important!, because it has to be at most as long as configured in Tableau Server, which is 5 minutes by default).

a.8) Testing if your Authorization provider is generating JWT as expected by Tableau Server. Go to “Token Preview”, select your new OIDC client = My Web App, Grant Type = Authorization Code, User = <any valid user here>, Scopes = “tableau:views:embed” & :tableau:metrics:embed”. Click Preview Token:

Now compare if this output matches what Tableau Server expects. The main thing here is that the Access Token JWT must contain audience “aud”: tableau, the tableau embed content scopes (“scp” : tableau:views:embed), the email of the user that matches a username in Tableau Server under “sub”, the expiration (“exp”) which cannot be longer than in Tableau Server (5 min default). For reference, here’s a screenshot of Tableau’s EAS config instructions:

a.9) Still in Okta, go back to settings and grab the URI for this new Authorization Server. We’ll use it on the next step when configuring Tableau Server:

Take a note of the above “Metadata URI”, as you need to add this value as the “<issuer_url_of_EAS>” on your Tableau Server configuration (see next steps)”

b) Configure your Tableau Server with details from your Okta EAS

b.1) As a pre-requisite for EAS Auth to work properly, Tableau Server must be configured to run with SSL enabled. You may even use a self-signed certificate for testing purposes.

b.2) Now let’s instruct Tableau Server to use the new EAS we created in Okta. We need the URI you got in step a.9 <issuer_uri_of_EAS>.

You can do it from the TSM command line tool:

tsm configuration set -k vizportal.oauth.external_authorization.enabled -v true

tsm configuration set -k vizportal.oauth.external_authorization_server.issuer -v "<issuer_uri_of_EAS>"

tsm restart

…or via TSM GUI:

Save all pending changes and restart the server.

b.3) If you haven’t yet done so, add the okta test user to Tableau Server. Make sure the username (email) is identical to the one you have used in Okta (step a.1)!

c) Register your “Web portal back end” as a new Web Application in Okta

Let’s create a new integration for our “Web portal back end” in Okta (i.e. my modified version sample okta quickstart app):

1. In the Dashboard, click on “SSO APPS” → “Create App Integration”
2. Choose “Sign-in method”:OIDC and “Application type”: Web Application
3. Give it a name to this new app and select “Grant Type”: Authorization Code
4. “Sign-in redirect URIs”: http://localhost:8080/authorization-code/callback (this is where to redirect the browser back, after a successful user authentication against Okta).
5. “Sign-out redirect URIs”: http://localhost:8080
6. “Assignments” : Allow everyone in your organization to access (just for testing, you can also allow just some users here)
7. Take a note of the Client ID and Client Secret (you’ll use it later when configuring the web app you have cloned from github).

You should have something like this:

8. Go to “Assignments” and add a couple of users that should be allowed to sign in through this new App (you will need to add these same users to Tableau Server. Make sure to use the email as username!).

d) If you wish to test it with my sample app, clone my git repo and configure it to your parameters

d.1) To run this application, as a pre-requisite you need to have Node JS and git installed on your machine. Then go ahead and clone the repo:

git clone https://github.com/alexeski/tableau_embed_okta_eas.git

d.2) And run the following to install the necessary dependencies (feel free to ignore the security warnings for now, as this is just a demo app and should never be used in prod):

npm install

Now let’s configure the sample github app with Okta EAS’ parameters and url of the viz we wish to embed:

d.3 Go to the root path where you ran npm install and create a file called testenv with the information about your Okta client app and Authorization Server URI generated in the previous steps. For example:

d.4) Now jump to your favorite code editor and to make a few adjustments to the code Edit the file .common/sample-we-server.js and locate the /dash route and add the url of a visualization hosted on your Tableau Server. For example:

<ADD-YOUR-TABLEAU-VIZ-URL-HERE> = https://ec2amaz-3mvj71t/views/GoogleCOVID-19MobilityDashboard/MobilityDashboard

You will find this under the /dash route:

They way this function works, whenever a user triggers the /dash route (e.g. by clicking on the “Tableau Dashboard” menu, it will first fire Okta’s oidc.ensureAuthenticated( ) function, which takes care of all the authentication and access token exchange for us. Then it will activate the ‘dash’ route which will redirect the browser to the Dashboard page (effectively under .common/views/dash.mustache, passing the access_token and viz_url.

The dashboard page has the Tableau Embed code v3, including passing the JWT access token. Here’s how it looks like

d.5) Finally, let’s now try out our sample web app! Start the app as follows:

npm run okta-hosted-login-server

d.6) In your browser, go to http://localhost:8080 and click the Login button.

If everything is configured correctly, your browser should be redirected to Okta to authentication the user. After a successful login, Okta will redirect your browser back to the homepage and you can now go to the Dash page to see the embedded Tableau Dashboard showing up seamlessly without prompting you to sign in.

Troubleshooting Tips:

You’ll find all EAS-related error messages can be found in the vizportal logs, under file name vizportal-nodeN-N.log under these directories:

Win: C:\ProgramData\Tableau\Tableau Server\data\tabsvc\logs\vizportal Linux: /var/opt/tableau/tableau_server/data/tabsvc/logs/vizportal

I highly recommend using Tableau Log Viewer to visualise and parse these logs easily as you develop your integration. This is high it looks:

Look for the “externalauthorization” string to locate the relevant EAS auth entries and, in case of any errors, refer to the error code table available on Tableau’s official documentation.

In summary, it’s becoming easier and easier to embed Tableau content in third-party applications thanks to the variety of SSO options. EAS is a compeling option if you wish to leave the responsibiliy of all user identities and credential management to your oauth2 idp of choice, for example if that’s what your existing portal/app is already doing.

In case you do not already use an external EAS in your App, you can use a different SSO solution called Connected Apps Direct Trust. The way it works is that you register your APP with Tableau Server/Online to let it act as your app’s EAS, instead of relying on a third-party authentication solution. You can even set the scope of the app to a single “content folder” (aka Project), allowing you to run unlimited Connected Apps under a single Site/Tenant. Connected Apps is available for both Tableau Server and Online. It’s in fact the recommended SSO auth solution for most clients going forward.

Hope this post helps some of you folks.

Share your experiences and questions in the comments section below.