Configuring a Connection

After Installing the Connector you can connect and create a Data Source for data in Apache CouchDB.

Setting Up a Data Source

Complete the following steps to connect to the data:

Under Connect | To a Server, click More....
Select the data source called Apache CouchDB by CData.
Enter the information required for the connection.
Click Sign In.
If necessary, select a Database and Schema to discover what tables and views are available.

Using the Connection Builder

The connector makes the most common connection properties available directly in Tableau. However, it can be difficult to use if you need to use more advanced settings or need to troubleshoot connection issues. The connector includes a separate connection builder that allows you to create and test connections outside of Tableau.

There are two ways to access the connection builder:

On Windows, use a shortcut called Connection Builder in the Start menu, under the CData Tableau Connector for Apache CouchDB folder.
You can also start the connection builder by going to the driver install directory and running the .jar file in the lib directory.

In the connection builder, you can set values for connection properties and click Test Connection to validate that they work. You can also use the Copy to Clipboard button to save the connection string. This connection string can be given to the Connection String option included in the connector connection window in Tableau.

Connecting to Apache CouchDB

Set the URL connection property to the URL of your Apache CouchDB instance. For example: http://localhost:5984

If you want your users (or JWTs) to have access only to specific databases, configure the admin_only_all_dbs option in your Apache CouchDB instance to grant all users access to the "/_all_dbs" endpoint, which is required by the connector for listing tables.

Authenticating to Apache CouchDB

Apache CouchDB supports three types of authentication:

Basic: Basic username/password authentication.
JWT: Authentication with a JWT.
None: Anonymous access for databases that are public.

Basic Authentication

Set the following to connect to data:

AuthScheme: Basic.
User The Apache CouchDB user account used to authenticate.
Password The Apache CouchDB password associated with the authenticating user.

JWT Authentication

Set AuthScheme to JWT.

You can either automatically generate (and, if applicable, refresh) a JWT or manually generate one:

Automatic Token Generation

Configure the connector to automatically generate the tokens:

Required

JWTSubject: The name of the user to assign to the JWT.
JWTAlgorithm: The algorithm to use for the JWT signature.
JWTKeyType: The encryption key's type.
JWTKey: The encryption key used to sign the JWT generated by the connector.

Optional

JWTIssuer: The issuer of the JWT.
JWTExpiration: The duration for which the JWT remains valid, in seconds.
JWTHeaders: A collection of extra headers to include in the JWT header.
JWTClaims: A collection of extra claims to include in the JWT payload.
CredentialsLocation: The filepath of the settings file containing the JWT. If a settings file does not exist in this location, the connector creates a new settings file when it retrieves a JWT.

Manual Token Generation

You can generate the tokens yourself manually and pass them to the connector by using the JWTToken connection property.

Generating the Key Pair

When using asymmetric algorithms to sign the tokens, you must generate a private/public key pair. For that, a cryptographic library like OpenSSL can be used. For example:

# generate private key
openssl genrsa --out private_rsa256.pem 2048

# extract public key
openssl rsa -in private_rsa256.pem -pubout > public_rsa256.pem

JWT Configurations

Refer to CouchDB JWT Authentication Documentation for the following.

The alg and sub are required claims and will always be validated by the Apache CouchDB instance. Other required claims can be configured in the server (see required_claims). In that case, you must use JWTHeaders and JWTClaims so that the connector can include those additional claims when generating the JWT.

You can use roles_claim_name or the roles_claim_path options to assign roles to the JWTs.

An example configuration of the server and corresponding sample connection string are shown below:

Example Server Configuration

[chttpd]
...
authentication_handlers = {chttpd_auth, jwt_authentication_handler}, {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, default_authentication_handler}
admin_only_all_dbs = false
...

[jwt_auth]
...
required_claims = exp
roles_claim_path = my.nested._couchdb\.roles
rsa:rsa_256 = -----BEGIN PUBLIC KEY-----\nYOUR_PUBLIC_KEY\n-----END PUBLIC KEY-----\n
...

Example Connection String

Url=http://localhost:5984;
JWTSubject=JWT User 1;
JWTAlgorithm=RS256;
JWTKeyType=PEMKEY_FILE;
JWTKey=PATH_TO_FOLDER\private_rsa256.pem;
JWTHeaders=kid : rsa_256 | Custom Header 1 : Test 1;
JWTClaims= my : eyJuZXN0ZWQiOnsiX2NvdWNoZGIucm9sZXMiOlsidXNlcjIiXX19 | Custom Claim 1 : Test 1;

Anonymous Authentication