🕐 7 min read
This topic tries to clarify some design and implementation ideas that have traditionally been part of Web Data Connector.
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})
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.
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 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 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 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.
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.
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 |
Yes | |
| refreshTokenResponseMaps | Map<String, String> | Key value pair that maps a refresh token request response 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. |
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 | - |
Web Data Connector 3.0 supports multiple table connectors by default.