password policy

SUMMARY.adoc

@@ -28,6 +28,8 @@
  . link:topics/login-settings.adoc[Login Page Settings]
  .. link:topics/login-settings/forgot-password.adoc[Forgot Password]
  .. link:topics/login-settings/remember-me.adoc[Remember Me]
+ . link:topics/authentication.adoc[Authentication]
+ .. link:topics/authentication/password-policies.adoc[Password Policies]
  . link:topics/admin-permissions.adoc[Master Admin Access Control]
  . link:topics/per-realm-admin-permissions.adoc[Per Realm Admin Access Control]
  . link:topics/client-registration.adoc[Client Registration]

topics/authentication.adoc

@@ -0,0 +1,7 @@
+
+== Authentication
+
+There's a few features you should be aware of when configuring authentication for your realm.  Many organizations
+have strict password an OTP policies that you can enforce via settings in the Admin Console.  You may or may not
+want to require different credential types for authentication.  You may want to give users the option to login via
+Kerberos or disable or enable various built in credential types.  This chapter covers all of these topics.

topics/authentication/password-policies.adoc

@@ -0,0 +1,62 @@
+
+=== 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 stupid 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 pull 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:
+
+HashAlgorithm::
+  Passwords are not stored 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.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.
+HashIterations::
+  This value specifies the number of times a password will be hashed before it is stored or verified.  The default value is 1.
+  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::
+  How many lower case letters are required to be in the password string?
+UpperCase::
+  How many upper case letters are required to be in the password string?
+SpecialChars::
+  How many special characters like '?!#%$' are required to be in the password string?
+NotUsername::
+  When set, password is not allowed to be the same as the username.
+RegexPattern::
+  Define a Perl regular expression pattern that passwords must match.
+ForceExpiredPasswordChange::
+  How many days is a password valid for?  After the number of days has expired, the user will be required to change their password.
+PasswordHistory::
+  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.
+
+