rick-infra/roles/vaultwarden/VAULT_VARIABLES.md

Vaultwarden Role - Required Vault Variables

This document lists all vault-encrypted variables required by the Vaultwarden role.

Required Variables

These variables must be defined in your vault file (e.g., group_vars/homelab/vault.yml):

Database Credentials

# PostgreSQL database password for vaultwarden user
vault_vaultwarden_db_password: "your-secure-database-password-here"

Generation:

openssl rand -base64 32

Admin Panel Access

# Plain text admin token (will be hashed during deployment)
vault_vaultwarden_admin_token: "your-secret-admin-token"

Generation:

# Generate a secure random token
openssl rand -base64 32

Important:

• Store as plain text in vault (the role will hash it automatically)
• Use the same token to access /admin panel
• The token is automatically hashed on the control node using argon2id
• Hashing uses OWASP recommended settings (m=19456, t=2, p=1)
• Hashing is idempotent: same token always produces same hash
• The argon2 package is automatically installed if not present on control node
• Never commit the vault file unencrypted to git

Optional Variables

These variables are only needed if you enable specific features:

SMTP Configuration

Required if vaultwarden_smtp_enabled: true:

# SMTP password for sending emails
vault_vaultwarden_smtp_password: "smtp-password-here"

SSO Integration (Authentik)

⚠️ SSO Feature Status (December 2025)

SSO is only available in vaultwarden/server:testing images (not in stable yet). This role is configured with SSO ready for when it reaches stable release.

Current deployment uses vaultwarden_version: "latest" (stable) - SSO credentials below are configured but SSO will not appear until feature reaches stable.

Required if vaultwarden_sso_enabled: true:

# OAuth2 Client ID from Authentik
vault_vaultwarden_sso_client_id: "your-client-id-here"

# OAuth2 Client Secret from Authentik
vault_vaultwarden_sso_client_secret: "your-client-secret-here"

Setup (following Authentik integration guide):

1. Create OAuth2/OpenID Provider in Authentik:
   • Redirect URI: https://vault.jnss.me/identity/connect/oidc-signin (exact match)
   • Add scope mappings: openid, email, profile, offline_access (required)
   • Access token validity: > 5 minutes
   • Note the application slug from the provider URL
2. Copy Client ID and Secret from Authentik
3. Add credentials to vault file
4. Set the SSO authority URL in role configuration:

   vaultwarden_sso_enabled: true
   vaultwarden_sso_authority: "https://auth.jnss.me/application/o/<your-slug>/"
   

5. Deploy the role
6. Wait for SSO to reach stable, or use vaultwarden_version: "testing" to test now

Important:

• The SSO authority must include the full path with application slug
• The offline_access scope mapping is required for Vaultwarden SSO
• Access token must be valid for more than 5 minutes
• SSO is configured and ready but will activate when stable release includes it

Example Vault File

---
# group_vars/homelab/vault.yml (encrypted with ansible-vault)

# Vaultwarden - Database
vault_vaultwarden_db_password: "xK9mP2nR5tY8wQ3vZ7cB6sA4dF1gH0jL"

# Vaultwarden - Admin Panel (plain text, will be hashed automatically)
vault_vaultwarden_admin_token: "MySecureAdminToken123!"

# Vaultwarden - SMTP (optional)
vault_vaultwarden_smtp_password: "smtp-app-password-here"

# Vaultwarden - SSO (optional)
vault_vaultwarden_sso_client_id: "vaultwarden"
vault_vaultwarden_sso_client_secret: "sso-secret-from-authentik"

Vault File Management

Encrypt Vault File

ansible-vault encrypt group_vars/homelab/vault.yml

Edit Vault File

ansible-vault edit group_vars/homelab/vault.yml

Decrypt Vault File (temporary)

ansible-vault decrypt group_vars/homelab/vault.yml
# Make changes
ansible-vault encrypt group_vars/homelab/vault.yml

Security Best Practices

1. Never commit unencrypted vault files
2. Use strong passwords (32+ characters for database, admin token)
3. Rotate credentials periodically (especially admin token)
4. Limit vault password access (use password manager)
5. Use separate passwords for different services
6. Back up vault password (secure location, not in git)

Verifying Variables

Test if variables are properly loaded:

ansible -m debug -a "var=vault_vaultwarden_db_password" homelab --ask-vault-pass

Troubleshooting

Variable not found error

• Ensure vault file is in correct location: group_vars/homelab/vault.yml
• Verify file is encrypted: file group_vars/homelab/vault.yml
• Check variable name matches exactly (case-sensitive)
• Provide vault password with --ask-vault-pass

Admin token not working

• Verify the plain text token in vault matches what you're entering
• Check for extra whitespace in vault file
• Ensure the token was hashed successfully during deployment (check ansible output)
• Try redeploying the role to regenerate the hash