Navigation

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:

  • SCRAM-SHA-1
  • PLAIN

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.

Install

Windows

  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 mongosql_auth.so 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.

Usage

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.

Note

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.

Notes

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