# Security & Identity

The Nest's security model is built around three pillars: **identity management** (Keycloak), **secrets management** (Vault), and **network security** (TLS, MetalLB, Traefik middleware).

## Identity: Keycloak

[Keycloak](https://keycloak.org/) is the central identity provider for all user-facing services. It handles authentication, authorization, and single sign-on (SSO) via OpenID Connect (OIDC).

### Configuration

- **Namespace:** `security`
- **Image:** `quay.io/keycloak/keycloak:latest`
- **Hostname:** `sso.mynest.love`
- **Database:** PostgreSQL (`keycloak-postgres.security.svc.cluster.local`)
- **Proxy Headers:** `xforwarded` (required behind HAProxy)

### Authentication Flow

1. User visits a service (e.g., Jellyfin).
2. Service redirects to Keycloak's OIDC authorization endpoint.
3. User authenticates via **WebAuthn passkey** (passwordless).
4. Keycloak issues an ID token and access token.
5. Service validates the token and grants access based on group membership.

### Passkeys (WebAuthn)

- All authentication is **passwordless** after initial setup.
- Users enroll passkeys on their devices (smartphone, security key, etc.).
- Passkeys are stored in Keycloak's `webauthn` credential store.
- Account recovery requires admin intervention + email verification.

### Group-Based Authorization

Access to services is controlled by Keycloak groups:

| Group | Services Unlocked |
|-------|-------------------|
| (default) | Matrix, Vaultwarden, Forgejo, Documentation |
| `media-users` | Jellyfin, Sonarr, Radarr, Bazarr |
| `music-users` | DroppedNeedle, slskd |
| `books-users` | Calibre-Web, Shelfmark, Audiobookshelf |
| `storage-users` | Nextcloud |
| `ttrpg-users` | Foundry VTT |

Groups are managed by an admin. Users request access via the Matrix bot (`@access-bot:starling.mynest.love`).

### Related Documentation

- [Keycloak (Technical)](keycloak-technical.md) — Deep dive into Keycloak configuration
- [Matrix Architecture](matrix-architecture.md) — How MAS integrates with Keycloak

## Secrets Management: HashiCorp Vault

[HashiCorp Vault](https://www.vaultproject.io/) manages secrets for all services. It is deployed as a 3-node Raft cluster with transit sealing via [Keykeeper](vault-and-keykeeper.md).

### Architecture