Salesforce Docs Portal

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

  • The parser file (located in the handlers/ directory) extends the proper parser class. The TACO Toolkit provides two base parser classes, Parser and AsyncParser. The difference between the two classes is that the signatures of the .parse() function from the classes are sync and async accordingly.

    So if the custom parser needs an async operation, such as loading external resources for parsing, you should extend the AsyncParser. Otherwise, we recommend that you use the Parser class.

  • Always use ContainerBuilder to mutate dataContainer in parser. AsyncParser.createContainerBuilder(dataContainer). This guarantees that the dataContainer object is always in a proper shape.

  • The parser file also returns the dataContainer from the .parse() function. For performance purposes, a dataContainer passed to the .parse() function is a mutable object. However, it doesn’t mean directly mutating the dataContainer object takes any effect in the connector runtime engine.

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
  • Custom
  • OAuth

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:

  • Security: Your database credentials are never known to or stored in Tableau Server, and the access token can be used only by Tableau on behalf of users.

  • Convenience: Instead of having to embed your data source ID and password in multiple places, you can use the token provided for a particular data provider for all published workbooks and data sources that access that data provider.

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.