Authentication

Client authentication can be achieved by using the Authorization HTTP header in client requests. ArangoDB supports authentication via HTTP Basic or JWT.

Authentication is turned on by default for all internal database APIs but turned off for custom Foxx apps. To toggle authentication for incoming requests to the internal database APIs, use the --server.authentication startup option. This option is turned on by default so authentication is required for the database APIs.

There is an additional option to control authentication for custom Foxx apps. The --server.authentication-system-only startup option controls whether authentication is required only for requests to the internal database APIs and the admin interface. It is turned on by default, meaning that other APIs (this includes custom Foxx apps) do not require authentication.

The default values allow exposing a public custom Foxx API built with ArangoDB to the outside world without the need for HTTP authentication, but still protecting the usage of the internal database APIs (i.e. /_api/, /_admin/) with HTTP authentication.

If the server is started with the --server.authentication-system-only option set to false, all incoming requests need HTTP authentication if the server is configured to require HTTP authentication (i.e. --server.authentication true). Setting the option to true makes the server require authentication only for requests to the internal database APIs and allows unauthenticated requests to all other URLs.

Here is a short summary:

• --server.authentication true --server.authentication-system-only true: This requires authentication for all requests to the internal database APIs but not custom Foxx apps. This is the default setting.
• --server.authentication true --server.authentication-system-only false: This requires authentication for all requests (including custom Foxx apps).
• --server.authentication false: Authentication is disabled for all requests.

Whenever authentication is required and the client has not yet authenticated, ArangoDB returns HTTP 401 (Unauthorized). It also sends the Www-Authenticate response header, indicating that the client should prompt the user for username and password if supported. If the client is a browser, then sending back this header normally triggers the display of the browser-side HTTP authentication dialog. As showing the browser HTTP authentication dialog is undesired in AJAX requests, ArangoDB can be told to not send the Www-Authenticate header back to the client. Whenever a client sends the X-Omit-Www-Authenticate HTTP header (with an arbitrary value) to the server, ArangoDB only sends status code 401, but no Www-Authenticate header. This allows clients to implement credentials handling and bypassing the browser’s built-in dialog.

HTTP Basic Authentication

ArangoDB supports basic authentication with a user name and password. The name and the password of an ArangoDB user account need to be separated by a colon and the entire string needs to be Base64-encoded. The resulting value can be used in the Authorization header of an HTTP request, indicating that the authorization scheme is Basic.

For example, if the name is user and the password pass, the temporary string that needs to be encoded is user:pass. The Base64-encoded value is dXNlcjpwYXNz (e.g. using the btoa() JavaScript function in a browser). The HTTP request header to authenticate is a follows:

Authorization: Basic dXNlcjpwYXNz

If you use a tool like cURL, you can manually specify this header as follows:

curl -H 'Authorization: Basic dXNlcjpwYXNz' ...

However, cURL can also take care of the authentication for you:

curl -u user:pass ...

Bearer Token Authentication

ArangoDB uses a standard JWT-based authentication method. To authenticate via JWT, you must first obtain a JWT token with a signature generated via HMAC with SHA-256. The secret may either be set using --server.jwt-secret or it is randomly generated on server startup.

For more information on JWT please consult RFC7519 and jwt.io .

JWT user tokens

To authenticate with a specific user you need to supply a JWT token containing the preferred_username field with the username. You can either let ArangoDB generate this token for you via an API call or you can generate it yourself (only if you know the JWT secret).

ArangoDB offers a RESTful API to generate user tokens for you if you know the username and password. To do so send a POST request to:

/_open/auth

… containing username and password JSON-encoded like so:

{
  "username": "root",
  "password": "rootPassword"
}

On success, the endpoint returns a 200 OK and an answer containing the JWT in a JSON-encoded object like so:

{ "jwt": "eyJhbGciOiJIUzI1NiI..x6EfI" }

This JWT should then be used within the Authorization HTTP header in subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiI..x6EfI

You can find the expiration date of the JWT token in the exp field, encoded as Unix timestamp in seconds. Please note that all JWT tokens must contain the iss field with string value arangodb. As an example the decoded JWT body would look like this:

{
  "exp": 1540381557,
  "iat": 1537789.55727901,
  "iss": "arangodb",
  "preferred_username": "root"
}

Create a JWT session token

JWT superuser tokens

To access specific internal APIs as well as Agency and DB-Server instances a token generated via POST /_open/auth is not good enough. For these special APIs, you need to generate a special JWT token which grants superuser access. Note that using superuser access for normal database operations is not advised.

For your convenience it is possible to generate this token via the ArangoDB starter CLI.

Should you wish to generate the JWT token yourself with a tool of your choice, you need to include the correct body. The body must contain the iss field with string value arangodb and the server_id field with an arbitrary string identifier:

{
  "exp": 1537900279,
  "iat": 1537800279,
  "iss": "arangodb",
  "server_id": "myclient"
}

For example to generate a token via the jwtgen tool  (note the lifetime of one hour):

jwtgen -s <my-secret> -e 3600 -v -a "HS256" -c 'iss=arangodb' -c 'server_id=myclient'
curl -v -H "Authorization: bearer $(jwtgen -s <my-secret> -e 3600 -a "HS256" -c 'iss=arangodb' -c 'server_id=myclient')" http://<database-ip>:8529/_api/version

Hot-reload JWT secrets

ArangoDB Enterprise Edition

To reload the JWT secrets of a local arangod process without a restart, you may use the following RESTful API. A POST request reloads the secret, a GET request may be used to load information about the currently used secrets.

Get information about the loaded JWT secrets

Hot-reload the JWT secret(s) from disk

Example result:

{
  "error": false,
  "code": 200,
  "result": {
    "active": {
      "sha256": "c6c1021286dfe870b7050f9e704df93c7f1de3c89dbdadc3fb30394bebd81e97"
    },
    "passive": [
      {
        "sha256": "6d2fe32dc4249ef7e7359c6d874fffbbf335e832e49a2681236e1b686af78794"
      },
      {
        "sha256": "448a28491967ea4f7599f454af261a685153c27a7d5748456022565947820fb9"
      },
      {
        "sha256": "6745d49264bdfc2e89d4333fe88f0fce94615fdbdb8990e95b5fda0583336da8"
      }
    ]
  }
}