Creating certificates

The starter provides commands to create all certificates needed for an ArangoDB deployment.

TLS server certificates

To create a certificate used for TLS servers in the keyfile format, you need the public key of the CA (--cacert), the private key of the CA (--cakey) and one or more hostnames (or IP addresses). Then run:

arangodb create tls keyfile \
    --cacert=my-tls-ca.crt --cakey=my-tls-ca.key \
    --host=<hostname> \
    --keyfile=my-tls-cert.keyfile

Make sure to store the generated keyfile (my-tls-cert.keyfile) in a safe place.

To create a certificate used for TLS servers in the crt & key format, you need the public key of the CA (--cacert), the private key of the CA (--cakey) and one or more hostnames (or IP addresses). Then run:

arangodb create tls certificate \
    --cacert=my-tls-ca.crt --cakey=my-tls-ca.key \
    --host=<hostname> \
    --cert=my-tls-cert.crt \
    --key=my-tls-cert.key \

Make sure to protect and store the generated files (my-tls-cert.crt & my-tls-cert.key) in a safe place.

Client authentication certificates

To create a certificate used for client authentication in the keyfile format, you need the public key of the CA (--cacert), the private key of the CA (--cakey) and one or more hostnames (or IP addresses) or email addresses. Then run:

arangodb create client-auth keyfile \
    --cacert=my-client-auth-ca.crt --cakey=my-client-auth-ca.key \
    [--host=<hostname> | --email=<emailaddress>] \
    --keyfile=my-client-auth-cert.keyfile

Make sure to protect and store the generated keyfile (my-client-auth-cert.keyfile) in a safe place.

CA certificates

To create a CA certificate used to sign TLS certificates, run:

arangodb create tls ca \
    --cert=my-tls-ca.crt --key=my-tls-ca.key

Make sure to protect and store both generated files (my-tls-ca.crt & my-tls-ca.key) in a safe place.

Note: CA certificates have a much longer lifetime than normal certificates. Therefore even more care is needed to store them safely.

To create a CA certificate used to sign client authentication certificates, run:

arangodb create client-auth ca \
    --cert=my-client-auth-ca.crt --key=my-client-auth-ca.key

Make sure to protect and store both generated files (my-client-auth-ca.crt & my-client-auth-ca.key) in a safe place.

Note: CA certificates have a much longer lifetime than normal certificates. Therefore even more care is needed to store them safely.

Creating authentication tokens

JWT tokens are used to authenticate servers (within a cluster) with each other.

JWT tokens

To create a file containing an JWT token, run:

arangodb create jwt-secret \
    --secret=my-secret.jwt [--length=32]

Make sure to protect and store the generated file (my-secret.jwt) in a safe place.

Using authentication tokens

ArangoDB deployments that require authentication can be accessed through standard user+password pairs or using a JWT to get “super-user” access.

This super-user access is needed to communicate directly with the Agency or with any server in the deployment. Note that uses super-user access for normal database access is NOT advised.

To create a JWT from the JWT secret file specified using the --auth.jwt-secret option, use the following command:

arangodb auth token --auth.jwt-secret=<secret-file>

To create a complete HTTP Authorization header that can be passed directly to tools like curl, use the following command:

arangodb auth header --auth.jwt-secret=<secret-file>

Using curl with this command looks like this:

curl -v -H "$(arangodb auth header --auth.jwt-secret=<secret-file>)" http://<database-ip>:8529/_api/version

Note the double quotes around $(...).

Both commands support the following options to adjust the generated token:

  • --auth.user <name>: The name of a user account to authenticate as. This creates a JWT user token with the permissions of this user instead of a JWT superuser token.
  • --auth.exp <duration>: The time after which the token expires, relative to the current time, like 30m or 2h. Supported units are h, m, and s (default). Without this option, the token doesn’t expire. Note that the ArangoDB client tools cannot renew expiring user or superuser tokens, unlike session tokens.
  • --auth.paths <path>: A request path that the token can be used for, without the /_db/<database-name> prefix. You can specify the option multiple times. The path must match exactly. Wildcards and prefix matching are not supported. Requests to other paths are rejected.
  • --auth.fields <key>=<value>: An additional field to set in the token, or a field to override. You can specify the option multiple times.

For example, to create a token for the root user that can only be used to query the metrics endpoint:

arangodb auth token --auth.jwt-secret=<secret-file> --auth.user=root --auth.paths=/_admin/metrics/v2