# Kanidm on Jeeves

Kanidm is served at **https://auth.tmmworkshop.com**. Portal terminates public
HTTPS and forwards requests over Tailscale to Jeeves on port 8443, verifying
Jeeves's TLS certificate. Only the Tailscale interface exposes that backend port.

The service module is automatically imported by `services/default.nix`.
`services/kanidm.nix` pins Kanidm to the 1.11 release series; review the
[upgrade guide](https://kanidm.github.io/kanidm/stable/server_updates.html)
before changing that series. The flake lock determines the patch release.

## Before deployment

1. Point `auth.tmmworkshop.com` at Portal's public address, using the same DNS
   arrangement as `gitea.tmmworkshop.com`. Port 80 must reach Portal for ACME.
2. Enable [HTTPS certificates in Tailscale](https://tailscale.com/kb/1153/enabling-https).
   Jeeves must be able to obtain a certificate for `jeeves.taile39c31.ts.net`.
3. Allow Portal to reach Jeeves on TCP 8443 in your Tailscale policy.

The trusted proxy address in `services/kanidm.nix` is Portal's current Tailscale
IPv4 address, `100.80.102.33`. Update it if Portal is re-enrolled with a new address.
HAProxy connects over IPv4 and replaces incoming `X-Forwarded-For` headers.

## Deploy

Ensure the new Nix file is tracked by Git before using this Git-backed flake.
From this repository, using the existing SSH aliases:

```sh
nixos-rebuild switch --flake .#jeeves --target-host jeeves --sudo
nixos-rebuild switch --flake .#portal-1 --target-host portal-1 --sudo
```

Deploy Jeeves first, then Portal. Portal manages the public Let's Encrypt
certificate. `kanidm-tls.service` on Jeeves obtains the backend certificate and
checks for renewal daily, restarting Kanidm only when the certificate changes.
Private keys are generated at runtime and never stored in this repository or
the Nix store.

On Jeeves, check startup:

```sh
sudo systemctl status kanidm-tls.service kanidm.service
sudo journalctl -u kanidm-tls.service -u kanidm.service -n 100
```

If the initial certificate request fails, fix the Tailscale HTTPS configuration
and run `sudo systemctl restart kanidm.service`; its dependency retries the
certificate request. A successful oneshot certificate service normally appears
as inactive after finishing.

After both hosts are deployed:

```sh
curl --fail https://auth.tmmworkshop.com/status
```

## First login

On Jeeves, recover the initial administrator passwords interactively:

```sh
sudo kanidmd recover-account admin
sudo kanidmd recover-account idm_admin
kanidm login --name idm_admin
kanidm person create richie "Richie"
kanidm person credential create-reset-token richie
```

Store the recovered passwords securely. Follow the reset URL to enroll your
personal account's passkey. `admin` manages the Kanidm server; `idm_admin`
manages people, groups, and application integrations. Creating `richie` does
not automatically grant administrator rights. The client is installed and
configured to use `https://auth.tmmworkshop.com`.

Register each website as its own OAuth2/OIDC client and each backend identity
as a service account, then grant application scopes through groups. This
deployment does not create application clients or change existing sites' login
settings. See the [OAuth2 guide](https://kanidm.github.io/kanidm/stable/integrations/oauth2.html)
and [service-account guide](https://kanidm.github.io/kanidm/stable/accounts/service_accounts.html).

## Storage and recovery

- Database: `/var/lib/kanidm/kanidm.db` on Jeeves's existing ZFS `/var` filesystem.
- Online backups: `/var/lib/kanidm/backups`, daily at 02:30, retaining 14.
- Backend certificate and key: `/var/lib/kanidm-tls`, readable by Kanidm.
- Server configuration: `/etc/kanidm/server.toml`.

The existing `root_pool/var` snapshot policy covers the database and backups.
Copy backups off Jeeves as part of disaster recovery; local snapshots do not
protect against loss of the host. Follow Kanidm's
[backup and restore instructions](https://kanidm.github.io/kanidm/stable/backup_and_restore.html).

The configured identity domain and origin are both `auth.tmmworkshop.com`.
Changing them after enrollment can affect passkeys and application integrations;
follow the [domain rename guide](https://kanidm.github.io/kanidm/stable/domain_rename.html).