From f323bdf1694a0383278478467e0f0cd749d758d2 Mon Sep 17 00:00:00 2001
From: Jan-Eric Hellenberg <janeric.hellenberg@gmail.com>
Date: Mon, 26 Jul 2021 15:00:43 +0200
Subject: [PATCH] Add documentation on authenticating against Nomad

---
 README.md                | 26 ++++++++++++++++++++++++++
 docs/poseidon_policy.hcl | 30 ++++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+)
 create mode 100644 docs/poseidon_policy.hcl

diff --git a/README.md b/README.md
index a05405d..77fa1d0 100644
--- a/README.md
+++ b/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.
diff --git a/docs/poseidon_policy.hcl b/docs/poseidon_policy.hcl
new file mode 100644
index 0000000..4b15bf8
--- /dev/null
+++ b/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"
+}