community.mongodb.mongodb_user – Adds or removes a user from a MongoDB database¶

Note

This plugin is part of the community.mongodb collection (version 1.2.1).

To install it use: ansible-galaxy collection install community.mongodb.

To use it in a playbook, specify: community.mongodb.mongodb_user.

New in version 1.0.0: of community.mongodb

Synopsis
Requirements
Parameters
Notes
Examples
Return Values

Synopsis ¶

Adds or removes a user from a MongoDB database.

Requirements ¶

The below requirements are needed on the host that executes this module.

pymongo

Parameters ¶

Parameter	Choices/Defaults	Comments
auth_mechanism string	Choices: SCRAM-SHA-256 SCRAM-SHA-1 MONGODB-X509 GSSAPI PLAIN	Authentication type.
connection_options list / elements=raw		Additional connection options. Supply as a list of dicts or strings containing key value pairs seperated with '='.
create_for_localhost_exception path		This is parmeter is only useful for handling special treatment around the localhost exception. If `login_user` is defined, then the localhost exception is not active and this parameter has no effect. If this file is NOT present (and `login_user` is not defined), then touch this file after successfully adding the user. If this file is present (and `login_user` is not defined), then skip this task.
database string / required		The name of the database to add/remove the user from. aliases: db
login_database string	Default: "admin"	The database where login credentials are stored.
login_host string	Default: "localhost"	The host running MongoDB instance to login to.
login_password string		The password used to authenticate with. Required when login_user is specified.
login_port integer	Default: 27017	The MongoDB server port to login to.
login_user string		The MongoDB user to login with. Required when login_password is specified.
name string / required		The name of the user to add or remove. aliases: user
password string		The password to use for the user. aliases: pass
replica_set string		Replica set to connect to (automatically connects to primary for writes).
roles list / elements=raw		The database user roles valid values could either be one or more of the following strings: 'read', 'readWrite', 'dbAdmin', 'userAdmin', 'clusterAdmin', 'readAnyDatabase', 'readWriteAnyDatabase', 'userAdminAnyDatabase', 'dbAdminAnyDatabase' Or the following dictionary '{ db: DATABASE_NAME, role: ROLE_NAME }'. This param requires pymongo 2.5+. If it is a string, mongodb 2.4+ is also required. If it is a dictionary, mongo 2.6+ is required.
ssl boolean	Choices: no ← yes	Whether to use an SSL connection when connecting to the database.
ssl_ca_certs string		The ssl_ca_certs option takes a path to a CA file.
ssl_cert_reqs string	Choices: CERT_NONE CERT_OPTIONAL CERT_REQUIRED ←	Specifies whether a certificate is required from the other side of the connection, and whether it will be validated if provided.
ssl_certfile string		Present a client certificate using the ssl_certfile option.
ssl_crlfile string		The ssl_crlfile option takes a path to a CRL file.
ssl_keyfile string		Private key for the client certificate.
ssl_pem_passphrase string		Passphrase to decrypt encrypted private keys.
state string	Choices: absent present ←	The database user state.
update_password string	Choices: always ← on_create	`always` will always update passwords and cause the module to return changed. `on_create` will only set the password for newly created users. This must be `always` to use the localhost exception when adding the first admin user.

Notes ¶

Note

Requires the pymongo Python package on the remote host, version 2.4.2+. This can be installed using pip or the OS package manager. Newer mongo server versions require newer pymongo versions. @see http://api.mongodb.org/python/current/installation.html

Examples ¶

- name: Create 'burgers' database user with name 'bob' and password '12345'.
  community.mongodb.mongodb_user:
    database: burgers
    name: bob
    password: 12345
    state: present

- name: Create a database user via SSL (MongoDB must be compiled with the SSL option and configured properly)
  community.mongodb.mongodb_user:
    database: burgers
    name: bob
    password: 12345
    state: present
    ssl: True

- name: Delete 'burgers' database user with name 'bob'.
  community.mongodb.mongodb_user:
    database: burgers
    name: bob
    state: absent

- name: Define more users with various specific roles (if not defined, no roles is assigned, and the user will be added via pre mongo 2.2 style)
  community.mongodb.mongodb_user:
    database: burgers
    name: ben
    password: 12345
    roles: read
    state: present

- name: Define roles
  community.mongodb.mongodb_user:
    database: burgers
    name: jim
    password: 12345
    roles: readWrite,dbAdmin,userAdmin
    state: present

- name: Define roles
  community.mongodb.mongodb_user:
    database: burgers
    name: joe
    password: 12345
    roles: readWriteAnyDatabase
    state: present

- name: Add a user to database in a replica set, the primary server is automatically discovered and written to
  community.mongodb.mongodb_user:
    database: burgers
    name: bob
    replica_set: belcher
    password: 12345
    roles: readWriteAnyDatabase
    state: present

# add a user 'oplog_reader' with read only access to the 'local' database on the replica_set 'belcher'. This is useful for oplog access (MONGO_OPLOG_URL).
# please notice the credentials must be added to the 'admin' database because the 'local' database is not synchronized and can't receive user credentials
# To login with such user, the connection string should be MONGO_OPLOG_URL="mongodb://oplog_reader:oplog_reader_password@server1,server2/local?authSource=admin"
# This syntax requires mongodb 2.6+ and pymongo 2.5+
- name: Roles as a dictionary
  community.mongodb.mongodb_user:
    login_user: root
    login_password: root_password
    database: admin
    user: oplog_reader
    password: oplog_reader_password
    state: present
    replica_set: belcher
    roles:
      - db: local
        role: read

- name: Adding a user with X.509 Member Authentication
  community.mongodb.mongodb_user:
    login_host: "mongodb-host.test"
    login_port: 27001
    login_database: "$external"
    database: "admin"
    name: "admin"
    password: "test"
    roles:
    - dbAdminAnyDatabase
    ssl: true
    ssl_ca_certs: "/tmp/ca.crt"
    ssl_certfile: "/tmp/tls.key" #cert and key in one file
    state: present
    auth_mechanism: "MONGODB-X509"
    connection_options:
     - "tlsAllowInvalidHostnames=true"

Return Values ¶

Common return values are documented here, the following are the fields unique to this module:

Key	Returned	Description
user string	success	The name of the user to add or remove.

Authors¶

Elliott Foster (@elliotttf)
Julien Thebault (@Lujeni)

community.mongodb.mongodb_user – Adds or removes a user from a MongoDB database¶

Synopsis¶

Requirements¶

Parameters¶

Notes¶

Examples¶

Return Values¶