Connecting to the MongoDB Connector for BI¶

On this page

Authentication
Connect with the MySQL Client
Connect with Tableau

Authentication¶

Changed in version 2.0: Prior to version 2.0, the MongoDB Connector for BI stored its own separate set of credentials.

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. Possible values include:

SCRAM-SHA-1
MONGODB-CR
PLAIN (LDAP SASL)

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

For 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

Authentication requires your client to send your password in plain text, and you must use TLS/SSL to protect your credentials. See Connect from MySQL with Authentication and TLS/SSL for details on how to connect the MySQL command line client to the MongoDB Connector for BI using authentication.

Connect with the MySQL Client¶

You can use the command-line MySQL client to connect to the MongoDB Connector for BI.

Connect from MySQL without Authentication or TLS/SSL¶

To connect to a mongosqld instance listening on the MySQL default port 3307, run the following command:

copy

mysql --protocol tcp --port 3307

Connect from MySQL with Authentication and TLS/SSL¶

To connect to a mongosqld instance listening on port 3307, as user grace using authentication mechanism PLAIN, and using specific TLS/SSL CA and x.509 certificates, run the following command:

copy

mysql --enable-cleartext-plugin --protocol tcp --port 3307 \
  -u 'grace?mechanism=PLAIN&source=$external' \
  --ssl-ca=/path_to_the_CAcert/ca.crt \
  --ssl-key=/path_to_my_certificate_key/mysql.key \
  --ssl-cert=/path_to_my_client_certificate/mysql.crt \
  -p

If using the $external authentication source, wrap your username in single quotes or escape the $ character with a backslash to prevent your shell from performing interpolation.

Authentication requires your client to send your password in plain text. To send the password in plain text, either:

Use the --enable-cleartext-plugin option shown in the previous example, or
Set the environment variable LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN=1.

See the MySQL documentation for additional details on enabling the MySQL cleartext plugin.

Connect with Tableau¶

Connect from Tableau without Authentication or TLS/SSL¶

To connect to the MongoDB Connector for BI:

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

By default, mongosqld binds to port 3307.

Screenshot of Tableau with the MySQL connection panel open

Connect from Tableau with Authentication and TLS/SSL¶

To connect Tableau to the MongoDB Connector for BI using TLS/SSL, you must configure Tableau to send passwords in clear text either by using a Tableau Datasource Connection (TDC) file, or by setting the LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN environment variable.

Using a TDC File¶

1

Configure Tableau Datasource Connection.¶

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:

copy

<?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 XML as a .tdc file in the Datasources directory of your Tableau Repository. On Windows this is typically C:\Users\<username>\Documents\My Tableau Repository\Datasources. On OS X, this is ~/Documents/My Tableau Repository/Datasources.

Important

You must restart Tableau to apply the TDC.

Tableau will apply 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.¶

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.

Using an Environment Variable¶

1

Start Tableau.¶

OS X

Open a terminal window and execute the following command:

copy

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:

copy

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.

← Using the MongoDB Connector for BI Using the MongoDB Connector for BI with Atlas →