C Authentication Plugin

New in version 2.2.

The MongoDB Connector for BI provides a MySQL authentication plugin which implements the client side of MongoDB-supported authentication mechanisms. The mongosql_auth plugin allows you to use MongoDB Connector for BI with a MongoDB instance running with authentication enabled without needing to generate your own SSL certificates for authentication.

This plugin supports the following authentication mechanisms:


Supported Platforms

The plugin is built and tested on the following platforms (all x86_64):

  • Windows 2008 R2
  • OSX 10.12
  • Ubuntu 14.04
  • RHEL 7.0

The plugin is built against MySQL 5.7.18 Community Edition (64-bit), and tested with MySQL 5.7.18 Community Edition and the MongoDB Connector for BI 2.2.



  1. Download the MySQL 5.7.18 installer and install the products needed.
  2. Download the mongosql_auth plugin component .msi installer and install the mongosql_auth plugin component.

MacOS and Linux

  1. Download mongosql_auth plugin library from the releases page.

  2. After downloading, move the file to either:

    • <mysql-home>/lib/plugin/ directory.

      The default location of <mysql-home> varies by platform.

      To discover the location of the plugin directory, run the following at the command line:

      mysql_config --plugindir

    - OR -

    • A directory of your choice if you provide the plugin-dir=<your-install-dir> option to your MySQL client. See the mysql client command example.


The exact procedure for using the C Authentication plugin library varies depending on your SQL client.

This plugin can be used with the 64-bsit version of the the MySQL shell and the MySQL ODBC driver.

mysql Options

The following table lists some mysql command-line options available for use with mongosql_auth. For a complete list of command line options, refer to the MySQL client documentation.

Option Value Notes
--default-auth mongosql_auth Use the C Authentication plugin. You can specify the plugin as part of your command, include it as a ODBC Connection Parameter, or include it in a MySQL Configuration File.
--user <your-username>

Possible parameters to this option are source=<authenticated-db> and mechanism=<auth-mechanism>. If no authenticated database is specified, it defaults to admin. If no authentication mechanism is specified, it defaults to SCRAM-SHA-1.


If you use both the source and mechanism parameters, separate them with a & and enclose the entire option in single quotes. See the example command below.

-p None, shell will prompt Required.
--plugin-dir <your-plugin-dir> Optional. Defaults to <mysql-home>/lib/plugin/.

Example Command

mysql '--user=myTestUser?source=test&mechanism=SCRAM-SHA-1' --default-auth=mongosql_auth --plugin-dir=/usr/bin/mysql/plugins -p

The above command specifies the user with username myTestUser who is authenticated for the database test. The shell will prompt the user for a password.

ODBC Connection Parameter

If you are using the MySQL ODBC driver, the interface you use to configure your DSN may provide a field where you can specify the default authentication plugin to use. Specifying mongosql_auth here will cause the ODBC driver to use the mongosql_auth plugin by default.

Configuration File

MySQL configuration files can be found in many locations, as listed in the MySQL documentation. In one of these files, add a line with default-auth=mongosql_auth to the [client] section or create it if it does not yet exist. To use this same configuration file with an ODBC DSN, provide the USE_MYCNF=1 connection parameter to your ODBC DSN.

Example Steps: Using the C Authentication Plugin

  1. If you haven’t yet set up authenticated users for MongoDB, do that first. See Enable Authentication for more information.

  2. Start a mongod instance with the --auth option. See Authentication for more information about starting mongod with security enabled.

  3. Start mongosqld with the --auth option. See Installation for more information about starting mongosqld.

    mongosqld --schema schema.drdl --auth
  4. Connect to mongosqld with your client program, using the default-auth=mongosql_auth option. The connection command varies by client, but with the MySQL shell the command is as follows:

    mysql --user=<username>?source=<some-db> --default-auth=mongosql_auth -p

In the above command, <some-db> should be the database for which the user is authenticated. The shell will prompt the user for a password. See the table above for additional options.


  • The SCRAM-SHA-1 mechanism hashes the passwords in the client plugin; however, all other data is in cleartext. If possible, use with encrypted connections.
  • The PLAIN mechanism sends the password in cleartext. As such, if possible, you should only use with encrypted connections.