This topic tries to clarify some design and implementation ideas that have traditionally been part of Web Data Connector.
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:
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.
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
For performance purposes, a
dataContainer passed to the
.parse() function is a mutable object. However, it doesn’t mean directly mutating the
dataContainer object will take 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. To create a custom authentication connector, see Create a Custom Authentication Connector.
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.
|dbclass||String||The identifier for your oauthConfig||Yes||The dbclass must be same with as the
|clientIdDesktop||String||Client ID you registered for Tableau Desktop||No||This is not considered a secret and will be stored in plain text|
|clientSecretDesktop||String||Client Secret you registered for Tableau Desktop||No||This is not considered a secret and will be stored in plain text|
|redirectUrisDesktop||String||Redirect Urls for Desktop||No||Only required when
|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|
|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
|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, 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 retrive userinfo. Use together with OAUTH_CAP_SUPPORTS_GET_USERINFO_FROM_ID_TOKEN|
|[your own field]||No||No||It is usually not needed to define your own field, and this field will not be able to participate in any OAuth flow.|
This set of OAuth configuration capabilities is not shared with the regular connector capabilities.
|OAUTH_CAP_SUPPORTS_CUSTOM_DOMAIN||Whether your OAuth provider supports custom domain. i.e. OAuth endpoint host is not 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 are 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 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 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 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. To create a multiple table connector, see Create a Multi-table Connector.