OAuth Configuration and Usage

OAuth for plugins is available in Tableau 2021.1 and newer. Multi-IDP config for plugins is available starting in Tableau 2023.1.

This document explains how to configure and use OAuth. It’s meant for admins and plugin developers. For information on adding OAuth to a connector plugin, see OAuth Development.

We have templates for common IDPs in the samples. In general, you should only need to substitute the desktop client ID and secret, and the URL of the IDP. However, there may be additional modifications needed to account for differences such as with PKCE and scopes.

Note: Single use refresh tokens (sometimes called rolling refresh tokens or refresh token rotation) are not supported for OAuth connections to Tableau at this time. Support for these tokens are planned for a future release.

In this section

• The OAuth Config File
  • XML Elements
  • Response Attribute Mapping
  • OAuth Capabilities
  • Example OAuthConfig File
  • Instance URL/Custom Domain
  • Multiple Embedded OAuth Configs
• OAuth on Tableau Desktop/Tableau Prep
  • redirectUrisDesktop Format
  • Custom OAuth Configs on Desktop
• OAuth on Tableau Server & Tableau Online
  • Server Level OAuth Clients
  • Site Level OAuth Clients
    • Create Site OAuth Client (Pre 2023.1)
    • Create Site OAuth Client (2023.1+)
  • Site-Wide OAuth Clients
• Site vs Server OAuth Client
  • Saved Credentials
  • Desktop Publish Flow
  • Tableau Server Web Authoring Flow

The OAuth Config File

This file configures a connector to run OAuth flows against a particular IDP. The XML schema is defined here: XSD.

This file may be provided in the following ways:

• Bundled in the connector package (only available to plugin authors)
• Installing on a client machine for Tableau Desktop, Prep, or Bridge. See Custom OAuth Config on Desktop
• Installing for a site on Tableau Cloud or Tableau Server. Create Site OAuth Client

We refer to the first option as an “Embedded” config, and the second two as “Custom.” The latter two options are only available starting in Tableau 2023.1. Also before 2023.1 you can only embed a single OAuth Config.

XML Elements

<pluginOAuthConfig> is the parent element for all fields below.

Response Attribute Mapping

The XML elements accessTokenResponseMaps and refreshTokenResponseMaps define a relationship between Tableau field names to fields in the authorization server response. For example this maps Tableau’s ACCESSTOKEN field to access_token in the authorization server response.

    <entry>
        <key>ACCESSTOKEN</key>
        <value>access_token</value>
    </entry>

OAuth Capabilities

This set of OAuth Config capabilities is not shared with the regular connector capabilities.

Example OAuthConfig File

oauthConfig.xml

<?xml version="1.0" encoding="utf-8"?>
<pluginOAuthConfig>
    <!-- dbclass must correspond to the class registered in manifest.xml -->
    <dbclass>my-connector-class</dbclass>

    <clientIdDesktop>client-id-1234</clientIdDesktop>
    <clientSecretDesktop>xyz-456-000</clientSecretDesktop>

    <!-- Desktop redirectUri, only needed if your authorization server doesn't allow dynamic port ranges in localhost redirect. -->
    <redirectUrisDesktop>http://localhost:55556/Callback</redirectUrisDesktop>
    <redirectUrisDesktop>http://localhost:55557/Callback</redirectUrisDesktop>
    <redirectUrisDesktop>http://localhost:55558/Callback</redirectUrisDesktop>
    <redirectUrisDesktop>http://localhost:55559/Callback</redirectUrisDesktop>
    <redirectUrisDesktop>http://localhost:555510/Callback</redirectUrisDesktop>

    <authUri>https://my.idp.com/oauth2/v1/authorize</authUri>
    <tokenUri>https://my.idp.com/oauth/token-request</tokenUri>

    <instanceUrlValidationRegex>^https:\/\/(.+\.)?(supercloud\.(com|us|cn|de))(.*)</instanceUrlValidationRegex>
    <scopes>refresh_token</scopes>
    <scopes>profile</scopes>
    <scopes>email</scopes>
    <capabilities>
        <entry>
            <key>OAUTH_CAP_PKCE_REQUIRES_CODE_CHALLENGE_METHOD</key>
            <value>true</value>
        </entry>
        <entry>
            <key>OAUTH_CAP_SUPPORTS_CUSTOM_DOMAIN</key>
            <value>true</value>
        </entry>
        <entry>
            <key>OAUTH_CAP_REQUIRE_PKCE</key>
            <value>true</value>
        </entry>
        <entry>
            <key>OAUTH_CAP_FIXED_PORT_IN_CALLBACK_URL</key>
            <value>true</value>
        </entry>
        <entry>
            <key>OAUTH_CAP_PKCE_REQUIRES_CODE_CHALLENGE_METHOD</key>
            <value>true</value>
        </entry>
    </capabilities>

    <!-- Map Tableau recognized attribute "key" to OAuth response attribute "value" -->
    <accessTokenResponseMaps>
        <entry>
            <key>ACCESSTOKEN</key>
            <value>access_token</value>
        </entry>
        <entry>
            <key>REFRESHTOKEN</key>
            <value>refresh_token</value>
        </entry>
        <entry>
            <key>access-token-issue-time</key>
            <value>issued_at</value>
        </entry>
        <entry>
            <key>access-token-expires-in</key>
            <value>expires_in</value>
        </entry>
        <entry>
            <key>username</key>
            <value>username</value>
        </entry>
    </accessTokenResponseMaps>

    <!-- No refreshTokenResponseMaps needed since it's the same as accessTokenResponseMaps -->
 </pluginOAuthConfig>

Instance URL/Custom Domain

Some IDPs have a single global endpoint, such as https://accounts.google.com/o/oauth2/. Others have different instances, for example Okta would have a different instance URL for each customer. If your authorization server or IDP has different instances, then either:

• Enable OAUTH_CAP_SUPPORTS_CUSTOM_DOMAIN. This only works with embedded OAuth configs. The instance URL will be either be collected later from the end-user or be extracted via the embedded OAuth configs’ defaultInstanceUrl field.
• Create seperate external/custom OAuth configs for each custom domain. External OAuth config shouldn’t set OAUTH_CAP_SUPPORTS_CUSTOM_DOMAIN, and should specify authUri, tokenUri, userInfoUri fields as absolute paths, which contains the custom domain/instance URL.

Multiple Embedded OAuth Configs

*Available starting in Tableau 2023.1

The plugin developer may add multiple embedded OAuth configs to the plugin starting in Tableau 2023.1. Each should have a new element <oauthConfigId>. This should be unique and is displayed in the UI. The user will be prompted to select from the available configurations when creating a connection.

OAuth configs may also be specified independent of the plugin using site-level OAuth clients or by installing in the Tableau directory for desktop applications. See below for more information.

OAuth on Tableau Desktop/Tableau Prep

Tableau Desktop uses a shared client ID and client secret which is embedded in the plugin. It also uses localhost callbacks to receive the authorization code response. The plugin developer (or whoever provides the OAuth config) must ensure that the localhost or loopback callback URLs are configured on the whitelist for the authorization server.

If the authorization server supports dynamic port ranges for native applications then that should be used. This is the default behavior for Tableau OAuth clients. If the authorization server does not support this, then enable OAUTH_CAP_FIXED_PORT_IN_CALLBACK_URL, and specify a set of <redirectUrisDesktop> in the OAuth config.

redirectUrisDesktop Format

• Before Tableau 2023.1, the redirectUrisDesktop must be of the form http://localhost:[portnumber]/Callback. If you need to use loopback address other than localhost, you can enable OAUTH_CAP_SUPPORTS_HTTP_SCHEME_LOOPBACK_REDIRECT_URLS, but the <redirectUrisDesktop> should still specify localhost. The callback at runtime will be rewritten to something like http://127.0.0.1:55555/Callback.
• Starting in Tableau 2023.1, You can use any valid loopback address like http://localhost:[portnumber]/Callback, http://127.0.0.1:[portnumber]/Callback (IPv4), http://[::1]:[portnumber]/Callback (IPv6). If you use loopback address other than localhost, enable OAUTH_CAP_SUPPORTS_HTTP_SCHEME_LOOPBACK_REDIRECT_URLS as well.

For more information on see RFC 8252: Loopback Interface Redirection.

Custom OAuth Configs on Desktop

Available starting in Tableau 2023.1

The end user or admin can specify custom OAuth configs for desktop applications, independent of the plugin connector. These should be installed in the repository folder which corresponds to the application, such as My Tableau Repository/OAuthConfigs or My Tableau Prep Repository/OAuthConfigs. They must define the new field oauthConfigId. The user will be prompted to select from available configs when creating the connection.

When installing or testing custom OAuth configs on desktop, you must restart the application to pick up the changes.

OAuth on Tableau Server & Tableau Online

Server Level OAuth Clients

This is an older approach that may not work for plugins with with multiple OAuth configs. In most cases Site Level OAuth Clients are preferred.

You need to configure the OAuth client on server for all connectors using saved credentials (aka Custom OAuth), which includes all plugins. Execute the following command, substituting the values for your OAuth client. Note if you have multiple OAuth Configs, the oauth.config.id should be formatted as dbClass:oauthConfigId.

tsm configuration set -k oauth.config.clients -v "[{\"oauth.config.id\":\"[dbclass]\", \"oauth.config.client_id\":\"[client_id]\", \"oauth.config.client_secret\":\"[client_secret]\", \"oauth.config.redirect_uri\":\"[redirect_url]\"}]" --force-keys

The value dbclass should match that configured in the plugin manifest and OAuthConfig.xml. The client_id, client_secret, and redirect_uri should be provided by your authorization server. The redirect_url needs to follow certain format, if your Tableau Server URL is https://myserver/ then redirect_uri needs to be https://myserver/auth/add_oauth_token.

Site Level OAuth Clients

The preferred way to configure OAuth on Tableau Cloud/Server is by using site level OAuth clients. These are configured by the server admin for Tableau Server, or site admin for Tableau Online. For an example of configuring an Azure AD OAuth client on a site: https://help.tableau.com/current/server/en-us/config_oauth_azure_ad.htm.

The site OAuth clients will only be effective for a particular site, and will not not require a restart. They will take take precedence over the server-level OAuth clients if any. For each site, there is only one OAuth client allowed for each OAuth config.

Create Site OAuth Client (Pre 2023.1)

Create Site OAuth Client (2023.1+)

Starting in Tableau 2023.1, you can have multiple OAuth configs for a connector. These may be embedded or custom.

To create a client for an embedded config, select the config ID.

To create a client for an custom config, upload the config XML file.

Site-Wide OAuth Clients

Another way is through the site level OAuth client feature where the server admin for Tableau Server, or site admin for Tableau Online, will be able to register the OAuth client on a particular site. For example setting Azure AD OAuth client on a site: https://help.tableau.com/current/server/en-us/config_oauth_azure_ad.htm. The OAuth clients will only be effective in the particular site, it did not require a restart and take precedence over the server-wide OAuth clients if any.

Site vs Server OAuth Client

Saved Credentials

To add an OAuth credential on Tableau Server, go to My Account Settings page, look for your connector in the Saved Credentials For DataSources Section. After successfully adding your credential you will notice an entry appear under your connector. In this case the OAuth config ID is shown along with the username. In some cases the instance-url may also be shown.

Desktop Publish Flow

When publishing an OAuth connection to Tableau Server, you will see multiple auth options:

• Prompt means this resource will published without embedding credential, viewers would need to provide credential to access the resource.
• Embedding [username] means you will embed the credential to this resource, so all the viewer can use the same credential to access the resource. Note in order for this to show up, you must already have added a saved OAuth credential according to previous section. You would see multiple entries if you have multiple records of saved credentials and you can pick which one you want to use for embedding.
• Embed Password is not a supported auth mechanism for plugin OAuth connections and an error will show up if you choose that option.

Tableau Server Web Authoring Flow

For Web Authoring, the UI dialog will be same as Tableau Desktop. The difference will be that we are using the server OAuth clients. The server or site admin must configure the OAuth client information (client ID, client secret, etc) beforehand for this to succeed.