Navigation

Connect from Tableau Desktop

The MongoDB Connector for BI is a named connector in Tableau.

Authentication

New in version 2.2: The MongoDB Connector for BI now offers MySQL authentication plugins allowing you to connect with authentication but without TLS/SSL.

There are two options for authenticating your connection:

  1. Use an authentication plugin with either the SCRAM-SHA-1 or PLAIN authentication mechanism.

    Important

    The use of TLS/SSL is recommended as:

    • The SCRAM-SHA-1 mechanism hashes the passwords in the client plugin. However, all other data is in cleartext.
    • The PLAIN mechanism sends the password in cleartext.

    See C Authentication Plugin or Install the JDBC Authentication Plugin for more information on the plugins.

  2. Provide cleartext credentials for simple username/password authentication against a MongoDB database. This method uses MySQL’s built-in mysql_clear_password plugin.

    Note

    Authentication with mysql_clear_password requires the use of TLS/SSL. See Connect from MySQL with Authentication and TLS/SSL for more information.

The MongoDB Connector for BI requires authentication when running with --auth. When the MongoDB Connector for BI receives a connection with authentication credentials from a client, it passes those credentials through to the underlying MongoDB instance.

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) that delegate credential storage to other services, set the source value to $external.

mechanism

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

The PLAIN (LDAP) mechanism requires MongoDB Enterprise, and requires that source be $external.

Note

Neither Kerberos (GSSAPI) nor x.509 are supported.

Example

To authenticate as the user grace with authentication mechanism PLAIN and using an external source, you would use the following username:

grace?mechanism=PLAIN&source=$external

New in version 2.2.

Connect from Tableau with the C Authentication Plugin

1

Download the C Authentication Plugin library.

Navigate to the releases page then download the mongosql_auth plugin library.

macOS

Save the library file mongosql_auth.so to the /usr/local/mysql/lib/plugin/ directory.

If this directory does not exist, create it:

Example

sudo mkdir -p /usr/local/mysql/lib/plugin -m 755
sudo chown -R {user}:admin /usr/local/mysql
tar -xvf /Users/{user}/Downloads/mongosql-auth-osx-x86_64-v{version}.tgz
cp /Users/{user}/Downloads/mongosql-auth-osx-x86_64/lib/mongosql_auth.so ./

Note

This example assumes you downloaded the mongosql_auth plugin to the /Users/{user}/Downloads/ directory.

The plugin does not require MySQL or the MySQL ODBC Connector to be installed.

Windows Run the Windows installer (.msi).
2

Create a MySQL Configuration file. (macOS only)

  1. Create a text file with the following contents:

    [client]
    default-auth=mongosql_auth
    
  2. Save the file to /etc/my.cnf.

3

Create a Tableau Datasource Connection file.

  1. Create a text file with the following contents:

    Platform TDC File Contents
    macOS
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    <?xml version='1.0' encoding='utf-8' ?>
    <connection-customization class='mongodb' version='7.7' enabled='true'>
      <vendor name='mongodb' />
      <driver name='mongodb' />
      <customizations>
        <customization
          name='odbc-connect-string-extras'
          value='USE_MYCNF=1' />
      </customizations>
    </connection-customization>
    
    Windows
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    <?xml version='1.0' encoding='utf-8' ?>
    <connection-customization class='mongodb' version='7.7' enabled='true'>
      <vendor name='mongodb' />
      <driver name='mongodb' />
      <customizations>
        <customization
          name='odbc-connect-string-extras'
          value='DEFAULT_AUTH=mongosql_auth' />
      </customizations>
    </connection-customization>
    
  2. Save this file as mongodb.tdc in the My Tableau Repository for your platform:

    Platform Default TDC Save Path
    macOS /Users/{name}/Documents/My Tableau Repository/Datasources
    Windows C:\Users\{username}\Documents\My Tableau Repository\Datasources
4

Start Tableau.

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

Important

Any time you change a .tdc file, you must restart the Tableau Desktop application for those changes to take effect.

5

Connect using Tableau.

  1. In the left-side navigation under To a server, click on More... then click MongoDB BI Connector.

  2. In the connection dialog box:

    Field Action
    Server Type the hostname or IP address of the MongoDB Connector for BI host.
    Port Type the IANA port number for the MongoDB Connector for BI. The default is 3307.
    Username

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

    Unless you specified a defaultMechanism in your MongoDB Connector for BI Configuration File, you must append the authenticating database to the username.

    Example

    The user myTestUser is authenticated against the test database.

    Screenshot of Tableau with the connection panel open
    • If you are using Username and Password (SCRAM-SHA-1) authentication, the expected authenticating database is admin.
    • If you are using LDAP (PLAIN) authentication, the expected authenticating database is $external.
    Password Type the password associated with the Username.
  3. Click Sign In.

6

Connect using Tableau.

  1. In the left-side navigation under To a server, click on More... then click MongoDB BI Connector.

  2. In the connection dialog box:

    Field Action
    Server Type the hostname or IP address of the MongoDB Connector for BI host.
    Port Type the IANA port number for the MongoDB Connector for BI. The default is 3307.
    Username

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

    Unless you specified a defaultMechanism in your MongoDB Connector for BI Configuration File, you must append the authenticating database to the username.

    Example

    The user biUser is authenticated against the imf database.

    Screenshot of Tableau with the connection panel open
    • If you are using Username and Password (SCRAM-SHA-1) authentication, the expected authenticating database is admin.
    • If you are using LDAP (PLAIN) authentication, the expected authenticating database is $external.
    Password Type the password associated with the Username.
  3. Click Sign In.

Connect from Tableau without Authentication or TLS/SSL

  1. In the left-side navigation under To a server, click on More... then click MongoDB BI Connector.

  2. In the connection dialog box, provide values for these fields:

    Field Action
    Server Type the hostname or IP address of the MongoDB Connector for BI host.
    Port Type the IANA port number for the MongoDB Connector for BI. The default is 3307.
    Username

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

    Unless you specified a defaultMechanism in your MongoDB Connector for BI Configuration File, you must append the authenticating database to the username.

    Example

    Screenshot of Tableau with the MongoDB BI connection panel open
  3. Click Sign In.

Connect from Tableau with Authentication and TLS/SSL

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

Using Tableau 10.3 or Later

With Tableau versions 10.3 or later, Tableau sends passwords in clear text. To configure Tableau to use authentication and TLS/SSL:

1

Create a Tableau Datasource Connection file.

The TDC file allows you to specify the authentication mechanism.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<?xml version='1.0' encoding='utf-8' ?>
<connection-customization class='mongodb' version='7.7' enabled='true'>
  <vendor name='mongodb' />
  <driver name='mongodb' />
  <customizations>
    <customization
      name='odbc-connect-string-extras'
      value='DEFAULT_AUTH=mongosql_auth' />
  </customizations>
</connection-customization>

Save this file as mongodb.tdc in the My Tableau Repository for your platform:

Platform Default TDC Save Path
macOS /Users/{name}/Documents/My Tableau Repository/Datasources
Windows C:\Users\{username}\Documents\My Tableau Repository\Datasources

Important

Any time you change a .tdc file, you must restart the Tableau Desktop application for those changes to take effect.

Tableau applies the authentication settings in the .tdc file to every connection matching the named database vendor and driver.

2

Connect using Tableau.

  1. In the left-side navigation under To a server, click on More... then click MongoDB BI Connector.

  2. In the connection dialog box, provide values for these fields:

    Field Action
    Server Type the hostname or IP address of the MongoDB Connector for BI host.
    Port Type the IANA port number for the MongoDB Connector for BI. The default is 3307.
    Username

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

    Unless you specified a defaultMechanism in your MongoDB Connector for BI Configuration File, you must append the authenticating database to the username.

    Example

    The user reader is authenticated against the admin database.

    Screenshot of Tableau with the connection panel open
    • If you are using Username and Password (SCRAM-SHA-1) authentication, the expected authenticating database is admin.
    • If you are using LDAP (PLAIN) authentication, the expected authenticating database is $external.
    Password Type the password associated with the Username.
    Require SSL Select the checkbox.
    No custom configuration file specified (click to change)... Click this link to configure your SSL certificate.
  3. In the Configure and Use SSL Certificate dialog box:

    Field Action
    Use the following custom SSL certificate file

    Select this to allow you to select an SSL certificate.

    Example

    The user is going to select an SSL certificate.

    Screenshot of Tableau with the SSL Certificate panel open
    Browse... Choose an SSL certificate file on your computer.
  4. Click OK.

  1. Click Sign In.

Using Tableau 10.2 or Earlier

With Tableau versions 10.2 or earlier, you must configure Tableau to send passwords in clear text. To configure Tableau, you can either:

  • Use a Tableau Datasource Connection (TDC) file, or
  • Set the LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN environment variable.

Use a TDC File

1
Create a Tableau Datasource Connection file.

The TDC file is a convenient way to enable the cleartext plugin and specify all of mongosqld‘s TLS/SSL certificates and keys.

To create a TDC file that can connect to the MongoDB Connector for BI with authentication over TLS/SSL, modify the following .tdc file template. Substitute SSLKEY, SSLCERT, and SSLCA appropriately:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<?xml version='1.0' encoding='utf-8' ?>
<connection-customization class='mysql' version='7.7' enabled='true'>
  <vendor name='mysql' />
  <driver name='mysql' />
  <customizations>
    <customization
      name='odbc-connect-string-extras'
      value='SSLKEY={C:\path_to_key\mysql.key};
             SSLCERT={C:\path_to_cert\mysql.crt};
             SSLCA={C:\path_to_CAcert\ca.crt};
             ENABLE_CLEARTEXT_PLUGIN=1;
             SSL_ENFORCE=1' />
  </customizations>
</connection-customization>

Save this file as mysql.tdc in the My Tableau Repository for your platform:

Platform Default TDC Save Path
macOS /Users/{name}/Documents/My Tableau Repository/Datasources
Windows C:\Users\{username}\Documents\My Tableau Repository\Datasources

Important

Any time you change a .tdc file, you must restart the Tableau Desktop application for those changes to take effect.

Tableau applies the TLS/SSL, certificate, and cleartext plugin settings in the .tdc file to every connection matching the named database vendor and driver.

2
Connect using Tableau.
  1. In the left-side navigation under To a server, click on More... then click MongoDB BI Connector.

  2. In the connection dialog box, provide values for these fields:

    Field Action
    Server Type the hostname or IP address of the MongoDB Connector for BI host.
    Port Type the IANA port number for the MongoDB Connector for BI. The default is 3307.
    Username

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

    Unless you specified a defaultMechanism in your MongoDB Connector for BI Configuration File, you must append the authenticating database to the username.

    Example

    The user biUser is authenticated against the imf database.

    Screenshot of Tableau with the connection panel open
    • If you are using Username and Password (SCRAM-SHA-1) authentication, the expected authenticating database is admin.
    • If you are using LDAP (PLAIN) authentication, the expected authenticating database is $external.
    Password Type the password associated with the Username.
  3. Click Sign In.

Set an Environment Variable

1
Start Tableau.
OS X

Open a terminal window and execute the following command:

LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN=1 /Applications/Tableau.app/Contents/MacOS/Tableau
Windows

Add the LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN=1 environment variable to your user environment.

To do this, open a Command Prompt. Press the Win key, type cmd.exe, and press Enter. Then execute the following command:

SETX LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN 1

SETX should respond with the following:

SUCCESS: Specified value was saved.

Then start Tableau.

2
Connect using Tableau.

Click on the MySQL named connection in Tableau’s left hand column. Enter the host and port on which mongosqld is listening, along with the username and password with which to authenticate. Click Sign In to connect.

By default, mongosqld binds to port 3307.

Screenshot of Tableau with the connection panel open