Documented arangodb auth commands

Author: ewoutp

docs/Manual/Programs/Starter/Options.md

@@ -94,12 +94,15 @@ and pass it through the `--auth.jwt-secret-path` option.
 For example:
 
 ```bash
-echo "MakeThisSecretMuchStronger" > jwtSecret
+arangodb create jwt-secret --secret=jwtSecret
 arangodb --auth.jwt-secret=./jwtSecret
 ```
 
 All starters used in the cluster must have the same JWT secret.
 
+To use a JWT secret to access the database, use `arangodb auth header`.
+See [Using authentication tokens](./Security.md#using-authentication-tokens) for details.
+
 ## SSL options
 
 The arango starter by default creates a cluster that uses no unencrypted connections (no SSL).

docs/Manual/Programs/Starter/Security.md

@@ -99,3 +99,34 @@ arangodb create jwt-secret \
 ```
 
 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:
+
+```bash
+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:
+
+```bash
+arangodb auth header --auth.jwt-secret=<secret-file>
+```
+
+Using `curl` with this command looks like this:
+
+```bash
+curl -v -H "$(arangodb auth header --auth.jwt-secret=<secret-file>)" http://<database-ip>:8529/_api/version
+```
+
+Note the double quotes around `$(...)`.