OpenAM Administration Guide
Chapter 8. Configuring Password Reset

Procedure 8.1. To Set Up the Password Reset Service

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.

1. When OpenAM is configured with default settings, it uses the ldapService authentication chain, which relies on the DataStore authentication module. The DataStore authentication module provides a generic authentication mechanism for OpenAM data stores, and therefore cannot handle specific data store settings, such as the directory server password policy setting to force password changes on reset. When you use settings the module cannot handle, then authentication can fail.

   If you must configure the directory server to force password changes on reset, then also configure a separate authentication chain for users. The separate authentication chain must require the LDAP authentication module rather than the DataStore authentication module.

   You can create and configure authentication chains, and assign them in the OpenAM console under Access Control > Realm Name > Authentication.

   The OpenAM administrator, amadmin, uses the DataStore authentication module. If you set Access Control > /(Top Level Realm) > Authentication > Core > Organization Authentication Configuration to use your LDAP based authentication chain for users, let the Administrator Authentication Configuration continue to use the DataStore based authentication chain.

2. Configure the Password Reset service in one of the following ways.

   • To configure the service globally for all realms, login to OpenAM Console as administrator and browse to Configuration > Global > Password Reset in the Global Properties list.

   • To configure the service for a particular realm, login to OpenAM console as the realm administrator and browse to Access Control > Realm Name > Services, then click Add... to add a new Password Reset service configuration.

3. In the Password Reset page, use the following hints to adjust settings, and then save your work.

   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.

   User Validation

   OpenAM uses this LDAP attribute and the value entered by the user to look up the user profile in the data store.

   Secret Question

   This list corresponds to property values held in the file amPasswordReset.properties inside , which you can find under WEB-INF/lib/ where OpenAM is installed.

   To make changes, extract a version from , copy it to WEB-INF/classes/ where OpenAM is deployed, and then edit WEB-INF/classes/amPasswordReset.properties.

   Localized versions of this file are named amPasswordReset_locale.properties. 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:

   favourite-restaurant=What is your favorite restaurant?

   Then WEB-INF/classes/amPasswordReset_fr.properties ought to contain:

   favourite-restaurant=Quel est votre restaurant préféré ?

   After changing these files, you must restart OpenAM.

   Search Filter

   An additional LDAP search filter you specify here is &-ed with the filter constructed for user validation to find the user entry in the data store.

   Base DN

   If you specify no base DN for the search, the search for the user entry starts from the base DN for the realm.

   Bind DN

   The DN of the user with access to change passwords in the LDAP data store.

   Bind Password

   The password of the user with access to change passwords in the LDAP data store.

   Reset Password Creator

   Classname of a plugin that implements the PasswordGenerator interface.

   Default: com.sun.identity.password.plugins.RandomPasswordGenerator

   Password Reset Notification Class

   Classname of a plugin that implements the NotifyPassword interface.

   Default: com.sun.identity.password.plugins.EmailPassword

   Password Reset

   Enables the service.

   Personal Question

   When enabled, allows the user to create custom secret questions.

   Maximum Number of Questions

   Maximum number of questions to ask during password reset.

   Force Change Password on Next Login

   When enabled, the user must change her password next time she logs in after OpenAM resets her password.

   Password Reset Failure Lockout

   When enabled, the user only gets the specified number of tries before her account is locked.

   Password Reset Failure Lockout Count

   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.

   Password Reset Failure Lockout Interval

   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.

   Email Address to Send Lockout Notification

   This specifies the administrator address(es) which receive(s) notification on user account lockout. Each address must be a full email address such as admin@example.com, or admin@host.domain.

   OpenAM must be able to send mail through an SMTP-capable service for this to work. See Procedure 8.2, “To Set Up SMTP Mail Notification”.

   Warn User After N Failures

   If you configure Password Reset Failure Lockout, set this to warn users who are about to use up their count of tries.

   Password Reset Failure Lockout Duration

   If you configure Password Reset Failure Lockout, set this to a number of minutes other than 0 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.

   Password Reset Lockout Attribute Name

   If you configure Password Reset Failure Lockout, then OpenAM sets sets data store attribute to inactive upon lockout.

   Password Reset Lockout Attribute Value

   If set to inactive, then a user who is locked out cannot attempt to reset her password if the Password Reset Failure Lockout Duration is 0.

   Password Reset E-mail Attribute Name

   Identity attribute that holds the user's email address.

   Default: mail

4. If you changed Secret Questions in the WEB-INF/classes/amPasswordReset.properties file or in any localized versions, restart OpenAM for the changes to take effect.

Procedure 8.2. To Set Up SMTP Mail Notification

By default, OpenAM expects the SMTP service to listen on localhost:25. You can change these settings.

1. In the OpenAM console, click the Configuration > Servers and Sites > Default Server Settings.

2. In the Edit server-default page, scroll down to Mail Server to change the Mail Server Host Name or Mail Server Port Number.

3. Save your work.

4. By default, OpenAM sends password reset notifications from <Password-Administrator>.

   To set a valid from address, extract amPasswordResetModuleMsgs.properties from , copy it to WEB-INF/classes/ where OpenAM is deployed, and then edit the file to change the fromAddress.label property value, as in the following example.

   fromAddress.label=no-reply@example.com

   Save your work, and then restart OpenAM for the properties file change to take effect.

Procedure 8.3. To Prepare Users to Reset Passwords

Before a user can reset her password, she must choose answers for secret questions.

1. When her account is first created, direct the user to her idm/EndUser page, such as http://openam.example.com:8080/openam/idm/EndUser, where she can provide a valid email address to recover the reset password and can edit Password Reset Options.

   
   [D]

   By default OpenAM console redirects end users to this page when they login.

2. After the user updates her secret questions, she can use the password reset service when necessary.

   
   [D]

   	Note
   	Answers to secret questions are case sensitive.

Procedure 8.4. To Direct Users to Reset Passwords

Having setup her email and answers to secret questions, the user can use the reset password service.

Create a test subject and use these steps to validate your configuration.

1. Send the user with a forgotten password to enter her user ID at the password reset URL.

   If the user is in the default realm use password at the end of the URL to OpenAM, as in http://openam.example.com:8080/openam/password.

   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 ui/PWResetUserValidation?realm=realm name, as in http://openam.example.com:8080/openam/ui/PWResetUserValidation?realm=realm name.

   
   [D]

2. The user answers the specified questions, and clicks OK.

   OpenAM resets the password, sending mail to the SMTP service you configured.

   
   [D]

   When the user clicks OK, OpenAM sends the email and shows a confirmation message.

   The user receives the email with a line such as the following.

   Your OpenAM password was changed to:  647bWluw

3. The user logs in using the new password.

   If you configured the system to force a change on password reset, then OpenAM requires the user to change her password.