From 8786113f8fe20f058fcbcef01de0a0c0e5c34771 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Torjus=20H=C3=A5kestad?= <torjus@usit.uio.no>
Date: Sun, 8 Feb 2026 15:45:44 +0100
Subject: [PATCH] docs: add OpenBao + Kanidm OIDC integration plan

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/plans/openbao-kanidm-oidc.md | 108 ++++++++++++++++++++++++++++++
 1 file changed, 108 insertions(+)
 create mode 100644 docs/plans/openbao-kanidm-oidc.md

diff --git a/docs/plans/openbao-kanidm-oidc.md b/docs/plans/openbao-kanidm-oidc.md
new file mode 100644
index 0000000..67869af
--- /dev/null
+++ b/docs/plans/openbao-kanidm-oidc.md
@@ -0,0 +1,108 @@
+# OpenBao + Kanidm OIDC Integration
+
+## Overview
+
+Enable Kanidm users to authenticate to OpenBao (Vault) using OIDC, allowing access to secrets based on Kanidm group membership.
+
+## Current State
+
+**Kanidm:**
+- Server: `auth.home.2rjus.net` (kanidm01)
+- Domain: `home.2rjus.net`
+- Groups: `admins`, `users`, `ssh-users`
+- No OIDC clients configured yet
+
+**OpenBao:**
+- Server: `vault.home.2rjus.net` (vault01)
+- Auth: AppRole only (machine-to-machine)
+- No human user authentication configured
+
+## OpenBao OIDC Auth Method
+
+OpenBao includes the JWT/OIDC auth method in the open-source version (unlike Vault Enterprise which gates some auth features). Key points:
+
+- Enable with: `bao auth enable oidc`
+- Supports browser-based OIDC login flow
+- Maps OIDC claims/groups to OpenBao policies
+- Works with both CLI (`bao login`) and Web UI
+
+### Required Configuration
+
+```bash
+bao write auth/oidc/config \
+  oidc_discovery_url="https://auth.home.2rjus.net/oauth2/openid/<client_id>" \
+  oidc_client_id="<client_id>" \
+  oidc_client_secret="<client_secret>" \
+  default_role="default"
+```
+
+### Callback URIs
+
+OpenBao requires specific callback URIs registered in Kanidm:
+
+- **CLI:** `http://localhost:8250/oidc/callback`
+- **Web UI:** `https://vault.home.2rjus.net:8200/ui/vault/auth/oidc/oidc/callback`
+
+## Kanidm OAuth2 Configuration
+
+Kanidm supports declarative OAuth2 client provisioning via NixOS:
+
+```nix
+services.kanidm.provision.systems.oauth2.openbao = {
+  displayName = "OpenBao Secrets";
+  # originUrl - where the client lives
+  # originLanding - where to redirect after auth
+  # basicSecretFile - client secret
+  # scopeMaps - which scopes groups can request
+  # claimMaps - custom claims based on group membership
+};
+```
+
+The `basicSecretFile` should contain the client secret, fetched from Vault.
+
+## Implementation Approach
+
+### 1. Create OAuth2 Client in Kanidm
+
+Add to `services/kanidm/default.nix`:
+- OAuth2 client `openbao` with callback URIs
+- Scope maps for `admins` and `users` groups
+- Claim maps to expose group membership
+
+### 2. Enable OIDC Auth in OpenBao
+
+Options:
+- **Terraform:** Add `vault_jwt_auth_backend` resource in `terraform/vault/`
+- **NixOS:** Configure in vault01 host config
+
+Terraform is probably cleaner since we already manage OpenBao config there.
+
+### 3. Create OpenBao Roles
+
+Map Kanidm groups to policies:
+
+| Kanidm Group | OpenBao Role | Policy |
+|--------------|--------------|--------|
+| `admins` | `admin` | Full read access to secrets |
+| `users` | `user` | Limited read access |
+
+### 4. Chicken-and-Egg Problem
+
+The OAuth2 client secret needs to be stored in OpenBao, but OpenBao needs the secret to configure OIDC auth. Solutions:
+
+1. **Bootstrap manually:** Create initial secret via `bao` CLI
+2. **Two-phase Terraform:** First create the secret, then configure OIDC
+3. **Static secret:** Use a static secret for the OAuth2 client (less ideal)
+
+## Open Questions
+
+1. **Web UI access:** Do we want users logging into the OpenBao web UI, or just CLI?
+2. **Policy granularity:** What secrets should `admins` vs `users` access?
+3. **Token TTL:** How long should OIDC-issued tokens last?
+
+## References
+
+- [OpenBao JWT/OIDC Auth Method](https://openbao.org/docs/auth/jwt/)
+- [OpenBao OIDC Provider Configuration](https://openbao.org/docs/auth/jwt/oidc-providers/)
+- [Kanidm OAuth2 Documentation](https://kanidm.github.io/kanidm/stable/integrations/oauth2.html)
+- [NixOS Kanidm OAuth2 Options](https://search.nixos.org/options?query=services.kanidm.provision.systems.oauth2)