OAuth Authentication Support

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

In this section

• How to Enable OAuth for a Plugin Connector
  • OAuth Only
  • Multiple Authentication Options
• 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
  • External/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

How to Enable OAuth for a Plugin Connector

First check your database and driver documentation to make sure it supports OAuth. For a complete example please refer to https://github.com/tableau/connector-plugin-sdk/tree/master/samples/scenarios/snowflake_oauth.

To enable OAuth for your connector add an <oauth-config> field in the manifest.xml and link to an oauthConfig.xml you created, described below.

  manifest.xml

  <?xml version='1.0' encoding='utf-8' ?>
  <connector-plugin class=...>
    ...
    <dialect file='dialect.tdd'/>
    <oauth-config file='oauthConfigPing.xml'/>    <!-- add this to to define your OAuth Configs -->
  </connector-plugin>

Starting in Tableau 2023.1, you can add multiple OAuth configs, embedded in the plugin. The end users may also provide external/custom OAuth configurations:

• By installing the config files in the Tableau directory. See External OAuth Config on Desktop
• By uploading the config for a site level OAuth client. See Create Site OAuth Client

However in both cases, at least one embedded config is still required.

  manifest.xml

  <?xml version='1.0' encoding='utf-8' ?>

  <connector-plugin class=...>
    ...
    <dialect file='dialect.tdd'/>
    <oauth-config file='oauthConfigPing.xml'/>
    <oauth-config file='oauthConfigOkta.xml'/>
  </connector-plugin>

In your connectionFields.xml file make sure to add an authentication field with a value equal to oauth. For example:

OAuth Only

    <field name="authentication" label="Authentication" category="authentication" value-type="string" editable="false" default-value="oauth" />

Multiple Authentication Options

    <field name="authentication" label="Authentication" category="authentication" value-type="selection" default-value="auth-user-pass" >
        <selection-group>
            <option value="auth-user-pass" label="Username and Password"/>
            <option value="oauth" label="OAuth"/>
        </selection-group>
    </field>

In your connectionProperties.js file you need to use your connector specific logic to handle how to pass in OAuth attributes. Example:

  if (authAttrValue == "oauth")
  {
      params["AUTHENTICATOR"] = "OAUTH";
      params["TOKEN"] = attr["ACCESSTOKEN"];
  }

In your connectionResolver.tdr file, the following related OAuth attributes will be automatically included so you do not need to define them: ACCESSTOKEN, REFRESHTOKEN, access-token-issue-time, access-token-expires-in, CLIENTID, CLIENTSECRET, oauth-client, id-token (if any), instanceurl (if any) You still need to define other required attributes for your connector; authentication and username are currently required for OAuth connections so make sure to add them as well.

<required-attributes>
    <attribute-list>
        <attr>server</attr>
        <attr>dbname</attr>
        <attr>sslmode</attr>
        <attr>authentication</attr>
        <attr>username</attr>
    </attribute-list>
</required-attributes>

The OAuth Config File

The OAuth Config file defines your connector’s OAuth configuration and also provides the ability to customize how the OAuth flow should work.

The OAuth Config file (XSD) is identified in the main plugin manifest using the <oauth-config> element. Here we discuss the structure of this file.

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 ports 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 and tokenUri only contains the relative path since this example has OAUTH_CAP_SUPPORTS_CUSTOM_DOMAIN enabled. -->
    <authUri>/oauth/authorize</authUri>
    <tokenUri>/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 collected later from the end-user or the admin.
• 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. For example http://localhost:*/Callback.

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.

External/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 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.

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 is 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 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 external/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.