# OpenAM Administration Guide
Chapter 8. Configuring Password Reset

Sidebar | Prev | Up | Next

## 8.2. Resetting Forgotten Passwords

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.

| Tip
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. Do not therefore set up the service to reset the password used to access the email account specified in the user's profile.

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.