joakim/rick-infra
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Vaultwarden password manager role with PostgreSQL and SSO support

Browse Source 
- Implement complete Vaultwarden deployment using Podman Quadlet
- PostgreSQL backend via Unix socket with 777 permissions
- Caddy reverse proxy with WebSocket support for live sync
- Control-node admin token hashing using argon2 (OWASP preset)
- Idempotent token hashing with deterministic salt generation
- Full Authentik SSO integration following official guide
- SMTP email configuration support (optional)
- Invitation-only user registration by default
- Comprehensive documentation with setup and troubleshooting guides

Technical Details:
- Container: vaultwarden/server:latest from Docker Hub
- Database: PostgreSQL via /var/run/postgresql socket
- Port: 8080 (localhost only, proxied by Caddy)
- Domain: vault.jnss.me
- Admin token: Hashed on control node with argon2id
- SSO: OpenID Connect with offline_access scope support

Role includes automatic argon2 installation on control node if needed.
This commit is contained in:
Joakim
2025-12-21 16:13:25 +01:00
parent 89b43180fc
commit bfd6f22f0e
14 changed files with 1346 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

307
docs/vaultwarden-sso-status.md Normal file
View File

@@ -0,0 +1,307 @@
# Vaultwarden SSO Feature Status and Configuration
**Document Date:** December 21, 2025
**Last Updated:** December 21, 2025
**Status:** SSO Configured, Waiting for Stable Release
---
## Executive Summary
Vaultwarden has been successfully deployed with **SSO integration pre-configured** for Authentik. However, SSO functionality is currently **only available in testing images** and not yet in the stable release. This document explains the current state, our decision to wait for stable, and how to activate SSO when it becomes available.
## Current Deployment Status
### What's Working
- ✅ Vaultwarden deployed successfully at `https://vault.jnss.me`
- ✅ PostgreSQL backend via Unix socket
- ✅ Admin panel accessible and working
- ✅ Email/password authentication working
- ✅ SMTP notifications configured
- ✅ All SSO environment variables correctly configured
- ✅ Authentik OAuth2 provider created and ready
### What's Not Working (By Design)
- ❌ SSO login option not appearing on login page
- ❌ "Use single sign-on" button missing
**Reason:** Using stable image (`vaultwarden/server:latest` v1.34.3) which does not include SSO code.
## Investigation Summary (Dec 21, 2025)
### Problem Reported
User deployed Vaultwarden with `vaultwarden_sso_enabled: true` and configured Authentik integration following official guides, but no SSO option appeared on the login page.
### Root Cause Identified
After investigation including:
- Service status check (healthy, running normally)
- Environment variable verification (all SSO vars present and correct)
- Configuration review (matches Authentik integration guide perfectly)
- API endpoint inspection (`/api/config` returns `"sso":""`)
- Official documentation review
**Finding:** SSO feature is only compiled into `vaultwarden/server:testing` images, not stable releases.
### Evidence
From [Vaultwarden Official Wiki](https://github.com/dani-garcia/vaultwarden/wiki):
> **Testing features**
>
> Features available in the `testing` docker image:
> - Single Sign-On (SSO), see [Documentation](https://github.com/dani-garcia/vaultwarden/wiki/Enabling-SSO-support-using-OpenId-Connect)
From [SSO Documentation Page](https://github.com/dani-garcia/vaultwarden/wiki/Enabling-SSO-support-using-OpenId-Connect):
> ⚠️ **Important**
>
> ‼️ ‼️ ‼️
> SSO is currently only available in the `:testing` tagged images!
> The current stable `v1.34.3` **does not** contain the SSO feature.
> ‼️ ‼️ ‼️
### API Response Analysis
```bash
# API config endpoint shows SSO not available
curl -s http://127.0.0.1:8080/api/config | grep -o '"sso":"[^"]*"'
# Returns: "sso":"" ← Empty = feature not compiled in
# Environment variables are set correctly
podman exec vaultwarden env | grep -i sso
SSO_ENABLED=true
SSO_ONLY=false
SSO_CLIENT_ID=DDOQXdwFn6pi4FtSvo7PK5b63pRzyD552xapTZGr
SSO_CLIENT_SECRET=02D308Sle2w2NPsi7UaXb3bvKKK4punFDT2LiVqKpzvEFqgPpyLysA8Z5yS4g8t4LYmsI9txLE02l5MtWP5R2RBavLhYHjNFHcwEmvYB94bOJw45YmgiGePaW4NHKcfY
SSO_AUTHORITY=https://auth.jnss.me/application/o/vaultwarden/
SSO_SCOPES="openid email profile offline_access"
# ... etc (all correct)
```
**Conclusion:** Environment configured correctly, feature simply not available in stable release.
## Decision: Wait for Stable Release
### Rationale
**Why NOT switch to testing image:**
1. **Production stability** - This is a password manager handling sensitive credentials
2. **Testing images are volatile** - Frequent updates, potential bugs
3. **No ETA for stable** - SSO marked as "testing feature" indefinitely
4. **Current auth works fine** - Email/password login is secure and functional
5. **Configuration is ready** - When SSO reaches stable, it will work immediately
**Why keep SSO configured:**
1. **Future-ready** - No additional work needed when SSO stabilizes
2. **No harm** - Environment variables are ignored by stable image
3. **Documentation** - Clear record of SSO setup for future reference
4. **Authentik provider ready** - Already created and configured
### Alternatives Considered
| Option | Pros | Cons | Decision |
|--------|------|------|----------|
| Use `testing` image | SSO available now | Unstable, potential data loss, frequent breaking changes | ❌ Rejected |
| Wait for stable | Stable, reliable, secure | No SSO until unknown future date | ✅ **Selected** |
| Remove SSO config | Cleaner config | Requires reconfiguration later | ❌ Rejected |
| Dual deployment | Test SSO separately | Resource waste, complexity | ❌ Rejected |
## Current Configuration
### Ansible Role Variables
Location: `roles/vaultwarden/defaults/main.yml`
```yaml
# Container version (stable, no SSO)
vaultwarden_version: "latest"
# SSO enabled (ready for when feature reaches stable)
vaultwarden_sso_enabled: true
vaultwarden_sso_only: false
vaultwarden_sso_client_id: "{{ vault_vaultwarden_sso_client_id }}"
vaultwarden_sso_client_secret: "{{ vault_vaultwarden_sso_client_secret }}"
vaultwarden_sso_authority: "https://auth.jnss.me/application/o/vaultwarden/"
vaultwarden_sso_scopes: "openid email profile offline_access"
vaultwarden_sso_signups_match_email: true
vaultwarden_sso_allow_unknown_email_verification: false
vaultwarden_sso_client_cache_expiration: 0
```
### Vault Variables (Encrypted)
Location: `group_vars/homelab/vault.yml`
```yaml
# SSO credentials from Authentik
vault_vaultwarden_sso_client_id: "DDOQXdwFn6pi4FtSvo7PK5b63pRzyD552xapTZGr"
vault_vaultwarden_sso_client_secret: "02D308Sle2w2NPsi7UaXb3bvKKK4punFDT2LiVqKpzvEFqgPpyLysA8Z5yS4g8t4LYmsI9txLE02l5MtWP5R2RBavLhYHjNFHcwEmvYB94bOJw45YmgiGePaW4NHKcfY"
```
### Authentik Provider Configuration
**Provider Details:**
- **Name:** Vaultwarden
- **Type:** OAuth2/OpenID Connect Provider
- **Client Type:** Confidential
- **Client ID:** `DDOQXdwFn6pi4FtSvo7PK5b63pRzyD552xapTZGr`
- **Application Slug:** `vaultwarden`
- **Redirect URI:** `https://vault.jnss.me/identity/connect/oidc-signin`
**Scopes Configured:**
- ✅ `authentik default OAuth Mapping: OpenID 'openid'`
- ✅ `authentik default OAuth Mapping: OpenID 'email'`
- ✅ `authentik default OAuth Mapping: OpenID 'profile'`
- ✅ `authentik default OAuth Mapping: OpenID 'offline_access'`
**Token Settings:**
- Access token validity: > 5 minutes
- Refresh token enabled via `offline_access` scope
**Authority URL:** `https://auth.jnss.me/application/o/vaultwarden/`
### Deployed Environment (VPS)
```bash
# Deployed environment file
Location: /opt/vaultwarden/.env
# All SSO variables present and correct
SSO_ENABLED=true
SSO_AUTHORITY=https://auth.jnss.me/application/o/vaultwarden/
SSO_SCOPES="openid email profile offline_access"
# ... etc
```
## How to Activate SSO (Future)
When Vaultwarden SSO reaches stable release:
### Automatic Activation (Recommended)
1. **Monitor Vaultwarden releases** for SSO in stable:
- Watch: https://github.com/dani-garcia/vaultwarden/releases
- Look for: SSO feature in stable image changelog
2. **Update container** (standard maintenance):
```bash
ansible-playbook rick-infra.yml --tags vaultwarden --ask-vault-pass
```
3. **Verify SSO is available**:
```bash
ssh root@69.62.119.31 "curl -s http://127.0.0.1:8080/api/config | grep sso"
# Should return: "sso":"https://vault.jnss.me" or similar
```
4. **Test SSO**:
- Navigate to: https://vault.jnss.me
- Log out if logged in
- Enter verified email address
- Click "Use single sign-on" button
- Should redirect to Authentik login
**No configuration changes needed** - Everything is already set up correctly.
### Manual Testing (Use Testing Image)
If you want to test SSO before stable release:
1. **Backup current deployment**:
```bash
ansible-playbook playbooks/backup-vaultwarden.yml # Create if needed
```
2. **Change to testing image** in `roles/vaultwarden/defaults/main.yml`:
```yaml
vaultwarden_version: "testing"
```
3. **Deploy**:
```bash
ansible-playbook rick-infra.yml --tags vaultwarden --ask-vault-pass
```
4. **Test SSO** (same as above)
5. **Revert to stable** when testing complete:
```yaml
vaultwarden_version: "latest"
```
**Warning:** Testing images may contain bugs, data corruption risks, or breaking changes. Not recommended for production password manager.
## Verification Commands
### Check Current Image Version
```bash
ssh root@69.62.119.31 "podman inspect vaultwarden --format '{{.ImageName}}'"
# Expected: docker.io/vaultwarden/server:latest
```
### Check SSO API Status
```bash
ssh root@69.62.119.31 "curl -s http://127.0.0.1:8080/api/config | grep -o '\"sso\":\"[^\"]*\"'"
# Current: "sso":"" (empty = not available)
# Future: "sso":"https://vault.jnss.me" (URL = available)
```
### Check SSO Environment Variables
```bash
ssh root@69.62.119.31 "podman exec vaultwarden env | grep -i sso | sort"
# Should show all SSO_* variables configured correctly
```
### Check Vaultwarden Version
```bash
ssh root@69.62.119.31 "podman exec vaultwarden /vaultwarden --version"
# Current: Vaultwarden 1.34.3
```
## Documentation Updates
The following files have been updated to document this finding:
1. **`roles/vaultwarden/README.md`**
- Added warning banner in SSO configuration section
- Updated troubleshooting section with SSO status checks
- Documented stable vs testing image behavior
2. **`roles/vaultwarden/VAULT_VARIABLES.md`**
- Added SSO feature status warning
- Documented that credentials are ready but inactive
3. **`roles/vaultwarden/defaults/main.yml`**
- Added comments explaining SSO availability
4. **`docs/vaultwarden-sso-status.md`** (this document)
- Complete investigation findings
- Configuration reference
- Activation procedures
## Timeline
- **2025-07-30:** Vaultwarden v1.34.3 released (current stable)
- **2025-12-21:** Vaultwarden deployed with SSO pre-configured
- **2025-12-21:** Investigation completed, SSO status documented
- **TBD:** SSO feature reaches stable release (no ETA)
- **Future:** Automatic SSO activation on next deployment
## Related Documentation
- [Vaultwarden Official Wiki](https://github.com/dani-garcia/vaultwarden/wiki)
- [SSO Documentation](https://github.com/dani-garcia/vaultwarden/wiki/Enabling-SSO-support-using-OpenId-Connect)
- [Authentik Integration Guide](https://integrations.goauthentik.io/security/vaultwarden/)
- [Vaultwarden Testing Features](https://github.com/dani-garcia/vaultwarden/wiki#testing-features)
## Contact
For questions about this deployment:
- Infrastructure repo: `/home/fitz/rick-infra`
- Role location: `roles/vaultwarden/`
- Service: `vault.jnss.me`
- Host: `arch-vps` (69.62.119.31)
---
**Status:** SSO configured and ready, waiting for upstream stable release. No action required.