keycloak-scim/docs/documentation/server_admin/topics/authentication/password-policies.adoc

[[_password-policies]]

=== Password policies

When {project_name} 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. {project_name} has a set of password policies available through the Admin Console.

.Procedure
. Click *Authentication* in the menu.
. Click the *Policies* tab.
. Select the policy to add in the *Add policy* drop-down box.
. Enter a value that applies to the policy chosen.
. Click *Save*.
+
Password policy
image:images/password-policy.png[Password Policy]

After saving the policy, {project_name} enforces the policy for new users.

[NOTE]
====
The new policy will not be effective for existing users. Therefore, make sure that you set the password policy from the beginning of the realm creation or add "Update password" to existing users  or use "Expire password" to make sure that users update their passwords in next "N" days, which will actually adjust to new password policies.
====

==== Password policy types

===== HashAlgorithm

Passwords are not stored in cleartext. Before storage or validation, {project_name} hashes passwords using standard hashing algorithms. PBKDF2 is the only built-in and default algorithm available. See the link:{developerguide_link}[{developerguide_name}] on how to add your own hashing algorithm.

[NOTE]
====
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 {project_name} hashes passwords before storage or verification. The default value is 210,000 in case that `pbkdf2-sha512` is used as hashing algorithm, which is by default.
If other hash algorithms are explicitly set by using the`HashAlgorithm` policy, the default count of hashing iterations could be different. For instance, it is 600,000 by default if  the`pbkdf2-sha256` algorithm is used or 1,300,000 if
the `pbkdf2` algorithm (Algorithm `pbkdf2` corresponds to PBKDF2 with HMAC-SHA1).

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

[NOTE]
====
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 Java regular expression patterns.
See https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/regex/Pattern.html[Java's regular expression documentation] for the syntax of those expressions.

===== 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. {project_name} stores a history of used passwords. The number of old passwords stored is configurable in {project_name}.

===== 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.
* {project_name} 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, for example, `100k_passwords.txt`.
* Blacklist files resolve against `+${kc.home.dir}/data/password-blacklists/+` by default. Customize this path using:
** The `keycloak.password.blacklists.path` system property.
** The `blacklistsPath` property of the `passwordBlacklist` policy SPI configuration. To configure the blacklist folder using the CLI, use `--spi-password-policy-password-blacklist-blacklists-path=/path/to/blacklistsFolder`.

.A note about False Positives

The current implementation uses a BloomFilter for fast and memory efficient containment checks, such as whether a given password is contained in a blacklist, with the possibility for false positives.

* By default a false positive probability of `0.01%` is used.
* To change the false positive probability by CLI configuration, use `--spi-password-policy-password-blacklist-false-positive-probability=0.00001`.

===== Maximum Authentication Age

Specifies the maximum age of a user authentication in seconds with which the user can update a password without re-authentication. A value of `0` indicates that the user has to always re-authenticate with their current password before they can update the password.
See <<con-aia-reauth_{context}, AIA section>> for some additional details about this policy.