ArangoDB Server LDAP Options

This feature is only available in theEnterprise Edition

Basics Concepts

The basic idea is that one can keep the user authentication setup foran ArangoDB instance (single or cluster) outside of ArangoDB in an LDAPserver. A crucial feature of this is that one can add and withdraw usersand permissions by only changing the LDAP server and in particularwithout touching the ArangoDB instance. Changes will be effective inArangoDB within a few minutes.

Since there are many different possible LDAP setups, we must support avariety of possibilities for authentication and authorization. Here isa short overview:

To map ArangoDB user names to LDAP users there are two authenticationmethods called “simple” and “search”. In the “simple” method the LDAP binduser is derived from the ArangoDB user name by prepending a prefix andappending a suffix. For example, a user “alice” could be mapped to thedistinguished name uid=alice,dc=arangodb,dc=com to perform the LDAPbind and authentication.See Simple authentication methodbelow for details and configuration options.

In the “search” method there are two phases. In Phase 1 a genericread-only admin LDAP user account is used to bind to the LDAP serverfirst and search for an LDAP user matching the ArangoDB user name. InPhase 2, the actual authentication is then performed against the LDAPuser that was found in phase 1. Both methods are sensible and arerecommended to use in production.See Search authentication methodbelow for details and configuration options.

Once the user is authenticated, there are now two methods forauthorization: (a) “roles attribute” and (b) “roles search”.

In method (a) ArangoDB acquires a list of roles the authenticated LDAPuser has from the LDAP server. The actual access rights to databasesand collections for these roles are configured in ArangoDB itself.The user effectively has the union of all access rights of all roleshe has. This method is probably the most common one for production usecases. It combines the advantages of managing users and roles outside ofArangoDB in the LDAP server with the fine grained access control withinArangoDB for the individual roles. See Roles attributebelow for details about method (a) and for the associated configurationoptions.

Method (b) is very similar and only differs from (a) in the way theactual list of roles of a user is derived from the LDAP server. See Roles search below for details about method (b)and for the associated configuration options.

Fundamental options

The fundamental options for specifying how to access the LDAP server arethe following:

  • —ldap.enabled this is a boolean option which must be set totrue to activate the LDAP feature
  • —ldap.server is a string specifying the host name or IP addressof the LDAP server
  • —ldap.port is an integer specifying the port the LDAP server isrunning on, the default is 389
  • —ldap.basedn specifies the base distinguished name under whichthe search takes place (can alternatively be set via —ldap.url)
  • —ldap.binddn and —ldap.bindpasswd are distinguished name andpassword for a read-only LDAP user to which ArangoDB can bind tosearch the LDAP server. Note that it is necessary to configure thesefor both the “simple” and “search” authentication methods, sinceeven in the “simple” method, ArangoDB occasionally has to refreshthe authorization information from the LDAP servereven if the user session persists and no new authentication isneeded! It is, however, allowed to leave both empty, but then theLDAP server must be readable with anonymous access.
  • —ldap.refresh-rate is a floating point value in seconds. Thedefault is 300, which means that ArangoDB will refresh theauthorization information for authenticated users after at most 5minutes. This means that changes in the LDAP server like removedusers or added or removed roles for a user will be effective afterat most 5 minutes.Note that the —ldap.server and —ldap.port options canalternatively be specified in the —ldap.url string together withother configuration options. For details see Section “LDAP URLs” below.

Here is an example on how to configure the connection to the LDAP server,with anonymous bind:

  1. --ldap.enabled=true \
  2. --ldap.server=ldap.arangodb.com \
  3. --ldap.basedn=dc=arangodb,dc=com

With this configuration ArangoDB binds anonymously to the LDAP serveron host ldap.arangodb.com on the default port 389 and executes all searchesunder the base distinguished name dc=arangodb,dc=com.

If we need a user to read in LDAP here is the example for it:

  1. --ldap.enabled=true \
  2. --ldap.server=ldap.arangodb.com \
  3. --ldap.basedn=dc=arangodb,dc=com \
  4. --ldap.binddn=uid=arangoadmin,dc=arangodb,dc=com \
  5. --ldap.bindpasswd=supersecretpassword

The connection is identical but the searches will be executed with thegiven distinguished name in binddn.

Note here:The given user (or the anonymous one) needs at least read access onall user objects to find them and in the case of Roles searchalso read access on the objects storing the roles.

Up to this point ArangoDB can now connect to a given LDAP serverbut it is not yet able to authenticate users properly with it.For this pick one of the following two authentication methods.

LDAP URLs

As an alternative one can specify the values of multiple LDAP related configurationoptions by specifying a single LDAP URL. Here is an example:

  1. --ldap.url ldap://ldap.arangodb.com:1234/dc=arangodb,dc=com?uid?sub

This one option has the combined effect of setting the following:

  1. --ldap.server=ldap.arangodb.com \
  2. --ldap.port=1234 \
  3. --ldap.basedn=dc=arangodb,dc=com \
  4. --ldap.searchAttribute=uid \
  5. --ldap.searchScope=sub

That is, the LDAP URL consists of the LDAP server and port, a basedn, asearch attribute and a scope which can be one of base, one orsub. There is also the possibility to use the ldaps protocol as in:

  1. --ldap.url ldaps://ldap.arangodb.com:636/dc=arangodb,dc=com?uid?sub

This does exactly the same as the one above, except that it uses theLDAP over TLS protocol. This is a non-standard method which does notinvolve using the STARTTLS protocol. Note that this does not work in theWindows version! We suggest to use the ldap protocol and STARTTLSas described in the next section.

TLS options

TLS is not supported in the Windows version of ArangoDB!

To configure the usage of encrypted TLS to communicate with the LDAP serverthe following options are available:

  • —ldap.tls: the main switch to active TLS. can either be true (use TLS) or false (do not use TLS). It is switched off by default. If you switch this on and do not use the ldaps protocol via the LDAP URL, then ArangoDB will use the STARTTLS protocol to initiate TLS. This is the recommended approach.
  • —ldap.tls-version: the minimal TLS version that ArangoDB should accept. Available versions are 1.0, 1.1 and 1.2. The default is 1.2. If your LDAP server does not support Version 1.2, you have to change this setting.
  • —ldap.tls-cert-check-strategy: strategy to validate the LDAP server certificate. Available strategies are never, hard, demand, allow and try. The default is hard.
  • —ldap.tls-cacert-file: a file path to one or more (concatenated) certificate authority certificates in PEM format. As default no file path is configured. This certificate is used to validate the server response.
  • —ldap.tls-cacert-dir: a directory path to certificate authority certificates in c_rehash format. As default no directory path is configured.Assuming you have the TLS CAcert file that is given to the server at/path/to/certificate.pem, here is an example on how to configure TLS:
  1. --ldap.tls true \
  2. --ldap.tls-cacert-file /path/to/certificate.pem

You can use TLS with any of the following authentication mechanisms.

Esoteric options

The following options can be used to configure advanced options for LDAPconnectivity:

  • —ldap.serialized: whether or not calls into the underlying LDAP library should be serialized.This option can be used to work around thread-unsafe LDAP library functionality.
  • —ldap.serialize-timeout: sets the timeout value that is used when waiting to enter the LDAP library call serialization lock. This is only meaningful when —ldap.serialized has beenset to true.

  • —ldap.retries: number of tries to attempt a connection. Setting this to values greater thanone will make ArangoDB retry to contact the LDAP server in case no connection can be madeinitially.Please note that some of the following options are platform-specific and may not workwith all LDAP servers reliably:

  • —ldap.restart: whether or not the LDAP library should implicitly restart connections

  • —ldap.referrals: whether or not the LDAP library should implicitly chase referralsThe following options can be used to adjust the LDAP configuration on Linux and macOS platforms only, but will not work on Windows:

  • —ldap.debug: turn on internal OpenLDAP library output (warning: will print to stdout).

  • —ldap.timeout: timeout value (in seconds) for synchronous LDAP API calls (a value of 0 means default timeout).
  • —ldap.network-timeout: timeout value (in seconds) after which network operations following the initial connection return in case of no activity (a value of 0 means default timeout).
  • —ldap.async-connect: whether or not the connection to the LDAP library will be done asynchronously.

Authentication methods

In order to authenticate users in LDAP we have two options available.We need to pick exactly one them.

Simple authentication method

The simple authentication method is used if and only if both the—ldap.prefix and —ldap.suffix configuration options are specifiedand are non-empty. In all other cases the“search” authentication method is used.

In the “simple” method the LDAP bind user is derived from the ArangoDBuser name by prepending the value of the —ldap.prefix configurationoption and by appending the value of the —ldap.suffix configurationoption. For example, an ArangoDB user “alice” would be mapped to thedistinguished name uid=alice,dc=arangodb,dc=com to perform the LDAPbind and authentication, if —ldap.prefix is set to uid= and—ldap.suffix is set to ,dc=arangodb,dc=com.

ArangoDB binds to the LDAP server and authenticates with thedistinguished name and the password provided by the client. Ifthe LDAP server successfully verifies the password then the user is authenticated.

If you want to use this method add the following example to yourArangoDB configuration together with the fundamental configuration:

  1. --ldap.prefix uid= \
  2. --ldap.suffix ,dc=arangodb,dc=com

This method will authenticate an LDAP user with the distinguished name{PREFIX}{USERNAME}{SUFFIX}, in this case for the arango user aliceit will search for: uid=alice,dc=arangodb,dc=com.This distinguished name will be used as `` for the roles later on.

Search authentication method

The search authentication method is used if at least one of the twooptions —ldap.prefix and —ldap.suffix is empty or not specified.ArangoDB uses the LDAP user credentials given by the —ldap.binddn and—ldap.bindpasswd to perform a search for LDAP users.In this case, the values of the options —ldap.basedn,—ldap.search-attribute, —ldap.search-filter and —ldap.search-scopeare used in the following way:

  • —ldap.search-scope is an LDAP search scope with possible valuesbase (just search the base distinguished name),sub (recursive search under the base distinguished name) orone (search the base’s immediate children) (default: sub)
  • —ldap.search-filter is an LDAP filter expression which limits theset of LDAP users being considered (default: objectClass=* whichmeans all objects)
  • —ldap.search-attribute specifies the attribute in the user objectswhich is used to match the ArangoDB user name (default: uid)Here is an example on how to configure the search method.Assume we have users like the following stored in LDAP:
  1. dn: uid=alice,dc=arangodb,dc=com
  2. uid: alice
  3. objectClass: inetOrgPerson
  4. objectClass: organizationalPerson
  5. objectClass: top
  6. objectClass: person

Where uid is the username used in ArangoDB, and we only searchfor objects of type person then we can add the following to ourfundamental LDAP configuration:

  1. --ldap.search-attribute=uid \
  2. --ldap.search-filter=objectClass=person

This will use the sub search scope by default and will findall person objects where the uid is equal to the given username.From these the dn will be extracted and used as `` inthe roles later on.

Fetching roles for a user

After authentication, the next step is to derive authorizationinformation from the authenticated LDAP user.In order to fetch the roles and thereby the access rightsfor a user we again have two possible options and need to pickone of them. We can combine each authentication methodwith each role method.In any case a user can have no role or more than one.If a user has no role the user will not get any accessto ArangoDB at all.If a user has multiple roles with different rightsthen the rights will be combined and the strongestright will win. Example:

  • alice has the roles project-a and project-b.
  • project-a has no access to collection BData.
  • project-b has rw access to collection BData,
  • hence alice will have rw on BData.Note that the actual database and collection access rightswill be configured in ArangoDB itself by roles in the users module.The role name is always prefixed with :role:, e.g.: :role:project-aand :role:project-b respectively. You can use the normal userpermissions tools in the Web interface or arangosh to configure these.

Roles attribute

The most important method for this is to read off the roles an LDAPuser is associated with from an attribute in the LDAP user object.If the configuration option

  1. --ldap.roles-attribute-name

configuration option is set, then the value of thatoption is the name of the attribute being used.

Here is the example to add to the overall configuration:

  1. --ldap.roles-attribute-name=role

If we have the user stored like the following in LDAP:

  1. dn: uid=alice,dc=arangodb,dc=com
  2. uid: alice
  3. objectClass: inetOrgPerson
  4. objectClass: organizationalPerson
  5. objectClass: top
  6. objectClass: person 
  7. role: project-a
  8. role: project-b

Then the request will grant the roles project-a and project-bfor the user alice after successful authentication,as they are stored within the role on the user object.

An alternative method for authorization is to conduct a search in theLDAP server for LDAP objects representing roles a user has. If theconfiguration option

  1. --ldap.roles-search=<search-expression>

is given, then the string {USER} in <search-expression> is replacedwith the distinguished name of the authenticated LDAP user and theresulting search expression is used to match distinguished names ofLDAP objects representing roles of that user.

Example:

  1. --ldap.roles-search '(&(objectClass=groupOfUniqueNames)(uniqueMember={USER}))'

After a LDAP user was found and authenticated as described in theauthentication section above the {USER} in the search expressionwill be replaced by its distinguished name, e.g. uid=alice,dc=arangodb,dc=com,and thus with the above search expression the actual search expressionwould end up being:

  1. (&(objectClass=groupOfUniqueNames)(uniqueMember=uid=alice,dc=arangodb,dc=com}))

This search will find all objects of groupOfUniqueNames whereat least one uniqueMember has the dn of alice.The list of results of that search would be the list of roles given bythe values of the dn attributes of the found role objects.

Role transformations and filters

For both of the above authorization methods there are furtherconfiguration options to tune the role lookup. In this section wedescribe these further options:

  • —ldap.roles-include can be used to specify a regular expressionthat is used to filter roles. Only roles that match the regularexpression are used.

  • —ldap.roles-exclude can be used to specify a regular expressionthat is used to filter roles. Only roles that do not match the regularexpression are used.

  • —ldap.roles-transformation can be used to specify a regularexpression and replacement text as /re/text/. This regularexpression is applied to the role name found. This is especiallyuseful in the roles-search variant to extract the real role nameout of the dn value.

  • —ldap.superuser-role can be used to specify the role associatedwith the superuser. Any user belonging to this role gains superuserstatus. This role is checked after applying the roles-transformationexpression.

Example:

  1. --ldap.roles-include "^arangodb"

will only consider roles that start with arangodb.

  1. --ldap.roles-exclude=disabled

will only consider roles that do contain the word disabled.

  1. --ldap.superuser-role "arangodb-admin"

anyone belonging to the group “arangodb-admin” will become a superuser.

The roles-transformation deserves a larger example. Assume we are usingroles search and have stored roles in the following way:

  1. dn: cn=project-a,dc=arangodb,dc=com
  2. objectClass: top
  3. objectClass: groupOfUniqueNames
  4. uniqueMember: uid=alice,dc=arangodb,dc=com
  5. uniqueMember: uid=bob,dc=arangodb,dc=com
  6. cn: project-a
  7. description: Internal project A
  9. dn: cn=project-b,dc=arangodb,dc=com
  10. objectClass: top
  11. objectClass: groupOfUniqueNames
  12. uniqueMember: uid=alice,dc=arangodb,dc=com
  13. uniqueMember: uid=charlie,dc=arangodb,dc=com
  14. cn: project-b
  15. description: External project B

In this case we will find cn=project-a,dc=arangodb,dc=com as onerole of alice. However we actually want to configure a role name::role:project-a which is easier to read and maintain for ouradministrators.

If we now apply the following transformation:

  1. --ldap.roles-transformation=/^cn=([^,]*),.*$/$1/

The regex will extract out project-a resp. project-b of thedn attribute.

In combination with the superuser-role we could make allproject-a members arangodb admins by using:

  1. --ldap.roles-transformation=/^cn=([^,]*),.*$/$1/ \
  2. --ldap.superuser-role=project-a

Complete configuration examples

In this section we would like to present complete examplesfor a successful LDAP configuration of ArangoDB.All of the following are just combinations of the details described above.

Simple authentication with role-search, using anonymous LDAP user

This example connects to the LDAP server with an anonymous read-onlyuser. We use the simple authentication mode (prefix + suffix)to authenticate users and apply a role search for groupOfUniqueNames objectswhere the user is a uniqueMember. Furthermore we extract only the cnout of the distinguished role name.

  1. --ldap.enabled=true \
  2. --ldap.server=ldap.arangodb.com \
  3. --ldap.basedn=dc=arangodb,dc=com \
  4. --ldap.prefix uid= \
  5. --ldap.suffix ,dc=arangodb,dc=com \
  6. --ldap.roles-search '(&(objectClass=groupOfUniqueNames)(uniqueMember={USER}))' \
  7. --ldap.roles-transformation=/^cn=([^,]*),.*$/$1/ \
  8. --ldap.superuser-role=project-a

Search authentication with roles attribute using LDAP admin user having TLS enabled

This example connects to the LDAP server with a given distinguished name of anadmin user + password.Furthermore we activate TLS and give the certificate file to validate server responses.We use the search authentication searching for the uid attribute of person objects.These person objects have role attribute(s) containing the role(s) of a user.

  1. --ldap.enabled=true \
  2. --ldap.server=ldap.arangodb.com \
  3. --ldap.basedn=dc=arangodb,dc=com \
  4. --ldap.binddn=uid=arangoadmin,dc=arangodb,dc=com \
  5. --ldap.bindpasswd=supersecretpassword \
  6. --ldap.tls true \
  7. --ldap.tls-cacert-file /path/to/certificate.pem \
  8. --ldap.search-attribute=uid \
  9. --ldap.search-filter=objectClass=person \
  10. --ldap.roles-attribute-name=role