Managing Users in the ArangoDB Shell

Connect with arangosh to the server or a Coordinator respectively.The module @arangodb/users exposes a JavaScript API to manage user accounts.

Please note, that for backward compatibility the server access levelsfollow from the database access level on the database _system.

Also note that the server and database access levels are represented as

• rw: for Administrate
• ro: for Access
• none: for No access

This is again for backward compatibility.

Example

Fire up arangosh and require the users module. Use it to create a new user:

arangosh --server.endpoint tcp://127.0.0.1:8529 ...
...
> const users = require('@arangodb/users');
> users.save('JohnSmith', 'mypassword');

It creates a user called JohnSmith with mypassword as password. This userwill have no access at all.

Note that running the command like this may store the password literally inArangoShell’s history. To avoid that, either disable the history(—console.history false) or use a dynamically created password, e.g.:

> passwd = require('internal').genRandomAlphaNumbers(20);
> users.save('JohnSmith', passwd);

The above will print the password on screen (so you can memorize it) but willnot store it in the command history.

While there, you probably want to change the password of the default rootuser too. Otherwise one will be able to connect with the default root userand its empty password. The following commands change the root user’s password:

> passwd = require('internal').genRandomAlphaNumbers(20);
> require('@arangodb/users').update('root', passwd);

Back to our user account JohnSmith. Let us create a new databaseand grant him access to it with grantDatabase():

> db._createDatabase('testdb');
> users.grantDatabase('JohnSmith', 'testdb', 'rw');

This grants the user Administrate access to the databasetestdb. revokeDatabase() will revoke this access level setting.

Note: Be aware that from 3.2 onwards the grantDatabase() will notautomatically grant users the access level to write or read collections in adatabase. If you grant access to a database testdb you willadditionally need to explicitly grant access levels to individualcollections via grantCollection().

The upgrade procedure from 3.1 to 3.2 sets the wildcard database accesslevel for all users to Administrate and sets the wildcard collectionaccess level for all user/database pairs to Read/Write.

Before we can grant JohnSmith access to a collection, we first have toconnect to the new database and create a collection. Disconnect arangoshby pressing Ctrl+C twice. Then reconnect, but to the database we created:

arangosh --server.endpoint tcp://127.0.0.1:8529 --server.database testdb ...
...
> db._create('testcoll');
> const users = require('@arangodb/users');
> users.grantCollection('JohnSmith', 'testdb', 'testcoll', 'rw');

It is not necessary to reconnect to the _system database in order to grantaccess to the collection.

To confirm that the authentication works as expected, try to connect todifferent databases as JohnSmith:

arangosh --server.endpoint tcp://127.0.0.1:8529 --server.username JohnSmith --server.database testdb ...
...
> Connected to ArangoDB 'http+tcp://127.0.0.1:8529, version: 3.5.2 [SINGLE, server], database: 'testdb', username: 'JohnSmith'

arangosh --server.endpoint tcp://127.0.0.1:8529 --server.username JohnSmith --server.database _system ...
...
> Could not connect to endpoint 'tcp://127.0.0.1:8529', database: '_system', username: 'JohnSmith'
> Error message: 'not authorized to execute this request'

You can also use curl to check that you are actually getting HTTP 401(Unauthorized) server responses for requests that require authentication:

curl --dump - http://127.0.0.1:8529/_api/version

Save

users.save(user, passwd, active, extra)

This will create a new ArangoDB user. The user name must be specified in user_and must not be empty. Note that usernames _must not start with :role:(reserved for LDAP authentication).

The password must be given as a string, too, but can be left empty ifrequired. If you pass the special value ARANGODB_DEFAULT_ROOT_PASSWORD, thepassword will be set the value stored in the environment variableARANGODB_DEFAULT_ROOT_PASSWORD. This can be used to pass an instancevariable into ArangoDB. For example, the instance identifier from Amazon.

If the active attribute is not specified, it defaults to true. The _extra_attribute can be used to save custom data with the user.

This method will fail if either the user name or the passwords are notspecified or given in a wrong format, or there already exists a user with thespecified name.

Note: The user will not have permission to access any database. You needto grant the access rights for one or more databases usinggrantDatabase.

Examples

arangosh> require('@arangodb/users').save('my-user', 'my-secret-password');

Show execution results

Hide execution results

{ 
  "user" : "my-user", 
  "active" : true, 
  "extra" : { 
  }, 
  "code" : 201 
}

Grant Database

users.grantDatabase(user, database, type)

This grants type (‘rw’, ‘ro’ or ‘none’) access to the database forthe user. If database is "*", this sets the wildcard database accesslevel for the user user.

The server access level follows from the access level for the database_system.

Revoke Database

users.revokeDatabase(user, database)

This clears the access level setting to the database for the user andthe wildcard database access setting for this user kicks in. In case no wildcardaccess was defined the default is No Access. This will alsoclear the access levels for all the collections in this database.

Grant Collection

users.grantCollection(user, database, collection, type)

This grants type (‘rw’, ‘ro’ or ‘none’) access level to the collection_in _database for the user. If collection is "*" this sets thewildcard collection access level for the user user in databasedatabase.

Revoke Collection

users.revokeCollection(user, database)

This clears the access level setting to the collection collection for theuser user. The system will either fallback to the wildcard collection accesslevel or default to No Access

Replace

users.replace(user, passwd, active, extra)

This will look up an existing ArangoDB user and replace its user data.

The username must be specified in user, and a user with the specified namemust already exist in the database.

The password must be given as a string, too, but can be left empty if required.

If the active attribute is not specified, it defaults to true. Theextra attribute can be used to save custom data with the user.

This method will fail if either the user name or the passwords are not specifiedor given in a wrong format, or if the specified user cannot be found in thedatabase.

Note: this function will not work from within the web interface

Examples

arangosh> require("@arangodb/users").replace("my-user", "my-changed-password");

Show execution results

Hide execution results

{ 
  "user" : "my-user", 
  "active" : true, 
  "extra" : { 
  }, 
  "code" : 200 
}

Update

users.update(user, passwd, active, extra)

This will update an existing ArangoDB user with a new password and other data.

The user name must be specified in user and the user must already exist inthe database.

The password must be given as a string, too, but can be left empty if required.

If the active attribute is not specified, the current value saved for theuser will not be changed. The same is true for the extra attribute.

This method will fail if either the user name or the passwords are not specifiedor given in a wrong format, or if the specified user cannot be found in thedatabase.

Examples

arangosh> require("@arangodb/users").update("my-user", "my-secret-password");

Show execution results

Hide execution results

{ 
  "user" : "my-user", 
  "active" : true, 
  "extra" : { 
  }, 
  "code" : 200 
}

isValid

users.isValid(user, password)

Checks whether the given combination of user name and password is valid. Thefunction will return a boolean value if the combination of user name and passwordis valid.

Each call to this function is penalized by the server sleeping a randomamount of time.

Examples

arangosh> require("@arangodb/users").isValid("my-user", "my-secret-password");

Show execution results

Hide execution results

true

Remove

users.remove(user)

Removes an existing ArangoDB user from the database.

The user name must be specified in User and the specified user must exist inthe database.

This method will fail if the user cannot be found in the database.

Examples

arangosh> require("@arangodb/users").remove("my-user");

Show execution results

Hide execution results

Document

users.document(user)

Fetches an existing ArangoDB user from the database.

The user name must be specified in user.

This method will fail if the user cannot be found in the database.

Examples

arangosh> require("@arangodb/users").document("my-user");

Show execution results

Hide execution results

{ 
  "user" : "my-user", 
  "active" : true, 
  "extra" : { 
  }, 
  "code" : 200 
}

All

users.all()

Fetches all existing ArangoDB users from the database.

Examples

arangosh> require("@arangodb/users").all();

Show execution results

Hide execution results

[ 
  { 
    "user" : "tester", 
    "active" : false, 
    "extra" : { 
    } 
  }, 
  { 
    "user" : "admin", 
    "active" : true, 
    "extra" : { 
    } 
  }, 
  { 
    "user" : "root", 
    "active" : true, 
    "extra" : { 
    } 
  }, 
  { 
    "user" : "my-user", 
    "active" : true, 
    "extra" : { 
    } 
  } 
]

Reload

users.reload()

Reloads the user authentication data on the server

All user authentication data is loaded by the server once on startup only and iscached after that. When users get added or deleted, a cache flush is doneautomatically, and this can be performed by a call to this method.

Examples

arangosh> require("@arangodb/users").reload();

Show execution results

Hide execution results

Permission

users.permission(user, database[, collection])

Fetches the access level to the database or a collection.

The user and database name must be specified, optionally you can specifythe collection name.

This method will fail if the user cannot be found in the database.

Examples

arangosh> require("@arangodb/users").permission("my-user", "testdb");

Show execution results

Hide execution results

rw