keycloak-scim/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.
ifeval::[{project_community}==true]
. Click the *Policies* tab.
endif::[]
ifeval::[{project_product}==true]
. Click the *Password Policy* tab.
endif::[]
. Select the policy to add in the *Add policy* drop-down box.
ifeval::[{project_community}==true]
. Enter a value that applies to the policy chosen.
endif::[]
ifeval::[{project_product}==true]
. Enter a value for the *Policy Value* corresponding with the policy chosen.
endif::[]
. Click *Save*.
+
Password policy
image:{project_images}/password-policy.png[Password Policy]

After saving the policy, {project_name} 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
image:{project_images}/failed-password-policy.png[Failed Password Policy]

==== Password policy types

ifeval::[{project_community}==true]

===== 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.
====

endif::[]

ifeval::[{project_product}==true]
===== Hashing algorithm

Passwords are not stored in clear text. Before storage or validation, {project_name} hashes passwords using standard hashing algorithms {project_name} that support the PBKDF2, PBKDF2-SHA256 and PBKDF-SHA512 hashing algorithms.

endif::[]

===== Hashing iterations
Specifies the number of times {project_name} hashes passwords before storage or verification. The default value is 27,500.

{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 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. {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.
* 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.