. . .

MongoDB Security

This page contains a guide to set up the authentication and authorization of the connection between ApiOmat and MongoDB.


MongoDB Authentication

MongoDB uses no authentication by default. Enabling authentication is highly recommended in production systems! The following steps will guide through a simple authentication setup sufficient for ApiOmat installations. For more information about MongoDB authentication see https://docs.mongodb.com/manual/core/authentication/.

Authentication change in MongoDB 3

In MongoDB version 3.0, the default authentication method changed from MONGODB-CR to SCRAM-SHA-1 . Both variants are implemented in ApiOmat in version 2.5.3 and newer. If using older versions of ApiOmat, you have to change the authentication scheme in MongoDB as described in the last part of this page.

  1. Create a keyfile containing a basic key. A key’s length must be between 6 and 1024 characters and may only contain characters in the base64 set. The key file must not have group or world permissions on UNIX systems. Key file permissions are not checked on Windows systems.


    openssl rand -base64 741 > mongodb-keyfile
    chown mongod:mongod mongodb-keyfile
    chmod 600 mongodb-keyfile
  2. Edit /etc/mongod.conf and add a line


    keyFile: /path/to/mongodb-keyfile
  3. Restart mongodb

  4. Create a system administrator in mongod:


    use admin
    user: "siteUserAdmin",
    pwd: "password",
    roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
  5. Try to open a collection on apiomat database:

    apiomat database

    > mongo apiomat
    MongoDB shell version: 2.6.7
    connecting to: apiomat
    > db.Customer.find()

    The error { "$err" : "not authorized for query on apiomat.Customer", "code" : 13 } must show up.

  6. Login as admin:


    mongo -u siteUserAdmin -p password --authenticationDatabase admin
  7. Create an ApiOmat user; root role is required to gain access to all created databases. If you do not want to set the ApiOmat user as root on your Mongo DB just follow the MongoDB Authorization guide below.:


    use admin
    user: "apiomat",
    pwd: "12345678",
    roles: [ "root" ]
  8. Set up the password in apiomat.yaml:


    default: apiomat
    default: 12345678

    For a replication setup, see https://docs.mongodb.org/v3.0/tutorial/enable-internal-authentication/

MongoDB Authorization

This section describes how to precisely set up an authorization protected mongodb and how to configure ApiOmat to use it.
If you accept the the root role for the ApiOmat user within the first section you can skip this guide.

But if you do not want to give root role to the ApiOmat user the following guide lists the required roles.

Create an apiomat user with limited roles:

  • connect to admin mongodb: mongo admin

  • db.createUser({user:"apiomat", pwd:"<password>", roles:["readWrite", "dbAdmin", "userAdmin", "clusterMonitor"]}

Mongodb Build-in roles

Role 'readWrite' = provides all the privileges of the read role plus ability to modify data on all non-system collections

Role 'dbadmin' = provides different actions on the database’s system.indexes, system.namespaces, and system.profile collections (dbAdmin can sends queries but have not full control over mongodb)

Role 'userAdmin' = provides the ability to create and modify roles and users for a database, especially needed for command createUser for creating tmp users

Role 'clusterMonitor' = provides read-only access to monitoring tools, especially needed for the commands: listDatabases, shardingState and serverStatus

Overview MongoDB Built-In Roles:

Database Use Roles: read, readWrite

Database Administration Roles: dbAdmin, dbOwner, userAdmin

Cluster Administration Roles: clusterAdmin, clusterManager, clusterMonitor, hostManager

... and many more

See https://docs.mongodb.com/manual/reference/built-in-roles/#database-user-roles for further information about the build-in roles of mongodb.


Possible problems (Authentication scheme)

If you start the tomcat and in the log the message "MongoFacade - Error ensure indexes, dbName apiomat ..." occurs, than in the mongodb-log you get the message "Failed to authenticate". To solve this problem, you have to delete all users and change the scheme from version 5 to 3.


use admin
db.system.version.insert({ "_id" : "authSchema", "currentVersion" : 3})

Now you have to restart the mongodb and create a new user and go on with step 7.