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:

  • Windows 2008 R2 (32- and 64-bit)
  • macOS 10.12 (64-bit)
  • Ubuntu 14.04 (64-bit)
  • RHEL 7.0 (64-bit)

Testing Environment

The plugin was developed 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+.

Installing the Plugin


  1. Download the MySQL 5.7.x 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.

Using the Plugin for Authentication

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

This plugin can be used with either the 32-bit or 64-bit version of the the MySQL shell and the MySQL ODBC driver. The installation directory differs depending on the version you install.

mysql Options

The following table lists some mysql command-line options available for use with mongosql_auth.

See also

A complete list of command line can be found in 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>


Platform Default Location
macOS, Linux <mysql-home>/lib/plugin/
32-bit Windows "C:\Program Files (x86)\MySQL\MySQL Server 5.7\lib\plugin"
64-bit Windows "C:\Program Files\MySQL\MySQL Server 5.7\lib\plugin"


The following command specifies the username myTestUser who is authenticated for the database test. The shell prompts the user for a password.

macOS and Linux:

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

32-bit Windows:

"C:\Program Files (x86)\MySQL\MySQL Server 5.7\bin\mongosqld.exe" ^
  --default-auth=mongosql_auth ^
  --plugin-dir=/usr/bin/mysql/plugins -p

64-bit Windows:

"C:\Program Files\MySQL\MySQL Server 5.7\bin\mongosqld.exe" ^
  --default-auth=mongosql_auth ^
  --plugin-dir=/usr/bin/mysql/plugins -p

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 in that field causes 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. Create the [client] section if it does not exist.

To use this configuration file with an ODBC DSN, add the USE_MYCNF=1 connection parameter to your ODBC DSN.

Using the C Authentication Plugin

  1. If you have not yet set up authenticated users for MongoDB, do that first.

    To learn how to create authenticated users, see Enable Authentication.

  2. Start a mongod instance with the --auth option.

    To learn how to start mongod with security enabled. see Authentication .

  3. Start mongosqld with the --auth option.

    To learn how to start mongosqld, see Start the BI Connector Service.

    macOS and Linux:

    mongosqld --schema schema.drdl --auth


    "C:\Program Files\MongoDB\Connector for BI\{version}\bin\mongosqld.exe" ^
       --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:


    macOS and Linux:

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

    32-bit Windows:

    "C:\Program Files (x86)\MySQL\MySQL Server 5.7\bin\mongosqld.exe" ^
       --user=<username>?source=<some-db> --default-auth=mongosql_auth -p

    64-bit Windows:

    "C:\Program Files\MySQL\MySQL Server 5.7\bin\mongosqld.exe" ^
       --user=<username>?source=<some-db> --default-auth=mongosql_auth -p

    <some-db> should be the database on which you can authenticate. The shell prompts you for a password.

For additional options, see the MySQL Commands.


  • 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. Use encrypted connections with the PLAIN mechanism .