Add documentation on authenticating against Nomad

README.md

@@ -61,6 +61,8 @@ For the OpenAPI 3.0 definition of the API Poseidon provides, see [`swagger.yaml`
 
 ⚠️ Don't use authentication without TLS enabled, as otherwise the token will be transmitted in clear text.
 
+#### Poseidon
+
 ⚠ We encourage you to enable authentication for this API. If disabled, everyone with access to your API has also indirectly access to your Nomad cluster as this API uses it.
 
 The API supports authentication via an HTTP header. To enable it, specify the `server.token` value in the `configuration.yaml` or the corresponding environment variable `POSEIDON_SERVER_TOKEN`.
@@ -73,6 +75,30 @@ An example `curl` command with the configured token being `SECRET` looks as foll
 $ curl -H "X-Poseidon-Token: SECRET" http://localhost:7200/api/v1/some-protected-route
 ```
 
+#### Nomad
+
+⚠ Enabling access control in the Nomad cluster is also recommended, to avoid having unauthorized actors perform unwanted actions in the cluster. Instructions on setting up the cluster appropriately can be found in [the Nomad documentation](https://learn.hashicorp.com/collections/nomad/access-control).
+
+Afterwards, it is recommended to create a specific [Access Policy](https://learn.hashicorp.com/tutorials/nomad/access-control-policies?in=nomad/access-control) for Poseidon with the minimal set of capabilities it needs for operating the cluster. A non-minimal example with complete permissions can be found [here](docs/poseidon_policy.hcl). Poseidon requires a corresponding [Access Token](https://learn.hashicorp.com/tutorials/nomad/access-control-tokens?in=nomad/access-control) to send commands to Nomad. A Token looks like this:
+
+```text
+Accessor ID  = 463d3216-dc16-570f-380c-a48f5d26d955
+Secret ID    = ea1ac4c5-892b-0bcc-9fc5-5faeb5273a13
+Name         = Poseidon access token
+Type         = client
+Global       = false
+Policies     = [poseidon]
+Create Time  = 2021-07-26 12:45:11.437786378 +0000 UTC
+Create Index = 246238
+Modify Index = 246238
+```
+
+The `Secret ID` of the Token needs to be specified as the value of `nomad.token` value in the `configuration.yaml` or the corresponding environment variable `POSEIDON_NOMAD_TOKEN`. It may also be required for authentication in the Nomad Web UI and for using the Nomad CLI on the Nomad hosts (where the token can be specified via the `NOMAD_TOKEN` environment variable).
+
+Once configured, all requests to the Nomad API automatically contain a `X-Nomad-Token` header containing the token.
+
+⚠ Make sure that no (overly permissive) `anonymous` access policy is present in the cluster after the policy for Poseidon has been added. Anyone can perform actions as specified by this special policy without authenticating!
+
 ### TLS
 
 We highly encourage the use of TLS in this API to increase the security. To enable TLS, set `server.tls` or the corresponding environment variable to true and specify the `server.certfile` and `server.keyfile` options.

docs/poseidon_policy.hcl

@@ -0,0 +1,30 @@
+// Allow-all access policy
+
+namespace "*" {
+  policy       = "write"
+  capabilities = ["alloc-node-exec", "read-job"]
+}
+
+agent {
+  policy = "write"
+}
+
+operator {
+  policy = "write"
+}
+
+quota {
+  policy = "write"
+}
+
+node {
+  policy = "write"
+}
+
+host_volume "*" {
+  policy = "write"
+}
+
+plugin {
+  policy = "read"
+}