Doc: Add Auth to How-To

holesch · Jul 27, 2024 · d658e5f · d658e5f
1 parent 40846ff
commit d658e5f
Show file tree

Hide file tree

Showing 4 changed files with 55 additions and 1 deletion.
diff --git a/doc/how-to-guides/deploy-hub.md b/doc/how-to-guides/deploy-hub.md
@@ -32,6 +32,48 @@ with users of the board farm. They will need to start their *Agents* and
 *Exporters* with the {option}`--cacert <not-my-board --cacert>` option to trust
 this root CA.
 
+## Configuring Authentication and Authorization
+
+Authentication and authorization is optional, but recommended for a permanent
+deployment. `not-my-board` uses OpenID Connect for authentication. If you don't
+already have an OpenID provider, you can use either self-host an open source
+implementation like Keycloak or use services like Google Identity or Microsoft
+Entra ID.
+
+Start by creating a new Client in the OpenID provider. `not-my-board` uses the
+"Authorization Code Flow with PKCE". The redirect URI is `https://<host>/oidc-callback`.
+
+Add the OpenID configuration information to the *Hub* configuration. For example
+when using Keycloak:
+
+```{code-block} toml
+:caption: /etc/not-my-board/not-my-board-hub.toml
+
+[auth]
+issuer = "http://keycloak.example.com/realms/master"
+# The Client ID is configured in Keycloak
+client_id = "not-my-board"
+# Don't show all claims when logging in
+show_claims = ["sub", "preferred_username"]
+```
+
+Then add permissions for users. You can get the claims from users after they log
+in with `not-my-board login`, or from the OpenID provider.
+
+```{code-block} toml
+:caption: /etc/not-my-board/not-my-board-hub.toml
+
+# [...]
+
+[[auth.permissions]]
+claims.sub = "11111111-2222-3333-4444-000000000000"
+roles = ["exporter", "importer"]
+```
+
+:::{note}
+The *Hub* needs to be restarted, when the configuration changes.
+:::
+
 ## Configuring the systemd Service
 
 Configure `systemd` to listen on port `443`:
@@ -63,7 +105,6 @@ LoadCredential=certkey:/etc/not-my-board/not-my-board.key
 ExecStart=/opt/pipx/venvs/not-my-board/bin/uvicorn --fd 0 --ssl-keyfile ${CREDENTIALS_DIRECTORY}/certkey --ssl-certfile /etc/not-my-board/not-my-board.crt not_my_board:asgi_app
 StandardInput=socket
 StandardOutput=journal
-PrivateNetwork=yes
 DynamicUser=yes
 ```
 

diff --git a/doc/how-to-guides/set-up-agent.md b/doc/how-to-guides/set-up-agent.md
@@ -32,6 +32,11 @@ ExecStart=/usr/local/bin/not-my-board agent https://<my-hub-address>
 WantedBy=multi-user.target
 ```
 
+If authentication is configured in the *Hub*, log in:
+```console
+$ sudo not-my-board login https://<my-hub-address>
+```
+
 Enable and start the service:
 ```console
 $ sudo systemctl enable --now not-my-board-agent

diff --git a/doc/how-to-guides/set-up-exporter.md b/doc/how-to-guides/set-up-exporter.md
@@ -38,6 +38,11 @@ interface with `ufw`, use the following command:
 $ sudo ufw allow in on eno1 to any port 29200:29299 proto tcp comment 'not-my-board exporter'
 ```
 
+If authentication is configured in the *Hub*, log in:
+```console
+$ sudo not-my-board login https://<my-hub-address>
+```
+
 Finally enable and start the `systemd` service:
 ```console
 $ sudo systemctl enable --now not-my-board-exporter@example

diff --git a/doc/reference/cli.md b/doc/reference/cli.md
@@ -14,6 +14,9 @@ Here's a description of all the commands and options `not-my-board` supports.
 **`agent`** \[**`-h`**|**`--help`**\] \[**`--cacert`** *cacert*\] *hub_url*
 : Start an *Agent*.
 
+**`login`** \[**`-h`**|**`--help`**\] \[**`-v`**|**`--verbose`**\] \[**`--cacert`** *cacert*\] *hub_url*
+: Login user.
+
 **`reserve`** \[**`-h`**|**`--help`**\] \[**`-v`**|**`--verbose`**\] \[**`-n`**|**`--with-name`** *name*\] *import_description*
 : Reserve a *Place*.