# OpenBao + Kanidm OIDC Integration

## Status: Completed

Implemented 2026-02-09.

## Overview

Enable Kanidm users to authenticate to OpenBao (Vault) using OIDC for Web UI access. Members of the `admins` group get full read/write access to secrets.

## Implementation

### Files Modified

| File | Changes |
|------|---------|
| `terraform/vault/oidc.tf` | New - OIDC auth backend and roles |
| `terraform/vault/policies.tf` | Added oidc-admin and oidc-default policies |
| `terraform/vault/secrets.tf` | Added OAuth2 client secret |
| `terraform/vault/approle.tf` | Granted kanidm01 access to openbao secrets |
| `services/kanidm/default.nix` | Added openbao OAuth2 client, enabled imperative group membership |

### Kanidm Configuration

OAuth2 client `openbao` with:
- Confidential client (uses client secret)
- Web UI callback only: `https://vault.home.2rjus.net:8200/ui/vault/auth/oidc/oidc/callback`
- Legacy crypto enabled (RS256 for OpenBao compatibility)
- Scope maps for `admins` and `users` groups

Group membership is now managed imperatively (`overwriteMembers = false`) to prevent provisioning from resetting group memberships on service restart.

### OpenBao Configuration

OIDC auth backend at `/oidc` with two roles:

| Role | Bound Claims | Policy | Access |
|------|--------------|--------|--------|
| `admin` | `groups = admins@home.2rjus.net` | `oidc-admin` | Full read/write to secrets, system health/metrics |
| `default` | (none) | `oidc-default` | Token lookup-self, system health |

Both roles request scopes: `openid`, `profile`, `email`, `groups`

### Policies

**oidc-admin:**
- `secret/*` - create, read, update, delete, list
- `sys/health` - read
- `sys/metrics` - read
- `sys/auth` - read
- `sys/mounts` - read

**oidc-default:**
- `auth/token/lookup-self` - read
- `sys/health` - read

## Usage

### Web UI Login
1. Navigate to https://vault.home.2rjus.net:8200
2. Select "OIDC" authentication method
3. Enter role: `admin` (for admins) or `default` (for any user)
4. Click "Sign in with OIDC"
5. Authenticate with Kanidm

### Group Management
Add users to admins group for full access:
```bash
kanidm group add-members admins <username>
```

## Limitations

**CLI login not supported:** Kanidm requires HTTPS for all redirect URIs on confidential (non-public) OAuth2 clients. OpenBao CLI uses `http://localhost:8250/oidc/callback` which Kanidm rejects. Public clients would allow localhost redirects, but OpenBao requires a client secret for OIDC auth.

## Lessons Learned

1. **Kanidm group names:** Groups are returned as `groupname@domain` (e.g., `admins@home.2rjus.net`), not just the short name
2. **RS256 required:** OpenBao only supports RS256 for JWT signing; Kanidm defaults to ES256, requiring `enableLegacyCrypto = true`
3. **Scope request:** OIDC roles must explicitly request the `groups` scope via `oidc_scopes`
4. **Provisioning resets:** Kanidm provisioning with default `overwriteMembers = true` resets group memberships on restart
5. **Two-phase Terraform:** Secret must exist before OIDC backend can validate discovery URL

## References

- [OpenBao JWT/OIDC Auth Method](https://openbao.org/docs/auth/jwt/)
- [Kanidm OAuth2 Documentation](https://kanidm.github.io/kanidm/stable/integrations/oauth2.html)