Password policies

When Keycloak creates a realm, it does not associate password policies with the realm. You can set a simple password with no restrictions on its length, security, or complexity. Simple passwords are unacceptable in production environments. Keycloak has a set of password policies available through the Admin Console.

Procedure

  1. Click Authentication in the menu.

  2. Click the Policies tab.

  3. Select the policy to add in the Add policy drop-down box.

  4. Enter a value that applies to the policy chosen.

  5. Click Save.

    Password policy Password Policy

After saving the policy, Keycloak enforces the policy for new users and sets an Update Password action for existing users to ensure they change their password the next time they log in. For example:

Failed password policy

Failed Password Policy

Password policy types

HashAlgorithm

Passwords are not stored in cleartext. Before storage or validation, Keycloak hashes passwords using standard hashing algorithms. PBKDF2 is the only built-in and default algorithm available. See the Server Developer Guide on how to add your own hashing algorithm.

If you change the hashing algorithm, password hashes in storage will not change until the user logs in.

Hashing iterations

Specifies the number of times Keycloak hashes passwords before storage or verification. The default value is 27,500.

Keycloak hashes passwords to ensure that hostile actors with access to the password database cannot read passwords through reverse engineering.

A high hashing iteration value can impact performance as it requires higher CPU power.

Digits

The number of numerical digits required in the password string.

Lowercase characters

The number of lower case letters required in the password string.

Uppercase characters

The number of upper case letters required in the password string.

Special characters

The number of special characters required in the password string.

Not username

The password cannot be the same as the username.

Not email

The password cannot be the same as the email address of the user.

Regular expression

Password must match one or more defined regular expression patterns.

Expire password

The number of days the password is valid. When the number of days has expired, the user must change their password.

Not recently used

Password cannot be already used by the user. Keycloak stores a history of used passwords. The number of old passwords stored is configurable in Keycloak.

Password blacklist

Password must not be in a blacklist file.

  • Blacklist files are UTF-8 plain-text files with Unix line endings. Every line represents a blacklisted password.

  • Keycloak compares passwords in a case-insensitive manner. All passwords in the blacklist must be lowercase.

  • The value of the blacklist file must be the name of the blacklist file.

  • Blacklist files resolve against ${jboss.server.data.dir}/password-blacklists/ by default. Customize this path using:

    • The keycloak.password.blacklists.path property.

    • The blacklistsPath property of the passwordBlacklist policy SPI configuration.