Managing Users

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

The above will bypass authentication for requests to Foxx apps.

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

User management is possible in the while logged on to the _system database and inarangosh, as well as via the.

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

An ArangoDB server contains a list of users. It also defines variousaccess levels that can be assigned to a user (for details, see below)and that are needed to perform certain actions. These actions can be groupedinto 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 existinguser.

• 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 accesslevels must be setfor each database individually. For a given database the actions are

• 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 thegiven database.

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

The collection actions are tied to a given collection of a givendatabase, 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.

• 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 followingaccess levels. The access levels are Administrate andNo 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 performany action on a collection in that database.

For collections a user needs the following accesslevels to the given database and the given collection. The access levels forthe database are Administrate, Access and No access. The access levelsfor 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 databaseexample and the level Read/Write for the collection data, then the useris allowed to read, create, modify or delete documents in the collectiondata. But the user is, for example, not allowed to create indexes for thecollection data nor create new collections in the database example.

Granting Access Levels

Access levels can be managed via the web interfaceor in .

In order to grant an access level to a user, you can assign one ofthree access levels for each database and one of three levels for eachcollection in a database. The server access level for the user followsfrom the database access level in the system database, it is_Administrate if and only if the database access level isAdministrate. Note that this means that database access levelAccess does not grant a user server access level Administrate.

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

Wildcard Database Access Level

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

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

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 thepermissions will change as follows:

• database shop1: Administrate
• database shop2: 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 throughdb._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 definedaccess level. This level is defined as Read-Only.

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

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

Database somehing, collection else does not match a defined accesslevel. 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”:

• Check if there is a specific database grant for foo, if yes use the granted access level

• Choose the higher access level of::

  • A wildcard database grant ( for example grantDatabase('user', '*', 'rw')
  • A database grant on the system databaseFor a collection named “_bar”:

• Check if there is a specific database grant for bar, if yes use the granted access level

• 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 databaseAn exception to this are system collections, here only the access level for the database is used.

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

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

To modify these system collections you should always use thespecialized APIs provided by ArangoDB. For exampleno user has access to the users_ collection in the systemdatabase. All changes to the access levels must be done using the@arangodb/users_ module, the /_users/ API or the web interface.

LDAP Users

LDAP authentication is only available in the,also available as managed service.

ArangoDB supports LDAP as an external authentication system. For detailedinformation please have look into the.

• ArangoDB does not “know” LDAP users before they first authenticate.Calls to various APIs using endpoints in _api/users/ will *fail untilthe user first logs-in.
• Access levels of each user are periodically updated. This will happen bydefault 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 theArangoDB 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 hewill 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 higheraccess grant in a different role.