58 lines
2.2 KiB
Markdown
58 lines
2.2 KiB
Markdown
|
# 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
|
||
|
|
|