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

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

**Generation**:
```bash
openssl rand -base64 32
```

### Admin Panel Access

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

**Generation**:
```bash
# 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`:

```yaml
# 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`:

```yaml
# 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](https://integrations.goauthentik.io/security/vaultwarden/)):
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:
   ```yaml
   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

```yaml
---
# 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

```bash
ansible-vault encrypt group_vars/homelab/vault.yml
```

### Edit Vault File

```bash
ansible-vault edit group_vars/homelab/vault.yml
```

### Decrypt Vault File (temporary)

```bash
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:

```bash
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