Docs

Set the password policy

Choose how long a new password must be and whether a user may reuse an earlier one, then deploy the rules.

The password policy holds the rules a new password must meet. Zitadel checks it whenever a password is set: at sign-up and through the API. Passwords already stored are never checked again. It is a policy, a file in .zitadel/policies/ that you deploy with the rest of your configuration.

Before you start

  • A project from zitadel setup (Quickstart). Setup writes the password policy to .zitadel/policies/auth.factor.password.set.json, with the minimum length you chose during setup: 15 characters by default, another minimum, or none. With the default:
{
  "$schema": "../meta/policy.json",
  "operation": "auth.factor.password.set",
  "config": { "min_length": 15 }
}

Choose the settings

Every setting is optional. A setting you leave out is off, and Zitadel adds no default: what the file sets is what applies.

SettingWhat it doesBounds
min_lengthThe fewest characters a new password may have, counted as Unicode code points after NFC normalization.1 to 64
max_lengthThe most characters a new password may have. A password above 64 characters is refused either way.min_length to 64
history_depthHow many of the user's passwords, the current one included, a new one may not repeat. Checked only when users set their own password, which they cannot do yet.1 to 4

The bounds are technical limits, not recommendations. NIST SP 800-63B asks for at least 15 characters when the password is the only factor, and at least 8 when it is always used with a second one.

For example, to allow passwords of 8 to 64 characters for an app where every user also signs in with a second factor:

{
  "$schema": "../meta/policy.json",
  "operation": "auth.factor.password.set",
  "config": { "min_length": 8, "max_length": 64 }
}

Your editor validates the file against .zitadel/meta/policy.json.

Users cannot change their own password yet

history_depth applies only when users set their own password. No sign-up or API call does that yet, so no password is checked against it today. You can set and deploy it now, and test it with "facts": { "history_matches": [false, true] }. It takes effect once users can change their own password.

Deploy the policy

Check the change, then deploy it:

npx @zitadel/cli@latest deploy --dry-run
npx @zitadel/cli@latest deploy

deploy refuses an unknown setting, a value outside its bounds, or a file not named after its operation, before anything is sent. From then on, a password set on your app's origins or through the API is checked against the new rules. On a pull request, preview applies them on its preview URLs only (Deploy).

Check that it works

Write a case one character below your minimum and one exactly at it, and run them against the policy:

npx @zitadel/cli@latest policy test

Test a policy shows the test file, the output, and how to test a release before you deploy it.

Switch the policy off

Delete the file, or set "config": {}, and deploy. Either switches every rule off for sign-ups and the API alike. Deploying the file again brings the rules back.

Was this helpful?