Considerations for Building Your Connector


🕐 7 min read

This topic tries to clarify some design and implementation ideas that have traditionally been part of Web Data Connector.

Cross-origin resource sharing

The JavaScript code in your web data connector makes requests to a server that’s on a different domain than your web data connector’s HTML page. That is, the code makes requests that represent cross-origin resource sharing (CORS). As a security measure, most browsers restrict CORS requests made from JavaScript code.

This restriction can result in errors when the web data connector runs. For example, if the code in your connector makes requests to a server that doesn’t allow CORS requests, you might see an error like the following in your browser console:

XMLHttpRequest cannot load URL. No 'Access-Control-Allow-Origin' header is present on the requested resource.

If you find that the domain your connector’s requested domain has CORS policy restrictions, you can use the functionality in the TACO Toolkit SDK to bypass the CORS policy and get the data from another API:

connector.get(url, {bypassCorsPolicy:true})

Parsing data

Authentication

Many connectors require authentication to connect to a data source. For these connectors, the TACO Toolkit provides boilerplate files that handle different types of authentication.

The TACO Toolkit supports three types of authentication:

Basic

Basic authentication is a method that requires a username and password when making a request. If you create a basic authentication connector, Tableau displays a standard username and password dialog. To create a basic authentication connector, see Create a Basic Authentication Connector.

Custom

Custom authentication allows you to set up an authentication process to support API keys or tokens, including authenticating the user through a third-party system.

OAuth

OAuth is an authentication protocol that allows your web data connector to request specific resources from a resource provider on behalf of a specific resource owner. This is a more secure and usable alternative to a connector that asks the user directly for their username and password.

To use OAuth, your connector must be registered with the OAuth resource provider. The provider assigns a client ID to identify the connector and a client secret that is known only by the connector and the OAuth provider and is used to authorize the connector to make requests on behalf of the user.

When your connector contacts the OAuth provider, the connector passes the client ID to identify itself. The exact process for registering your connector differs for each provider, and is typically explained in the provider’s documentation for how to use their API.

Benefits of OAuth

Using OAuth-based connections provides the following benefits:

To create an OAuth connector, see Create an OAuth Connector.

Configuring for OAuth

Each OAuth config attribute is represented by an element in the XML, the element name is the attribute name and the content is the attribute value.

Name Type Meaning Required? Notes
dbclass String The identifier for your oauthConfig Yes The dbclass must be same with as the class attribute in manifest.xml
clientIdDesktop String Client ID you registered for Tableau Desktop No This isn’t considered a secret and will be stored in plain text
clientSecretDesktop String Client Secret you registered for Tableau Desktop No This isn’t considered a secret and will be stored in plain text
redirectUrisDesktop String[] Redirect Urls for Desktop No Only required when OAUTH_CAP_FIXED_PORT_IN_CALLBACK_URL is set to true. The host for redirectUrisDesktop must be a valid loopback address
authUri String Authorization endpoint URI Yes  
tokenUri String Token endpoint URI Yes  
userInfoUri String User Info UrI No  
instanceUrlValidationRegex String Use to validate against your OAuth instance Url. No  
scopes String[] scopes Yes  
capabilities Map<String, String> This defines how OAuth flow behaves differently according to the capabilities set. No  
accessTokenResponseMaps Map<String, String> Key value pair that maps an initial token request response attribute to Tableau recognized attribute Yes  
refreshTokenResponseMaps Map<String, String> Key value pair that maps a refresh token request response attribute to Tableau recognized attribute No If not defined will use accessTokenResponseMaps by default

Note: The keys in accessTokenResponseMaps and refreshTokenResponseMaps are Tableau preferred field names and are defined in the followed table. The values are what your OAuth provider returns in the raw response

Name of the key Required for accessTokenResponseMaps Required for refreshTokenResponseMaps Notes
ACCESSTOKEN Yes Yes Used by Tableau to connect to your data.
REFRESHTOKEN Yes No Used by Tableau to get a new ACCESSTOKEN when the old one expired.
username Yes No Used by Tableau to identify the token.
access-token-issue-time No No Used to note when the token is issued, will default to the time when the token is sent back to Tableau if not set.
access-token-expires-in No No Use to note the validation time of your ACCESSTOKEN, which will default to 3600 seconds if not set.
id-token No No If you have openid as your scope this field is returned and can be used to retrieve userinfo. Use together with OAUTH_CAP_SUPPORTS_GET_USERINFO_FROM_ID_TOKEN
[your own field] No No It’s usually not needed to define your own field, and this field won’t be able to participate in any OAuth flow.


OAuth configuration capabilities

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

Capability Name Description Default Recommendation
OAUTH_CAP_SUPPORTS_CUSTOM_DOMAIN Whether your OAuth provider supports a custom domain. i.e. OAuth endpoint host isn’t fixed. false -
OAUTH_CAP_REQUIRE_PKCE Whether your OAuth provider supports PKCE, more details: https://oauth.net/2/pkce/ false true
OAUTH_CAP_PKCE_REQUIRES_CODE_CHALLENGE_METHOD Whether your OAuth provider PKCE requires code_challenging_method passed in. If set to true, we’re using S256 by default. false true
OAUTH_CAP_SUPPORTS_STATE Used to protect against CSRF attacks, more details: https://auth0.com/docs/protocols/state-parameters false true
OAUTH_CAP_GET_USERNAME_USES_POST_REQUEST Only use if you define a USERINFO_URI in the oauthConfig file to retrieve the userinfo in a separate request false -
OAUTH_CAP_CLIENT_SECRET_IN_URL_QUERY_PARAM Use this if Client secrets are expected in the query parameter instead of the request header. false -
OAUTH_CAP_FIXED_PORT_IN_CALLBACK_URL Use this when your OAuth provider native app(Tableau Desktop) OAuth clients only support a fixed callback url false -
OAUTH_CAP_SUPPORTS_HTTP_SCHEME_LOOPBACK_REDIRECT_URLS Use this when your OAuth provider native app(Tableau Desktop) OAuth clients support Loopback callback url. E.g. https://developers.google.com/identity/protocols/oauth2/native-app false -
OAUTH_CAP_REQUIRES_PROMPT_CONSENT Add prompt=consent to the request. false -
OAUTH_CAP_REQUIRES_PROMPT_SELECT_ACCOUNT Add propmt=select_account to the request. More details: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow false -
OAUTH_CAP_SUPPORTS_GET_USERINFO_FROM_ID_TOKEN Used when your OAuth response contains a JWT style ID_TOKEN that can be parsed out to get an actual username. For example, https://docs.microsoft.com/en-us/azure/active-directory/develop/id-tokens false -

Multiple tables

Web Data Connector 3.0 supports multiple table connectors by default.