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://user@REALM.COM@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. The simplest way to get mongo-connector running is to create a user with the backup role:

    $ mongo
    replset:PRIMARY> db.getSiblingDB("admin").createUser({
      user: "mongo-connector-username",
      pwd: "password",
      roles: ["backup"]
    })

NOTE: With a sharded cluster, the mongo-connector user must be created on a mongos AND separately on each shard. This enables mongo-connector to authenticate to the cluster as a whole and to each shard individually.

The following table explains what privileges are needed and what the built-in role for MongoDB grants this privilege:

Privilege Needed	Reason	Built-in Role
find on the config.shards collection	Required if the source is a sharded cluster.	backup or clusterMonitor
listDatabases	Required to determine what databases to read from if no --namespace-set is given.	backup or readAnyDatabase
find on the local.oplog.rs collection	Required for tailing the oplog.	backup or clusterManager and readAnyDatabase or read@local
find	Required to read the specified collections given in --namespace-set.	backup or read or readAnyDatabase

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

Authentication on the Target System

If the target system has authentication enabled, mongo-connector needs to authenticate in order to read and write data. The way to configure differs on the target doc manager:

Mongo Doc Manager

Use a config file and pass the target authentication information in a MongoDB connection string:

{  
   "docManagers": [
        {
            "docManager": "mongo_doc_manager",
            "targetURL": "mongodb://mongo-connector-target-user:password@localhost:27017",
        }
    ]
}

Elasticsearch Doc Managers

Use a config file and pass the target authentication information in the target URL:

{  
   "docManagers": [
        {
            "docManager": "elastic2_doc_manager",
            "targetURL": "mongo-connector-target-user:password@localhost:9200",
        }
    ]
}