Docs Menu
Docs Home
/
BI Connector
/
/

Connect from Tableau Desktop with Authentication and TLS/SSL

On this page

Prerequisites

Connecting Tableau to the MongoDB Connector for BI requires the following:

Connecting Tableau to the MongoDB Connector for BI requires the following:

  • Tableau version 10.4 or later

  • A running mongod instance

  • A running mongosqld instance

Procedure

The connect Tableau to the MongoDB Connector for BI using TLS/SSL:

1

Download and install the MongoDB BI Connector ODBC Driver.

Download the MongoDB BI Connector ODBC Driver and run the Windows installer (.msi).

2

Create a system DSN.

To securely connect Tableau to the BI Connector, a system DSN configured to use the MongoDB BI Connector ODBC Driver is required. To create a system DSN, follow the steps below:

1

Start the Microsoft ODBC Data Sources program.

Choose the program version (64-bit or 32-bit) which is appropriate for your system and ODBC driver version.

2

Select the System DSN tab.

3

Click the Add button.

Screenshot of the Windows ODBC Administrator application
click to enlarge
4

Select a MongoDB BI Connector ODBC Driver from the list of available drivers.

Select either the MongoDB ODBC ANSI Driver or the MongoDB ODBC Unicode Driver, then click OK.

Note

The ANSI ODBC driver offers maximum performance but has a limited character set. The Unicode ODBC driver supports a wider character set but may be slightly less performant as a result.

5

Fill in the necessary form fields.

Click the Details button to expose the lower half of the form.

The following form fields are required:

Field Name
Description
Data Source Name
A name of your choice.
TCP/IP Server
Address of the server where your mongosqld process is running. If you have enabled BI Connector on MongoDB Atlas, you can find the hostname of the server where mongosqld is running in the connection information for your cluster.
Port
Port number of your mongosqld process.
Database
The name of the database to connect to, e.g. test.
6

Provide connection information.

The following fields are required when running with --auth enabled or when connecting to an BI Connector for Atlas instance.

Field Name
Description
User

Username of the MongoDB user who is authenticated to use your target database.

You can specify the following authentication options after your username as URI-style query parameters:

Connection Option
Description
source

Specify the name of the database which stores the user's credentials. If you do not specify this option, the MongoDB Connector for BI will default to the current database associated with the MySQL connection.

For authentication mechanisms such as PLAIN (LDAP) or GSSAPI (Kerberos) that delegate credential storage to other services, set the source value to $external.

Not required if defaultSource is set in your MongoDB Connector for BI configuration file.

mechanism

Specify the mechanism that the MongoDB Connector for BI should use to authenticate the connection. Accepted values include:

LDAP and Kerberos require MongoDB Enterprise. Set the source to $external when using LDAP or Kerberos.

Not required if defaultMechanism is set in your MongoDB Connector for BI configuration file.

Note

X.509 is not supported.

Example

To authenticate as user grace using the admin database and the Challenge and Response (SCRAM-SHA-1) authentication mechanism, write the username in this format:

grace?source=admin

Example

To authenticate as user grace with the LDAP (PLAIN) authentication mechanism, write the username in this format:

grace?mechanism=PLAIN&source=$external

Example

To authenticate as user grace on the EXAMPLE.COM Kerberos realm with the Kerberos authentication mechanism, write the username in this format:

grace@EXAMPLE.COM?mechanism=GSSAPI&source=$external

For more information about Kerberos configuration, see Configure Kerberos for BI Connector.

Password

The authenticated user's password.

Note

You can't use curly braces ({ }) in your database password because these are special characters in the ODBC driver.

Authentication

The default authentication method. When using the MongoDB BI Connector ODBC Driver, this field is not required.

To use the authentication plugin in conjunction with another ODBC driver, fill in this field with the string mongosql_auth.

7

Fill in the SSL form fields.

Access the TLS/SSL form fields by clicking Details >>, then the SSL tab. The following parameters are available and may be required, depending on your TLS/SSL configuration:

Field Name
Description
SSL Key
The location of the client/server key file.
SSL Cert
The location of the client/server certificate file.
SSL CA File
The location of the file containing a list of trusted certificate authorities.
SSL Cipher
The location of the file containing a list of permitted ciphers.
SSL Mode
Set to REQUIRED to require an encrypted channel. If an encyrpted channel is not provided, the connection fails.
RSA Public Key
The location of the PEM file that contains the RSA public key.

Note

The BI Connector for Atlas uses TLS/SSL but does not require any TLS/SSL settings to be configured in your system DSN.

8

Click the Test button to test the ODBC connection.

If the connection is successful, click OK to add the DSN. If the connection fails, check to make sure your MongoDB user is correctly authenticated for the database named in the connection.

3

Start Tableau.

Start the Tableau Desktop application or restart it if it is already running.

4

Connect using Tableau.

  1. In the left-side navigation under To a server, click on More... then click Other Databases (ODBC).

  2. From the Other Databases (ODBC) dialog box, select your DSN from the dropdown and click Connect.

  3. Once the connection test completes, click Sign In.

1

Download and install the MongoDB BI Connector ODBC Driver.

Download the MongoDB BI Connector ODBC Driver and run the macOS installer (.dmg).

2

Create a system DSN.

To securely connect Tableau to the BI Connector, a system DSN configured to use the MongoDB BI Connector ODBC Driver is required. To create a system DSN, follow the steps below:

1

Launch ODBC Manager.

Note

ODBC Manager is included with the MongoDB BI Connector ODBC Driver.

Important

The 1.0.16 edition of ODBC Manager included with the MongoDB BI Connector ODBC Driver is not compatible with macOS Catalina or later versions of macOS. If you are on Catalina or a later version of macOS, download and install the latest version (1.0.19) of ODBC manager.

2

Click System DSN, then click Add.

ODBC Manager DSN configuration
3

Select a MongoDB BI Connector ODBC Driver from the list of available drivers.

Select either the MongoDB ANSI ODBC driver or the MongoDB Unicode ODBC driver, then click OK.

Note

The ANSI ODBC driver offers maximum performance but has a limited character set. The Unicode ODBC driver supports a wider character set but may be slightly less performant as a result.

4

Enter a Data Source Name (DSN).

Optionally enter a Description.

Note

Do not close the setup window. Proceed to the next step.

5

Add the necessary keywords.

  1. Add a keyword value pair by clicking the Add button.

  2. Modify the Keyword by double-clicking on it, entering the desired keyword, then pressing enter.

  3. Modify the Value by double-clicking on it, entering the desired keyword, then pressing enter.

Using the procedure above, add the following keywords:

Keyword
Value
SERVER

The hostname or IP address of the MongoDB Connector for BI host.

Important

Use 127.0.0.1 to connect via TCP to localhost. Specifying a value other than an IP address, will attempt to connect via Unix socket.

PORT
The IANA port number for the MongoDB Connector for BI. The default is 3307.
DATABASE

The database to use after connecting.

Note

Required when connecting with Microsoft Excel.

For the complete list of ODBC parameters, see Connector/ODBC Connection Parameters.

For example, your user DSN configuration should look similar to the following:

ODBC Manager DSN configuration

Note

Do not close the setup window. Proceed to the next step.

6

Add the authentication keywords.

  1. Add a keyword value pair by clicking the Add button.

  2. Modify the Keyword by double-clicking on it, entering the desired keyword, then pressing enter.

  3. Modify the Value by double-clicking on it, entering the desired keyword, then pressing enter.

Using the procedure above, add the following keywords:

Keyword
Value
UID

The username for the user that can access the active MongoDB Connector for BI database.

You can specify the following authentication options after your username as URI-style query parameters:

Connection Option
Description
source

Specify the name of the database which stores the user's credentials. If you do not specify this option, the MongoDB Connector for BI will default to the current database associated with the MySQL connection.

For authentication mechanisms such as PLAIN (LDAP) or GSSAPI (Kerberos) that delegate credential storage to other services, set the source value to $external.

Not required if defaultSource is set in your MongoDB Connector for BI configuration file.

mechanism

Specify the mechanism that the MongoDB Connector for BI should use to authenticate the connection. Accepted values include:

LDAP and Kerberos require MongoDB Enterprise. Set the source to $external when using LDAP or Kerberos.

Not required if defaultMechanism is set in your MongoDB Connector for BI configuration file.

Note

X.509 is not supported.

Example

To authenticate as user grace using the admin database and the Challenge and Response (SCRAM-SHA-1) authentication mechanism, write the username in this format:

grace?source=admin

Example

To authenticate as user grace with the LDAP (PLAIN) authentication mechanism, write the username in this format:

grace?mechanism=PLAIN&source=$external

Example

To authenticate as user grace on the EXAMPLE.COM Kerberos realm with the Kerberos authentication mechanism, write the username in this format:

grace@EXAMPLE.COM?mechanism=GSSAPI&source=$external

For more information about Kerberos configuration, see Configure Kerberos for BI Connector.

PWD

The password associated with the UID.

Note

You can't use curly braces ({ }) in your database password because these are special characters in the ODBC driver.

For the complete list of ODBC parameters, see Connector/ODBC Connection Parameters.

For example, your user DSN configuration should look similar to the following:

ODBC Manager DSN configuration
7

Add the SSL keywords.

  1. Add a keyword value pair by clicking the Add button.

  2. Modify the Keyword by double-clicking on it, entering the desired keyword, then pressing enter.

  3. Modify the Value by double-clicking on it, entering the desired keyword, then pressing enter.

Note

The BI Connector for Atlas uses TLS/SSL but does not require any TLS/SSL settings to be configured in your system DSN.

Using the procedure above, add the following keywords depending on your TLS/SSL configuration:

Keyword
Value
SSLKEY
The path to the .pem key file.
SSLCERT
The path to the SSL certificate.
SSLMODE
Set to REQUIRED.
SSLCA
The path to the SSL certificate authority file.
SSLCIPHER
The path to the file containing a list of permitted ciphers.
RSAKEY
The path to the PEM file containing the RSA public key.
ENABLE_CLEARTEXT_PLUGIN
Set to 1 to enable cleartext authentication.

Note

If you are connecting with Microsoft Excel, certificates must be located in the /Library/ODBC/ directory.

For the complete list of ODBC parameters, see Connector/ODBC Connection Parameters.

For example, your user DSN configuration should look similar to the following:

ODBC Manager DSN configuration
8

Click OK to finish creating the DSN.

3

Start Tableau.

Start the Tableau Desktop application or restart it if it is already running.

4

Connect using Tableau.

  1. In the left-side navigation under To a server, click on More... then click Other Databases (ODBC).

  2. From the Other Databases (ODBC) dialog box, select your DSN from the dropdown and click Connect.

  3. Once the connection test completes, click Sign In.

Back

Next

On this page