diff --git a/doc/how-to-guides/deploy-hub.md b/doc/how-to-guides/deploy-hub.md index c649a44..815eade 100644 --- 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 ` 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:///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 index b8b3f22..42c09ce 100644 --- 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:// WantedBy=multi-user.target ``` +If authentication is configured in the *Hub*, log in: +```console +$ sudo not-my-board login https:// +``` + 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 index 97304ca..8831117 100644 --- 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:// +``` + 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 index ae8e0e9..e922e61 100644 --- 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*.