Managing Users

Authentication needs to be enabled on the server in order to employ user permissions. Authentication is turned on by default in ArangoDB. You should make sure that it was not turned off manually however. Check the configuration file (normally named /etc/arangodb.conf) and make sure it contains the following line in the [server] section:

authentication = true

This will make ArangoDB require authentication for every request (including requests to Foxx apps depending on the option below). If you want to run Foxx apps without HTTP authentication, but activate HTTP authentication for the built-in server APIs, you can add the following line in the [server] section of the configuration:

authentication-system-only = true

The above will bypass authentication for requests to Foxx apps.

When finished making changes, you need to restart ArangoDB, e.g.:

service arangodb restart

User management is possible in the web interface while logged on to the _system database and in arangosh, as well as via the HTTP API.

There is a built-in user account root which cannot be removed. Note that it has an empty password by default, so make sure to set a strong password immediately. Additional users can be created and granted different actions and access levels. ArangoDB user accounts are valid throughout a server instance (across databases).

Actions and Access Levels

An ArangoDB server contains a list of users. It also defines various access levels that can be assigned to a user (for details, see below) and that are needed to perform certain actions. These actions can be grouped into three categories:

• server actions
• database actions
• collection actions

The server actions are

• create user: allows to create a new user.

• update user: allows to change the access levels and details of an existing user.

• drop user: allows to delete an existing user.

• create database: allows to create a new database.

• drop database: allows to delete an existing database.

• shutdown server: remove server from cluster and shutdown

The database actions are tied to a given database, and access levels must be set for each database individually. For a given database the actions are

• create collection: allows to create a new collection in the given database.

• update collection: allows to update properties of an existing collection.

• drop collection: allows to delete an existing collection.

• create index: allows to create an index for an existing collection in the given database.

• drop index: allows to delete an index of an existing collection in the given database.

The collection actions are tied to a given collection of a given database, and access levels must be set for each collection individually. For a given collection the actions are

• read document: read a document of the given collection.

• create document: creates a new document in the given collection.

• modify document: modifies an existing document of the given collection, this can be an update or replace operation.

• drop document: deletes an existing document of the given collection.

• truncate collection: deletes all documents of a given collection.

To perform actions on the server level the user needs at least the following access levels. The access levels are Administrate and No access:

To perform actions in a specific database (like creating or dropping collections), a user needs at least the following access level. The possible access levels for databases are Administrate, Access and No access. The access levels for collections are Read/Write, Read Only and No Access.

Note that the access level Access for a database is always required to perform any action on a collection in that database.

For collections a user needs the following access levels to the given database and the given collection. The access levels for the database are Administrate, Access and No access. The access levels for the collection are Read/Write, Read Only and No Access.

Example

For example, given

• a database example
• a collection data in the database example
• a user JohnSmith

If the user JohnSmith is assigned the access level Access for the database example and the level Read/Write for the collection data, then the user is allowed to read, create, modify or delete documents in the collection data. But the user is, for example, not allowed to create indexes for the collection data nor create new collections in the database example.

Granting Access Levels

Access levels can be managed via the web interface or in arangosh.

In order to grant an access level to a user, you can assign one of three access levels for each database and one of three levels for each collection in a database. The server access level for the user follows from the database access level in the _system database, it is Administrate if and only if the database access level is Administrate. Note that this means that database access level Access does not grant a user server access level Administrate.

Initial Access Levels

When a user creates a database the access level of the user for that database is set to Administrate. The same is true for creating a collection, in this case the user get Read/Write access to the collection.

Wildcard Database Access Level

With the above definition, one must define the database access level for all database/user pairs in the server, which would be very tedious. In order to simplify this process, it is possible to define, for a user, a wildcard database access level. This wildcard is used if the database access level is not explicitly defined for a certain database. Each new created user has an initial database wildcard of No Access.

Changing the wildcard database access level for a user will change the access level for all databases that have no explicitly defined access level. Note that this includes databases which will be created in the future and for which no explicit access levels are set for that user!

If you delete the wildcard, the default access level is defined as No Access.

The root user has an initial database wildcard of Administrate.

Example

Assume user JohnSmith has the following database access levels:

This will give the user JohnSmith the following database level access:

• database shop1: Administrate
• database shop2: No Access
• database something: Access

If the wildcard * is changed from Access to No Access then the permissions will change as follows:

• database shop1: Administrate
• database shop2: No Access
• database something: No Access

Wildcard Collection Access Level

For each user and database there is a wildcard collection access level. This level is used for all collections pairs without an explicitly defined collection access level. Note that this includes collections which will be created in the future and for which no explicit access levels are set for a that user! Each new created user has an initial collection wildcard of No Access.

If you delete the wildcard, the system defaults to No Access.

The root user has an initial collection wildcard of Read/Write in every database.

When creating a user through db._createDatabase(name, options, users) the access level of the user for this database will be set to Administrate and the wildcard for all collections within this database will be set to Read/Write.

Example

Assume user JohnSmith has the following database access levels:

and collection access levels:

Then the user doe will get the following collection access levels:

• database shop1, collection products: Read-Only
• database shop1, collection customers: No Access
• database shop2, collection reviews: Read-Only
• database something, collection else: Read/Write

Explanation:

Database shop1, collection products directly matches a defined access level. This level is defined as Read-Only.

Database shop1, collection customers does not match a defined access level. However, database shop1 matches and the wildcard in this database for collection level is No Access.

Database shop2, collection reviews does not match a defined access level. However, database shop2 matches and the wildcard in this database for collection level is Read-Only.

Database somehing, collection else does not match a defined access level. The database something also does have a direct matches. Therefore the wildcard is selected. The level is Read/Write.

Permission Resolution

The access levels for databases and collections are resolved in the following way:

For a database “foo”:

1. Check if there is a specific database grant for foo, if yes use the granted access level
2. Choose the higher access level of::
   • A wildcard database grant ( for example grantDatabase('user', '*', 'rw')
   • A database grant on the _system database

For a collection named “bar”:

1. Check if there is a specific database grant for bar, if yes use the granted access level
2. Choose the higher access level of::
   • Any wildcard access grant in the same database, or on "*" (in this example grantCollection('user', 'foo', '*', 'rw'))
   • The access level for the current database (in this example grantDatabase('user', 'foo', 'rw')
   • The access level for the _system database

An exception to this are system collections, here only the access level for the database is used.

System Collections

The access level for system collections cannot be changed. They follow different rules than user defined collections and may change without further notice. Currently the system collections follow these rules:

All other system collections have access level Read/Write if the user has Administrate access to the database. They have access level Read/Only if the user has Access to the database.

To modify these system collections you should always use the specialized APIs provided by ArangoDB. For example no user has access to the _users collection in the _system database. All changes to the access levels must be done using the @arangodb/users module, the /_users/ API or the web interface.

LDAP Users

ArangoDB supports LDAP as an external authentication system. For detailed information please have look into the LDAP configuration guide.

There are a few differences to normal ArangoDB users:

• ArangoDB does not “know” LDAP users before they first authenticate. Calls to various APIs using endpoints in _api/users/* will fail until the user first logs-in.
• Access levels of each user are periodically updated. This will happen by default every 5 minutes.
• It is not possible to change permissions on LDAP users directly, only on roles
• LDAP users cannot store configuration data per user (affects for example custom settings in the graph viewer).

To grant access for an LDAP user you will need to create roles within the ArangoDB server. A role is just a user with the :role: prefix in its name. Role users cannot login as database users, the :role: prefix ensures this. Your LDAP users will need to have at least one role, once the user logs in he will be automatically granted the union of all access rights of all his roles. Note that a lower right grant in one role will be overwritten by a higher access grant in a different role.