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.
| Setting | What it does | Bounds |
|---|---|---|
min_length | The fewest characters a new password may have, counted as Unicode code points after NFC normalization. | 1 to 64 |
max_length | The most characters a new password may have. A password above 64 characters is refused either way. | min_length to 64 |
history_depth | How 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 deploydeploy 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 testTest 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?