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

> Learn how to configure password iterations for PBKDF2 cost and master password security settings in Vaultwarden using environment variables. Secure your password manager effectively.

- Repository: [Daniel García/vaultwarden](https://github.com/dani-garcia/vaultwarden)
- Tags: how-to-guide
- Published: 2026-03-07

---

**Vaultwarden reads all password security settings from environment variables parsed at startup by [`src/config.rs`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/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:

```json
{
  "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`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/docker-compose.yml) environment section:

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

```env

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

```bash
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`](https://github.com/dani-garcia/vaultwarden/blob/main/src/config.rs), the initialization logic explicitly checks the iteration count:

```rust
// 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`](https://github.com/dani-garcia/vaultwarden/blob/main/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:

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

```

A configured instance returns the JSON policy object:

```json
{
  "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`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/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`.