[[_password-policies]]

=== Password Policies

Each new realm created has no password policies associated with it.  This means users can have as short, as long, as complex,
as insecure a password as they want.  This is great for development or if you are just learning and playing around with {{book.project.name}},
but pretty much unacceptable in production environment.  {{book.project.name}} has a rich set of password policies you can enable
through the Admin Console.

Click on the `Authentication` left menu item and go to the `Password Policy` tab.  Choose the policy you want to add in the
right side drop down list box.  This will add the policy in the table on the screen.  Choose the parameters for the policy.
Hit the `Save` button to store your changes.

.Password Policy
image:../../{{book.images}}/password-policy.png[]

After saving your policy, user registration and the Update Password required action will enforce your new policy.  Here's
what it would look like if the user failed the policy check:

.Failed Password Policy
image:../../{{book.images}}/failed-password-policy.png[]


Unfortunately,
users are not required to update their password if the password policy changes and there is no nice way of triggering an
Update Password required action other than setting it manually for every user.  This is scheduled as a future enhancement.

==== Password Policy Types

Here's an explanation of each policy type:

{% if book.community %}
HashAlgorithm::
  Passwords are not stored as clear text.  Instead they are hashed using standard hashing algorithms before they are stored or validated.
  The only built-in and default algorithm available is PBKDF2.  See the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.developerguide.link}}[{{book.developerguide.name}}]
  on how to plug in your own algorithm.  Note that if you do change the algorithm, password hashes will not change in storage until
  the next time the user logs in.
{% endif %}
{% if book.product %}
Hashing Algorithm::
  Passwords are not stored as clear text.  Instead they are hashed using standard hashing algorithms before they are stored or validated.
  The only currently supported algorithm is PBKDF2.
{% endif %}
Hashing Iterations::
  This value specifies the number of times a password will be hashed before it is stored or verified.  The default value is 20,000.
  This hashing is done in the rare case that a hacker gets access to your password database.  Once they have the database
  they can reverse engineer user passwords.
  The industry recommended value for this parameter changes every year as CPU power improves.  The current recommended value
  is 20,000.  Yes, 20,000 iterations! This is a very intensive CPU operation and with this high of a setting your servers
  are going to be spending most of their CPU power on hashing.  You'll have to weigh what is more important to you.  Performance
  or protecting your passwords stores.  There may be more cost effective ways of protecting your password stores.
Digits::
  How many digits are required to be in the password string?
Lowercase Characters::
  How many lower case letters are required to be in the password string?
Uppercase Characters::
  How many upper case letters are required to be in the password string?
Special Characters::
  How many special characters like '?!#%$' are required to be in the password string?
Not Username::
  When set, password is not allowed to be the same as the username.
Regular Expression::
  Define a Perl regular expression pattern that passwords must match.
Expire Password::
  How many days is a password valid for?  After the number of days has expired, the user will be required to change their password.
Not Recently Used::
  This policy saves a history of previous passwords.  The number of old passwords stored is configurable.  When a user changes their password
  they will not be able to re-use any password stored in history.