htwkmooc/poseidon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add documentation on authenticating against Nomad

Browse Source
This commit is contained in:
Jan-Eric Hellenberg
2021-07-26 15:00:43 +02:00
committed by Jan-Eric Hellenberg
parent 3aa1227db6
commit f323bdf169
2 changed files with 56 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
README.md
View File

@ -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.