Docs Menu
Docs Home
BI Connector


On this page

  • MongoDB Authentication
  • BI Connector Authentication
  • Client Authentication

The MongoDB Connector for BI supports the following authentication mechanisms for authenticating with MongoDB and for authenticating connecting users:


  • SCRAM-SHA-256


  • GSSAPI (Kerberos)

The BI Connector (mongosqld) uses admin credentials to authenticate with MongoDB and sample data to generate the BI Connector's schema. When a client connects to the BI Connector, mongosqld passes connecting client credentials to MongoDB for authentication and will display and restrict data according to the connecting user's permissions.

The following sections will guide you through configuring the BI Connector to authenticate with your MongoDB deployment, configuring authentication of users connecting to the BI Connector, and how usernames should be formatted from your BI tool using authentcation options.

If authentication is enabled on your MongoDB deployment, you must configure the BI Connector to use the required authentication mechanism and provide admin user credentials. The admin user credentials must be authorized to view the superset of data you wish to query using the BI Connector.

If your BI tool is using the MongoDB BI Connector ODBC Driver, the driver will handle authentication and you do not need to install an authentication plugin. If you are not using the MongoDB BI Connector ODBC Driver and need to authenticate using your BI tool, install either the C or JDBC authentication plugin depending on which is compatible with your BI Tool:

C Authentication Plugin
Instructions for installing the C Authentication Plugin, which facilitates authentication between the BI Connector and SQL clients such as Tableau and the MySQL shell.
JDBC Authentication Plugin
Instructions for installing the JDBC Authentication Plugin.

For more information on connecting BI Tools to the BI Connector, see Connect BI Tools.


The use of TLS/SSL is recommended in addition to using an authentication plugin as:

  • The SCRAM-SHA-1 and SCRAM-SHA-256 mechanisms hash the passwords in the client plugin. However, all other data is in cleartext.

  • The PLAIN mechanism sends the password in cleartext.

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

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.


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.


X.509 is not supported.

The following example shows how to format a username to authenticate with the BI Connector using Challenge and Response (username and password), LDAP, or Kerberos:

← MySQL Shell Options