Docs Menu
Docs Home
/
BI Connector

Authentication

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-1

  • SCRAM-SHA-256

  • PLAIN (LDAP)

  • 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.

MongoDB Authentication

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.

Note

For information on how to configure SCRAM on your MongoDB deployment, see SCRAM.

To enable Challenge and Response (SCRAM-SHA-1) as your BI Connector authentication mechanism for MongoDB, you must add the following settings to your mongosqld configuration file:

mongodb:
  net:
    auth:
      username: <admin-username>
      password: <admin-password>
      source: <auth-db-name>
      mechanism: "SCRAM-SHA-1"

For more information on MongoDB host configuration file settings, see:

Note

For information on how to configure LDAP on your MongoDB deployment, see LDAP Proxy Authentication.

To enable LDAP (PLAIN) as your BI Connector authentication mechanism for MongoDB, you must add the following settings to your mongosqld configuration file:

mongodb:
  net:
    auth:
      username: <admin-username>
      password: <admin-password>
      mechanism: "PLAIN"

For more information on MongoDB host configuration file settings, see:

To enable Kerberos (GSSAPI) as your BI Connector authentication mechanism for MongoDB, you must add the following settings to your mongosqld configuration file:

mongodb:
  net:
    auth:
      username: <admin-username>
      password: <admin-password>
      mechanism: "GSSAPI"

For more information on MongoDB host configuration file settings, see:

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

BI Connector Authentication

To enable Challenge and Response (SCRAM-SHA-1) as your BI Connector authentication mechanism, you must add security.enabled : true to your mongosqld configuration file:

security:
  enabled: true

SCRAM-SHA-1 is the default authentication mechanism when mechanism is not specified in the username and security is enabled. If you want to omit source from the username, add and set security.defaultSource : <authenticationDatabase> in the configuration file:

security:
  enabled: true
  defaultSource: "admin"

For more information on the BI Connector's configuration file settings, see:

To enable LDAP (PLAIN) as your BI Connector authentication mechanism, you must add security.enabled : true to your mongosqld configuration file:

security:
  enabled: true

If you want to omit adding mechanism and source to the username, add and set these option/value pairs to your mongosqld configuration file:

The resulting security block in your mongosqld configuration file should look like this:

security:
  enabled: true
  defaultMechanism: "PLAIN"
  defaultSource: "$external"

For more information on the BI Connector's configuration file settings, see:

To enable Kerberos (GSSAPI) as your BI Connector authentication mechanism, you must add security.enabled : true to your mongosqld configuration file:

security:
  enabled: true

If you want to omit adding mechanism and source to the username, add and set these option/value pairs to your mongosqld configuration file:

The resulting security block in your mongosqld configuration file should look like this:

security:
  enabled: true
  defaultMechanism: "GSSAPI"
  defaultSource: "$external"
  gssapi:
    hostname: "<yourHostname>"
    serviceName: "mongosql"

For more information on the BI Connector's configuration file settings, see:

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

Client Authentication

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.

Important

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.

Authentication Options

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.

X.509 is not supported.

Example

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:

For 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

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

grace?mechanism=PLAIN&source=$external

For 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.

Back

MySQL Shell Options

Next

C Authentication Plugin