How to Configure Password Iterations and Master Password Security Settings in Vaultwarden

Vaultwarden reads all password security settings from environment variables parsed at startup by src/config.rs, specifically using PASSWORD_ITERATIONS for PBKDF2 cost and SSO_MASTER_PASSWORD_POLICY for SSO password complexity rules.

Vaultwarden is the popular open-source Bitwarden-compatible server implementation written in Rust. To harden your self-hosted password manager, you must configure the Key Derivation Function (KDF) iterations and master password policies through environment variables that the server validates and applies at runtime.

Understanding the Core Configuration Options

Vaultwarden exposes two primary environment variables that control authentication security. These values are read once during server initialization and stored in the global CONFIG object defined in src/config.rs.

PASSWORD_ITERATIONS (PBKDF2 Cost)

The PASSWORD_ITERATIONS variable sets the number of PBKDF2 iterations used to derive the master encryption key from a user's password. According to the source code in src/config.rs at lines 942‑943, the server enforces a minimum of 100,000 iterations and defaults to 600,000.

Higher iteration counts exponentially increase the computational cost for brute-force attacks while adding marginal latency to legitimate login requests. When a client authenticates, the stored iteration count is compared against the current configuration, and the user record is automatically upgraded if necessary (see src/api/core/accounts.rs, lines 1255‑1256).

SSO_MASTER_PASSWORD_POLICY (JSON Policy)

For organizations using Single Sign-On (SSO), the SSO_MASTER_PASSWORD_POLICY variable accepts a JSON object that defines complexity requirements. The validate_sso_master_password_policy function in src/config.rs (starting at line 1286) parses and validates this input, returning a clear error if the JSON is malformed.

The default policy is:

{
  "enforceOnLogin": false,
  "minComplexity": 3,
  "minLength": 12,
  "requireLower": false,
  "requireNumbers": false,
  "requireSpecial": false,
  "requireUpper": false
}

This policy is exposed through the master_password_policy API endpoint defined in src/api/mod.rs (lines 90‑102) and applied during SSO login flows.

Configuration Methods

You can inject these settings via Docker Compose, raw Docker commands, or environment files. The server fails fast at startup if validation fails, preventing misconfigured instances from serving traffic.

Docker Compose Configuration

Add the variables to your docker-compose.yml environment section:

services:
  vaultwarden:
    image: vaultwarden/server:latest
    environment:
      # Increase PBKDF2 iterations to 1,000,000 (above default 600,000)

      - PASSWORD_ITERATIONS=1000000
      # Enforce strict master password requirements for SSO users

      - SSO_MASTER_PASSWORD_POLICY={"enforceOnLogin":true,"minComplexity":4,"minLength":16,"requireLower":true,"requireNumbers":true,"requireSpecial":true,"requireUpper":true}
    ports:
      - "8080:80"

Environment File Setup

For local testing or systemd deployments, create a .env file in the project root (reference /.env.template for documentation):

# Must be ≥ 100,000 per src/config.rs validation

PASSWORD_ITERATIONS=800000

# JSON string quoted to survive shell parsing

SSO_MASTER_PASSWORD_POLICY='{"enforceOnLogin":true,"minComplexity":4,"minLength":16,"requireLower":true,"requireNumbers":true,"requireSpecial":true,"requireUpper":true}'

Launch with:

docker run --env-file .env -p 8080:80 vaultwarden/server:latest

Validation and Enforcement in Source Code

Vaultwarden strictly validates these settings before the server starts. In src/config.rs, the initialization logic explicitly checks the iteration count:

// Simplified excerpt from src/config.rs lines 942-943
if cfg.password_iterations < 100_000 {
    err!("PASSWORD_ITERATIONS should be at least 100000 or higher. The default is 600000!");
}

If you provide PASSWORD_ITERATIONS=50000, the process exits immediately with the above error message.

The User model in src/db/models/user.rs (lines 41‑195) stores the iteration count per user and applies it when hashing passwords. The system automatically migrates existing users to higher iteration counts upon their next login, ensuring security improvements apply retroactively without manual database edits.

Verifying Your Configuration

After startup, confirm the active master password policy via the API:

curl http://localhost:8080/api/master_password_policy

A configured instance returns the JSON policy object:

{
  "enforceOnLogin": true,
  "minComplexity": 4,
  "minLength": 16,
  "requireLower": true,
  "requireNumbers": true,
  "requireSpecial": true,
  "requireUpper": true
}

Summary

• PASSWORD_ITERATIONS controls PBKDF2 cost, defaulting to 600,000 with a hard minimum of 100,000 enforced in src/config.rs.
• SSO_MASTER_PASSWORD_POLICY accepts a JSON object validated by validate_sso_master_password_policy to enforce complexity rules during SSO flows.
• Configuration occurs exclusively through environment variables parsed at server startup.
• User records in src/db/models/user.rs store individual iteration counts and upgrade automatically when the global setting increases.
• The master_password_policy endpoint in src/api/mod.rs exposes current policy settings for client verification.

Frequently Asked Questions

What happens if I set PASSWORD_ITERATIONS below 100,000?

Vaultwarden will fail to start. The validation logic in src/config.rs at lines 942‑943 explicitly checks this minimum and logs an error: "PASSWORD_ITERATIONS should be at least 100000 or higher. The default is 600000!" The process exits immediately to prevent insecure configurations.

Do existing users get upgraded automatically when I increase iterations?

Yes. When a user logs in, the server compares their stored iteration count against the current PASSWORD_ITERATIONS value. If the configured value is higher, Vaultwarden upgrades the user's key derivation parameters automatically (handled in src/api/core/accounts.rs at lines 1255‑1256).

Does the SSO master password policy affect regular non-SSO logins?

No. The SSO_MASTER_PASSWORD_POLICY only applies to authentication flows initiated through configured SSO providers. Local master password requirements remain governed by the standard Bitwarden client policies and the PASSWORD_ITERATIONS setting.

Where can I find the complete list of environment variables?

Reference the /.env.template file in the repository root. This file documents all configurable variables, including default values and JSON schema examples for complex settings like SSO_MASTER_PASSWORD_POLICY.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}