---
schema_version: "1"
id: e141216415eee9a4d0ec94a1e0021fbc716b1ebf1ec33f9beb83487139ac0f8a
title: Considerations for Building Your Connector
collection: tableau
version: current
locale: en-us
portal_url: https://docs.salesforce.com/tableau/current/en-us/api/webdataconnector/docs/wdc_dev_considerations.md
canonical_url: https://help.tableau.com/current/api/webdataconnector/en-us/docs/wdc_dev_considerations.html
source_site: help.tableau.com
content_type: documentation
content_hash: 44dee0e4ad46e4da30b2cf51827ffa6626aac27ee51aacf586a6370a8240124d
description: Documentation for the Tableau Web Data Connector
---
**Deprecated** - This repository will be removed with the Tableau 26.3 release.

The Web Data Connector 3.0 framework is deprecated and will not receive further updates. Migrate to the [REST API Connector on Tableau Exchange](https://exchange.tableau.com/products/1111)—built by Tableau, supports JSON and CSV over HTTP GET, Basic/Bearer/OAuth authentication, and runs on Tableau 2023.3 and later. Note: this connector is extract-only and requires a JDBC driver installation.

# 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](https://help.tableau.com/current/api/webdataconnector/en-us/reference/index.html) 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](https://help.tableau.com/current/api/webdataconnector/en-us/docs/wdc_create_basic_auth_connector.html).

### 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](https://help.tableau.com/current/api/webdataconnector/en-us/docs/wdc_create_oauth_connector.html).

#### 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.