rick-infra/docs/vaultwarden-sso-status.md

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:

Testing features

Features available in the testing docker image:

• Single Sign-On (SSO), see Documentation

From SSO Documentation Page:

⚠️ 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

# 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

# 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

# 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)

# 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):

   ansible-playbook rick-infra.yml --tags vaultwarden --ask-vault-pass
   

3. Verify SSO is available:

   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:

   ansible-playbook playbooks/backup-vaultwarden.yml  # Create if needed
   

2. Change to testing image in roles/vaultwarden/defaults/main.yml:

   vaultwarden_version: "testing"
   

3. Deploy:

   ansible-playbook rick-infra.yml --tags vaultwarden --ask-vault-pass
   

4. Test SSO (same as above)

5. Revert to stable when testing complete:

   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

ssh root@69.62.119.31 "podman inspect vaultwarden --format '{{.ImageName}}'"
# Expected: docker.io/vaultwarden/server:latest

Check SSO API Status

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

ssh root@69.62.119.31 "podman exec vaultwarden env | grep -i sso | sort"
# Should show all SSO_* variables configured correctly

Check Vaultwarden Version

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
• SSO Documentation
• Authentik Integration Guide
• Vaultwarden 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.