Add Vaultwarden password manager role with PostgreSQL and SSO support
- 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:
307
docs/vaultwarden-sso-status.md
Normal file
307
docs/vaultwarden-sso-status.md
Normal 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.
|
||||
Reference in New Issue
Block a user