Managing Users
Authentication needs to be enabled on the server in order to employ userpermissions. Authentication is turned on by default in ArangoDB. You shouldmake sure that it was not turned off manually however. Check the configurationfile (normally named /etc/arangodb.conf
) and make sure it contains thefollowing line in the [server]
section:
authentication = true
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:
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 interfacewhile logged on to the _system database and inarangosh, as well as via theHTTP API.
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).
Actions and Access Levels
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
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 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.
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 followingaccess levels. The access levels are Administrate andNo access:
server action | server level |
---|---|
create a database | Administrate |
drop a database | Administrate |
create a user | Administrate |
update a user | Administrate |
update user access level | Administrate |
drop a user | Administrate |
shutdown server | Administrate |
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.
database action | database level | collection level |
---|---|---|
create collection | Administrate | Read/Write |
list collections | Access | Read Only |
rename collection | Administrate | Read/Write |
modify collection properties | Administrate | Read/Write |
read properties | Access | Read Only |
drop collection | Administrate | Read/Write |
create an index | Administrate | Read/Write |
drop an index | Administrate | Read/Write |
see index definition | Access | Read Only |
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.
action | collection level | database level |
---|---|---|
read a document | Read/Write or Read Only | Administrate or Access |
create a document | Read/Write | Administrate or Access |
modify a document | Read/Write | Administrate or Access |
drop a document | Read/Write | Administrate or Access |
truncate a collection | Read/Write | Administrate or 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 arangosh.
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.
Initial Access Levels
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:
access level | |
---|---|
database * | Access |
database shop1 | Administrate |
database shop2 | No Access |
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 - 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 explicitlydefined collection access level. Note that this includes collectionswhich will be created in the future and for which no explicit accesslevels are set for a that user! Each new created user has an initialcollection 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 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:
access level | |
---|---|
database * | Access |
and collection access levels:
access level | |
---|---|
database , collection
| Read/Write |
database shop1 , collection products | Read-Only |
database shop1 , collection
| No Access |
database shop2 , collection
| Read-Only |
Then the user doe will get the following collection access levels:
- database
shop1
, collectionproducts
: Read-Only - database
shop1
, collectioncustomers
: No Access - database
shop2
, collectionreviews
: Read-Only - database
something
, collectionelse
: 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 reviews
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”:
- A wildcard database grant ( for example
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 examplegrantCollection('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.
- Any wildcard access grant in the same database, or on
System Collections
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:
collection | access level |
---|---|
users (in _system) | No Access |
_queues | Read-Only |
_frontend | Read/Write |
* | _same as db |
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 theEnterprise Edition,also available as managed service.
ArangoDB supports LDAP as an external authentication system. For detailedinformation please have look into theLDAP 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 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.