Usage with Authentication

Mongo Connector supports all authentication mechanisms provided by MongoDB. By default, Mongo Connector will use the MONGODB-CR ("challenge-response") authentication mechanism for MongoDB < 2.8 and SCRAM-SHA-1 (the new default auth mechanism) on MongoDB 2.8 and above. This is the default way of authenticating in MongoDB. This page explains how to use authentication with mongo-connector and assumes you already have a replica set or sharded cluster running with auth enabled. For detailed instructions on how to do this, please visit the MongoDB Authentication Manual.

There are two ways to provide the password for the Mongo Connector's user: on the command line/configuration file, or in a separate password file.

Providing a Password

Providing the password on the command-line is not recommended, since it will be visible when listing processes (e.g., with ps on linux). However, it can be useful for testing. Basic usage is as follows:

mongo-connector -m localhost:27017 -t http://localhost:8983/solr -d solr_doc_manager \
                --admin-username <administrator username> \
                --password <administrator password>

Alternatively, you may specify the password in Mongo Connector's configuration file under authentication.password. This will keep it safe from programs like ps.

Providing a Password File

Using a password file is much safer than providing a plaintext password on the command-line, since the password won't be revealed by tools like ps on Linux. If you have a user user with a password password, you can set up a password file to use with Mongo Connector as follows:

# Create password file. Use -n to prevent a trailing newline from being written.
echo -n 'password' > passwordfile

mongo-connector -m localhost:27017 -t http://localhost:8983/solr -d solr_doc_manager.py \
                --admin-username <administrator username>
                --password-file passwordfile

Note that mongo-connector currently only authenticates as a single user, the "admin user". Although this user doesn't actually need to be the superuser for your mongodb cluster, this user needs to be able to query the oplog.rs collection as well as any namespaces provided in --namespace-set. If no --namespace-set is provided, the user needs to be able to query every collection.

Using Other Authentication Mechanisms

Since any MongoDB connection string can be provided to the -m option of Mongo Connector, Mongo Connector also supports any connection type that can be expressed in the URI. This includes support for the authMechanism, authSource, and gssapiServiceName connection arguments. Mongo Connector can also use SSL and validate x509 certificates. See authentication options in the MongoDB Manual for details.

Examples

• Authenticate with a username and password using the default MONGODB-CR (pre-MongoDB 2.8) or SCRAM-SHA-1 (2.8+) mechanisms:

    mongo-connector -m mongodb://username:password@localhost:27017 ...
  

• Authenticate using Kerberos (requires the pykerberos package to be installed):

    mongo-connector -m mongodb://[email protected]@localhost/?authMechanism=GSSAPI&authSource=$external&gssapiServiceName=mongodb ...
  

• Authenticate using the default mechanism over SSL:

    mongo-connector -m mongodb://username:password@localhost:27017/?ssl=true
  

• Connect over SSL to MongoDB. Require and validate the server's certificate:

    mongo-connector --ssl-certfile client.pem --ssl-certificate-policy required ...
  

Required Permissions

Mongo Connector authenticates only as one user. What privileges the user needs depend on the type of MongoDB cluster from which you're reading. The following table explains what privileges are needed in what scenario, and what the default built-in role for MongoDB is granting this permission:

Privilege Needed	Reason	Built-in Role
listShards	Required if connecting from a sharded cluster.	clusterManager
listDatabases	Required to determine what databases to read from if no --namespace-set is given.	readAnyDatabase
read the local.oplog.rs collection	Required for tailing the oplog.	clusterManager
find	Required to read the specified collections given in --namespace-set.	read or readAnyDatabase

Note that in order to read the oplog, the user needs to be defined in the admin database.