Internet → Caddy (HTTPS) → Vaultwarden Container → PostgreSQL (Unix socket)
                                                  ↓
                                            /data volume

Components

Container Image: vaultwarden/server:latest (Docker Hub)
User: System user vaultwarden (non-root)
Port: 8080 (localhost only)
Domain: vault.jnss.me
Database: PostgreSQL via Unix socket at /var/run/postgresql
Data: /opt/vaultwarden/data

Dependencies

Managed Hosts:

postgresql role (provides database and Unix socket)
caddy role (provides reverse proxy)

Control Node:

argon2 command-line tool (automatically installed if not present)
- Used to hash the admin token securely on the control node
- Available in most package managers: pacman -S argon2, apt install argon2, etc.

Configuration

Required Variables

Must be defined in vault (e.g., group_vars/homelab/vault.yml):

# Database password
vault_vaultwarden_db_password: "secure-database-password"

# Admin token (plain text - will be hashed automatically during deployment)
vault_vaultwarden_admin_token: "your-secure-admin-token"

# SMTP password (if using email)
vault_vaultwarden_smtp_password: "smtp-password"  # optional

# SSO credentials (if using Authentik integration)
vault_vaultwarden_sso_client_id: "vaultwarden"  # optional
vault_vaultwarden_sso_client_secret: "sso-secret"  # optional

Optional Variables

Override in group_vars or host_vars:

# Domain
vaultwarden_domain: "vault.jnss.me"

# Container version
vaultwarden_version: "latest"

# Registration controls
vaultwarden_signups_allowed: false  # Disable open registration
vaultwarden_invitations_allowed: true  # Allow existing users to invite

# SMTP Configuration
vaultwarden_smtp_enabled: true
vaultwarden_smtp_host: "smtp.example.com"
vaultwarden_smtp_port: 587
vaultwarden_smtp_from: "vault@jnss.me"
vaultwarden_smtp_username: "smtp-user"

# SSO Configuration (Authentik)
vaultwarden_sso_enabled: true
vaultwarden_sso_authority: "https://auth.jnss.me"

Usage

Deploy Vaultwarden

# Full deployment
ansible-playbook rick-infra.yml --tags vaultwarden

# Or via site.yml
ansible-playbook site.yml --tags vaultwarden -l homelab

Access Admin Panel

Set admin token in vault file (plain text):

# Generate a secure token
vault_vaultwarden_admin_token: "$(openssl rand -base64 32)"

The role automatically hashes the token during deployment:
- Hashing occurs on the control node using argon2 CLI
- Uses OWASP recommended settings (19MiB memory, 2 iterations, 1 thread)
- Idempotent: same token always produces the same hash
- The argon2 package is automatically installed if not present
Access: https://vault.jnss.me/admin (use the plain text token from step 1)

Configure SSO (Authentik Integration)

⚠️ IMPORTANT: SSO Feature Status (as of December 2025)

SSO is currently only available in vaultwarden/server:testing images. The stable release (v1.34.3) does NOT include SSO functionality.

Current Deployment Status:

This role is configured with SSO settings ready for when SSO reaches stable release

Using vaultwarden_version: "latest" (stable) - SSO will not appear

To test SSO now: Set vaultwarden_version: "testing" (not recommended for production)

To wait for stable: Keep current configuration, SSO will activate automatically when available

References:

Vaultwarden Wiki - SSO Documentation

Vaultwarden Testing Features

Decision: This deployment keeps SSO configured but uses stable image until SSO feature is production-ready.

Following the Authentik integration guide:

In Authentik: Create OAuth2/OpenID Provider
- Name: Vaultwarden
- Client Type: Confidential
- Redirect URIs: https://vault.jnss.me/identity/connect/oidc-signin (must be strict/exact match)
- Scopes: Under "Advanced protocol settings", ensure these scope mappings are selected:
  - 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' ⚠️ Required
- Access token validity: Set to more than 5 minutes
- Note the Client ID, Client Secret, and application slug (from URL or provider settings)

Update Vault Variables:

vault_vaultwarden_sso_client_id: "<client-id-from-authentik>"
vault_vaultwarden_sso_client_secret: "<client-secret-from-authentik>"

Enable SSO and set authority in group_vars/homelab/main.yml:

vaultwarden_sso_enabled: true
# Replace 'vaultwarden' with your actual application slug
vaultwarden_sso_authority: "https://auth.jnss.me/application/o/vaultwarden/"

Optional: SSO-Only Mode (disable password login):

vaultwarden_sso_only: true  # Requires SSO, disables email+password

Redeploy:

ansible-playbook rick-infra.yml --tags vaultwarden

Test: Log out, enter a verified email on login page, click "Use single sign-on"
- Note: With vaultwarden_version: "latest", SSO button will not appear (feature not in stable yet)

Security Considerations

Database Access

Uses PostgreSQL Unix socket with 777 permissions
Security maintained via password authentication (scram-sha-256)
See: docs/socket-permissions-architecture.md

Admin Token

Never commit plain admin token to git
Use Ansible Vault for vault_vaultwarden_admin_token
Rotate periodically via admin panel

User Registration

Default: Disabled (vaultwarden_signups_allowed: false)
Users must be invited by existing users or created via admin panel
Prevents unauthorized account creation

Maintenance

Backup

Backup the following:

# Database backup (via PostgreSQL role)
sudo -u postgres pg_dump vaultwarden > vaultwarden-backup.sql

# Data directory (attachments, icons, etc.)
tar -czf vaultwarden-data-backup.tar.gz /opt/vaultwarden/data

Update Container

# Pull new image and restart
ansible-playbook rick-infra.yml --tags vaultwarden

View Logs

# Service logs
journalctl -u vaultwarden -f

# Container logs
podman logs vaultwarden -f

Restart Service

systemctl restart vaultwarden

Troubleshooting

Container won't start

# Check container status
systemctl status vaultwarden

# Check container directly
podman ps -a
podman logs vaultwarden

# Verify database connectivity
sudo -u vaultwarden psql -h /var/run/postgresql -U vaultwarden -d vaultwarden -c "SELECT 1;"

Database connection errors

Verify PostgreSQL is running: systemctl status postgresql
Check socket exists: ls -la /var/run/postgresql/.s.PGSQL.5432
Verify socket permissions: Should be srwxrwxrwx (777)
Test connection as vaultwarden user (see above)

Can't access admin panel

Verify admin token is set in vault file (plain text)
Check that the token was hashed successfully during deployment
Ensure you're using the plain text token to log in
Redeploy to regenerate hash if needed

SSO not appearing / not working

Most Common Issue: Using Stable Image

SSO is only available in testing images. Check your deployment:

# Check current image version
podman inspect vaultwarden --format '{{.ImageName}}'

# Check API config for SSO support
curl -s http://127.0.0.1:8080/api/config | grep -o '"sso":"[^"]*"'
# Empty string "" = SSO not available in this image
# URL present = SSO is available

If using vaultwarden_version: "latest": SSO will not appear (feature not in stable yet)

To test SSO: Set vaultwarden_version: "testing" in role defaults or group/host vars
For production: Wait for SSO to reach stable release (recommended)

If using vaultwarden_version: "testing" and SSO still not working:

Verify Authentik provider configuration:
- Check that offline_access scope mapping is added
- Verify redirect URI matches exactly: https://vault.jnss.me/identity/connect/oidc-signin
- Ensure access token validity is > 5 minutes
Verify SSO authority URL includes full path with slug:
- Should be: https://auth.jnss.me/application/o/<your-slug>/
- Not just: https://auth.jnss.me
Check client ID and secret in vault match Authentik
Verify all required scopes: openid email profile offline_access

Check Vaultwarden logs for SSO-related errors:

podman logs vaultwarden 2>&1 | grep -i sso

Test SSO flow: Log out, enter verified email, click "Use single sign-on"

File Structure

roles/vaultwarden/
├── defaults/
│   └── main.yml              # Default variables
├── handlers/
│   └── main.yml              # Service restart handlers
├── meta/
│   └── main.yml              # Role dependencies
├── tasks/
│   ├── main.yml              # Main orchestration
│   ├── user.yml              # User and directory setup
│   └── database.yml          # PostgreSQL setup
├── templates/
│   ├── vaultwarden.container # Quadlet container definition
│   ├── vaultwarden.env.j2    # Environment configuration
│   └── vaultwarden.caddy.j2  # Caddy reverse proxy config
└── README.md                 # This file

References

License

MIT