<?xml version="1.0" encoding="UTF-8"?>

<chapter xml:id='chap-pwd-reset'

xmlns='http://docbook.org/ns/docbook'

version='5.0' xml:lang='en'

xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

xsi:schemaLocation='http://docbook.org/ns/docbook

xmlns:xlink='http://www.w3.org/1999/xlink'>

<title>Configuring User Self-Service Features</title>

<indexterm><primary>Password reset</primary></indexterm>

<para>This chapter focuses on how to enable OpenAM features that allow users

to self register from the Login page and reset their own

passwords in secure fashion.

</para>

<section xml:id="user-self-registration">

<title>Configuring User Self-Registration</title>

<para>

OpenAM provides a self-registration feature that allows users to add

themselves to the system.

On the Login page, the user clicks a Register link, which sends a request to

the OpenAM server. OpenAM responds to request by sending a

Register Your Account page where the user enters his or her email address.

</para>

<para>

After the user enters his or her email, OpenAM responds by sending a

notification containing a confirmation link to the user's email address.

When the user clicks the link, OpenAM confirms the operation and presents the user

with a registration page where the user enters their account information.

</para>

<procedure xml:id="configure-user-self-registration">

<title>To Configure User Self-Registration</title>

<step>

<para>Configure the Email Service to send mail

notifications to users who self-register.

</para>

<para>

You can configure these globally

in OpenAM console at Configuration &gt; Global &gt; Email Service.

Alternatively, you can configure them for an individual realm under

Access Control > <replaceable>Realm Name</replaceable> > Services.</para>

</step>

<step>

<para>Configure User Self Service to enable self-registration.

</para>

<para>

You can configure these globally in OpenAM console at

Configure &gt; Global &gt; User Self Service. On the User Self Service page, click

the <literal>Enabled</literal> checkbox next to Self-Registration for Users,

and then click Save.

</para>

</step>

</procedure>

<para>

At this point users can self-register by clicking a Register link on the

Login page.

</para>

<mediaobject xml:id="figure-user-self-register-login">

<alt>User Self-Registration link</alt>

<imageobject>

<imagedata fileref="images/user-self-register-login.png" format="PNG" />

</imageobject>

<textobject><para>OpenAM allows users to register themselves by clicking

the Register link.

</para>

</textobject>

</mediaobject>

</section>

<section xml:id="about-pwd-reset">

<title>About Password Reset</title>

<para>Users who know their passwords, but must reset them because for example

the password is going to expire, can reset their passwords by successfully

authenticating to OpenAM, visiting their end user pages, such as

<literal>http://openam.example.com:8080/openam/XUI/#profile/</literal>, and

clicking Change Security Data to display the change password page.</para>

<figure xml:id="figure-console-change-pwd-xui">

<title>OpenAM Security Data Change page</title>

<mediaobject>

<alt>OpenAM Change Password page</alt>

<imageobject>

<imagedata fileref="images/console-change-pwd-xui.png" format="PNG" />

</imageobject>

<textobject><para>Authenticated users can change their passwords

through the OpenAM console.</para></textobject>

</mediaobject>

</figure>

<para>You therefore do not need to configure password reset for users

who can remember their current password. Instead, you point them to the

<literal>XUI/#profile</literal> page to let them do it themselves.</para>

</section>

<section xml:id="forgotten-pwd-reset">

<title>Resetting Forgotten Passwords</title>

<para>OpenAM can provide self-service password reset for forgotten passwords.

To enable self-service password reset, you must configure the password

reset service itself, which consists mainly of setting up secret questions,

and configuring an SMTP mail server to send reset passwords to the users

of the service.</para>

<tip>

<para>Users must be able to access their mail after the service resets

their passwords, or they will not be able to receive the new password.

Therefore, do not set up the service to reset the password used to access

the email account specified in the user's profile.</para>

</tip>

<procedure xml:id="set-up-pwd-reset-service">

<title>To Set Up the Password Reset Service</title>

<para>You can configure the password reset service for OpenAM, letting

each realm inherit the global settings. Alternatively, you can choose to

configure the service only for an individual realm.</para>

<tip>

<para>

Resetting a user password can have repercussions on the user profile.

For example, a user data store directory service

could enforce a policy to require password changes on reset.

OpenAM's LDAP authentication module can deal with policies

based on the Behera Internet-Draft,

<link

xlink:show="new"

xlink:href="http://tools.ietf.org/html/draft-behera-ldap-password-policy-09"

>Password Policy for LDAP Directories</link>,

though its default DataStore authentication module cannot.

</para>

<para>

When the user data store directory service

enforces password reset policies,

then either use the LDAP authentication module

in the authentication chain,

or rely on some other means of resetting user passwords.

</para>

</tip>

<step>

<para>Configure the Password Reset service in one of the following ways.</para>

<stepalternatives>

<step>

<para>To configure the service globally for all realms, login to OpenAM

Console as administrator and browse to Configuration &gt; Global &gt;

Password Reset in the Global Properties list.</para>

</step>

<step>

<para>To configure the service for a particular realm, login to OpenAM

console as the realm administrator and browse to Access Control &gt;

<replaceable>Realm Name</replaceable> &gt; Services, then click Add...

to add a new Password Reset service configuration.</para>

</step>

</stepalternatives>

</step>

<step>

<para>In the Password Reset page, use the following hints to adjust

settings, and then save your work.</para>

<para>In addition to the User Validation and Secret Question values

provided, you must configure at least the Bind DN and Bind Password

of the user who can reset passwords in the LDAP data store.</para>

<variablelist>

<varlistentry>

<term>User Validation</term>

<listitem>

<para>OpenAM uses this LDAP attribute and the value entered by the

user to look up the user profile in the data store.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Secret Question</term>

<listitem>

<para>This list corresponds to property values held in the file

<filename>amPasswordReset.properties</filename> inside

<filename><?eval ${coreLibrary}?></filename>, which you can find

under <filename>WEB-INF/lib/</filename> where OpenAM is installed.</para>

<para>To make changes, extract a version from

<filename><?eval ${coreLibrary}?></filename>, copy it to

<filename>WEB-INF/classes/</filename> where OpenAM is deployed, and

then edit

<filename>WEB-INF/classes/amPasswordReset.properties</filename>.</para>

<para>Localized versions of this file are named

<filename>amPasswordReset_<replaceable>locale</replaceable>.properties</filename>.

You should localize only the questions at the end, leaving the rest of

the localized file as is. For example if the default properties file

contains:</para>

<literallayout class="monospaced">favourite-restaurant=What is your favorite restaurant?</literallayout>

<para>Then <filename>WEB-INF/classes/amPasswordReset_fr.properties</filename>

ought to contain:</para>

<literallayout class="monospaced">favourite-restaurant=Quel est votre restaurant préféré ?</literallayout>

<para>After changing these files, you must restart OpenAM.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Search Filter</term>

<listitem>

<para>An additional LDAP search filter you specify here is &amp;-ed

with the filter constructed for user validation to find the user

entry in the data store.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Base DN</term>

<listitem>

<para>If you specify no base DN for the search, the search for the user

entry starts from the base DN for the realm.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Bind DN</term>

<listitem>

<para>The DN of the user with access to change passwords in the

LDAP data store.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Bind Password</term>

<listitem>

<para>The password of the user with access to change passwords in the

LDAP data store.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Reset Password Creator</term>

<listitem>

<para>Classname of a plugin that implements the

<literal>PasswordGenerator</literal> interface.</para>

<para>Default: <literal>com.sun.identity.password.plugins.RandomPasswordGenerator</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Password Reset Notification Class</term>

<listitem>

<para>Classname of a plugin that implements the

<literal>NotifyPassword</literal> interface.</para>

<para>Default: <literal>com.sun.identity.password.plugins.EmailPassword</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Password Reset</term>

<listitem>

<para>Enables the service.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Personal Question</term>

<listitem>

<para>When enabled, allows the user to create custom secret

questions.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Maximum Number of Questions</term>

<listitem>

<para>Maximum number of questions to ask during password reset.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Force Change Password on Next Login</term>

<listitem>

<para>When enabled, the user must change her password next time she

logs in after OpenAM resets her password.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Password Reset Failure Lockout</term>

<listitem>

<para>When enabled, the user only gets the specified number of tries

before her account is locked.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Password Reset Failure Lockout Count</term>

<listitem>

<para>If Password Reset Failure Lockout is enabled, this specifies the

maximum number of tries to reset a password within the specified

interval before the user's account is locked.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Password Reset Failure Lockout Interval</term>

<listitem>

<para>This interval applies when Password Reset Failure Lockout is

enabled, and when Password Reset Failure Lockout Count is set. During

this interval, a user can try to reset her password the specified

number of times before being locked out. For example, if this interval

is 5 minutes and the count is set to 3, a user gets 3 tries during

a given 5 minute interval to reset her password.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Email Address to Send Lockout Notification</term>

<listitem>

<para>This specifies the administrator address(es) which receive(s)

notification on user account lockout. Each address must be a full

email address such as <literal>admin@example.com</literal>, or

<literal>admin@host.domain</literal>.</para>

<para>OpenAM must be able to send mail through an SMTP-capable service

for this to work. See <xref linkend="set-up-mail-notification" />.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Warn User After N Failures</term>

<listitem>

<para>If you configure Password Reset Failure Lockout, set this to

warn users who are about to use up their count of tries.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Password Reset Failure Lockout Duration</term>

<listitem>

<para>If you configure Password Reset Failure Lockout, set this to a

number of minutes other than <literal>0</literal> so that lockout is

temporary, requiring only that the locked-out user wait to try again

to reset her password, rather than necessarily require help from

an administrator.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Password Reset Lockout Attribute Name</term>

<listitem>

<para>If you configure Password Reset Failure Lockout, then OpenAM sets

sets data store attribute to <literal>inactive</literal> upon

lockout.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Password Reset Lockout Attribute Value</term>

<listitem>

<para>If set to <literal>inactive</literal>, then a user who is locked

out cannot attempt to reset her password if the Password Reset

Failure Lockout Duration is <literal>0</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Password Reset E-mail Attribute Name</term>

<listitem>

<para>Identity attribute that holds the user's email address.</para>

<para>Default: <literal>mail</literal></para>

</listitem>

</varlistentry>

</variablelist>

</step>

<step>

<para>If you changed Secret Questions in the

<filename>WEB-INF/classes/amPasswordReset.properties</filename> file or in

any localized versions, restart OpenAM for the changes to take

effect.</para>

</step>

</procedure>

<procedure xml:id="set-up-mail-notification">

<title>To Set Up SMTP Mail Notification</title>

<para>By default, OpenAM expects the SMTP service to listen on

<literal>localhost:25</literal>. You can change these settings.</para>

<step>

<para>In the OpenAM console, click the Configuration &gt; Servers and

Sites &gt; Default Server Settings.</para>

</step>

<step>

<para>In the Edit server-default page, scroll down to Mail Server to

change the Mail Server Host Name or Mail Server Port Number.</para>

</step>

<step>

<para>Save your work.</para>

</step>

<step>

<para>By default, OpenAM sends password reset notifications from

<literal>&lt;Password-Administrator&gt;</literal>.</para>

<para>To set a valid from address, extract

<filename>amPasswordResetModuleMsgs.properties</filename> from

<filename><?eval ${coreLibrary}?></filename>, copy it to

<filename>WEB-INF/classes/</filename> where OpenAM is deployed, and then

edit the file to change the <literal>fromAddress.label</literal> property

value, as in the following example.</para>

<literallayout class="monospaced">fromAddress.label=no-reply@example.com</literallayout>

<para>Save your work, and then restart OpenAM for the properties file change

to take effect.</para>

</step>

</procedure>

<procedure xml:id="prepare-users-for-pwd-reset">

<title>To Prepare Users to Reset Passwords</title>

<para>Before a user can reset her password, she must choose answers for

secret questions.</para>

<step>

<para>When her account is first created, direct the user to her

<literal>idm/EndUser</literal> page, such as

<literal>http://openam.example.com:8080/openam/idm/EndUser</literal>,

where she can provide a valid email address to recover the reset password

and can edit Password Reset Options.</para>

<mediaobject xml:id="figure-console-end-user">

<alt>The OpenAM end user page</alt>

<imageobject>

<imagedata fileref="images/console-end-user.png" format="PNG" />

</imageobject>

<textobject><para>Authenticated users can change their email and

password reset secret questions through the OpenAM console.</para></textobject>

</mediaobject>

<para>By default OpenAM console redirects end users to this page when

they login.</para>

</step>

<step>

<para>After the user updates her secret questions, she can use the

password reset service when necessary.</para>

<mediaobject xml:id="figure-console-secret-questions">

<alt>The OpenAM secret question page</alt>

<imageobject>

<imagedata fileref="images/console-secret-questions.png" format="PNG" />

</imageobject>

<textobject><para>Authenticated users can change the answers to secret

questions through the OpenAM console.</para></textobject>

</mediaobject>

<note><para>Answers to secret questions are case sensitive.</para></note>

</step>

</procedure>

<procedure xml:id="redirect-to-reset-pwd">

<title>To Direct Users to Reset Passwords</title>

<para>Having setup her email and answers to secret questions, the user

can use the reset password service.</para>

<para>Create a test subject and use these steps to validate your

configuration.</para>

<step>

<para>Send the user with a forgotten password to enter her user ID at

the password reset URL.</para>

<para>If the user is in the default realm use <literal>password</literal>

at the end of the URL to OpenAM, as in

<literal>http://openam.example.com:8080/openam/password</literal>.</para>

<para>If the password reset service is enabled only for the user's realm

and not the parent realm, or the realm to reset the password is different

from the user's default realm, use <literal>ui/PWResetUserValidation?realm=<replaceable>realm

name</replaceable>, as in</literal>

<literal>http://openam.example.com:8080/openam/ui/PWResetUserValidation?realm=<replaceable>realm

name</replaceable></literal>.</para>

<mediaobject xml:id="figure-console-user-validation">

<alt>The OpenAM user validation page</alt>

<imageobject>

<imagedata fileref="images/console-user-validation.png" format="PNG" />

</imageobject>

<textobject><para>OpenAM validates that the user exists, has an active

account, and has set answers to her secret questions.</para></textobject>

</mediaobject>

</step>

<step>

<para>The user answers the specified questions, and clicks OK.</para>

<para>OpenAM resets the password, sending mail to the SMTP service

you configured.</para>

<mediaobject xml:id="figure-console-answer-questions">

<alt>The OpenAM user validation page</alt>

<imageobject>

<imagedata fileref="images/console-answer-questions.png" format="PNG" />

</imageobject>

<textobject><para>OpenAM prompts with secret questions.</para></textobject>

</mediaobject>

<para>When the user clicks OK, OpenAM sends the email and shows a

confirmation message.</para>

<para>The user receives the email with a line such as the following.</para>

<literallayout class="monospaced">Your OpenAM password was changed to: 647bWluw</literallayout>

</step>

<step>

<para>The user logs in using the new password.</para>

<para>If you configured the system to force a change on password reset,

then OpenAM requires the user to change her password.</para>

</step>

</procedure>

</section>

</chapter>