# mongodb_user – Adds or removes a user from a MongoDB database

- Synopsis
- Requirements
- Parameters
- Notes
- Examples
- Return Values
- Status

## 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
--- | --- | ---
database - / required |  | The name of the database to add/remove the user from
login_database - |  | The database where login credentials are stored
login_host - | Default: "localhost" | The host running the database
login_password - |  | The password used to authenticate with
login_port - | Default: 27017 | The port to connect to
login_user - |  | The username used to authenticate with
name - / required |  | The name of the user to add or remove aliases: user
password - |  | The password to use for the user
replica_set - |  | Replica set to connect to (automatically connects to primary for writes)

roles
-

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_cert_reqs
-

Choices:
- CERT_REQUIRED ←
- CERT_OPTIONAL
- CERT_NONE

Specifies whether a certificate is required from the other side of the connection, and whether it will be validated if provided.

state
-

Choices:
- present ←
- absent

The database user state

update_password
-

Choices:
- always ←
- on_create

`always` will update passwords if they differ. `on_create` will only set the password for newly created users.

## 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. @see http://api.mongodb.org/python/current/installation.html

## Examples

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

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

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

    # 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)
    - mongodb_user:
        database: burgers
        name: ben
        password: 12345
        roles: read
        state: present
    - mongodb_user:
        database: burgers
        name: jim
        password: 12345
        roles: readWrite,dbAdmin,userAdmin
        state: present
    - mongodb_user:
        database: burgers
        name: joe
        password: 12345
        roles: readWriteAnyDatabase
        state: present

    # add a user to database in a replica set, the primary server is automatically discovered and written to
    - 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+
    - 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

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

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

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

Hint

If you notice any issues in this documentation, you can edit this document to improve it.