A MySQL authentication plugin that implements the client-side of MongoDB-supported authentication mechanisms for the BI Connector.
Version 1.3 of this plugin supports the following mechanisms:
The plugin is built and tested on the following platforms (all x86_64):
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.
The plugin tarball/installer can be downloaded from the releases page.
First, download the MySQL 5.7.18 installer and install the products you need. Then, install the plugin using the msi installer provided on the releases page.
The plugin library (mongosql_auth.so
) should be installed in <mysql home>/lib/plugin/
.
The default location of <mysql home>
varies by platform, but the location of the plugin directory can be verified by running mysql_config --plugindir
.
Alternatively, the plugin can be installed in a directory of your choice if you provide the plugin-dir=<your_install_dir>
option to your MySQL client.
On Linux, ensure that the libgssapi_krb5
shared library is installed and in the default search path if the GSSAPI mechanism is desired.
This plugin can be used with the 64-bit version of the the MySQL shell and the MySQL ODBC driver.
Authentication parameters can be specified on the user name field.
mechanism (optional)
Default: SCRAM-SHA-1
The authentication mechanism to use. Supported mechanisms are PLAIN
, SCRAM-SHA-1
, SCRAM-SHA-256
, and GSSAPI
.
Example PLAIN authentication:
mysql --default-auth=mongosql_auth -u "username?mechanism=PLAIN"
For GSSAPI authentication, a hostname (not an IP address) is required to form the service principal name (SPN) of the BI Connector service, serviceName/hostname@REALM
. For example:
mysql --default-auth=mongosql_auth -u "username?mechanism=GSSAPI" -h mongosql.example.com
This authenticates the user principal [email protected]
to the service principal mongosql/[email protected]
.
serviceName (optional)
Default: mongosql
The service name of the MongoDB BI Connector. Used for the GSSAPI
mechanism only.
For example:
mysql --default-auth=mongosql_auth -u "username?mechanism=GSSAPI&serviceName=mongosqlservice" -h mongosql.example.com
source (optional)
Default: $external
The authentication source to use. For the GSSAPI and PLAIN mechanisms, the required source is $external
.
For example:
mysql --default-auth=mongosql_auth -u "username?mechanism=SCRAM-SHA-1&source=somedb"
To authenticate with mongosqld
using the mongosql_auth
plugin, you will need to provide the default-auth=mongosql_auth
option to your MySQL client.
There are a number of ways to accomplish this, depending on which client program you are using.
With the MySQL shell, the default-auth option can be specified as follows:
mysql -uusername -ppassword --default-auth=mongosql_auth
To use Kerberos GSSAPI authentication on OSX/Linux, the following considerations must be made:
krb5.conf
configuration is required (exact location is platform dependent). The default realm will be used for GSSAPI authentication.
12.34.56.78 realm.example.com
KRB5_CONFIG
environment variable will be used.mysql
, the plugin will use it to obtain a credential from the KDC.
forwardable = true
setting in the [libdefaults]
section of the krb5.conf file.mysql
, the plugin will use a credential in the default credential cache, created by a preceding call to kinit
.forwardable = true
setting in the [libdefaults]
section of the krb5.conf filekinit
must be run with the -f
flag to request a forwardable (delegatable) TGT.
kinit -f [email protected]
For debugging, Kerberos information can be logged by setting the environment variable KRB5_TRACE
to a file path.
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 auth plugin to use.
Specifying mongosql_auth
here will cause the ODBC driver to use the mongosql_auth
plugin by default.
MySQL configuration files can be found in many locations, as enumerated here.
In one of these files, add a line with default-auth=mongosql_auth
to the [client]
section (or create it if it doesn't yet exist).
To use this same configuration file with an ODBC DSN, provide the USE_MYCNF=1
connection parameter to your ODBC DSN.
Copyright (c) 2018 MongoDB Inc. Dual licensed under the Apache and GPL licenses.