User Self-Service in AM/OpenAM

This book provides information on the User Self-Service in AM/OpenAM including customizations and known issues (with solutions).


How do I update REST API calls after upgrading to a newer version of AM/OpenAM?

The purpose of this article is to provide a single point of reference for evolving REST API endpoints. You can use this information to find equivalent REST API endpoints after upgrading AM/OpenAM, where known endpoints have been deprecated or removed in later versions of AM/OpenAM. Deprecated endpoints are not supported and you should move to the replacement endpoints at your earliest convenience.

Deprecated / removed endpoints (AM 6.5)

No endpoints were deprecated or removed in AM 6.5.

Deprecated / removed endpoints (AM 6)

No endpoints were deprecated or removed in AM 6.

Deprecated endpoints (AM 5.5)

The following endpoint is deprecated in AM 5.5; you should use the replacement endpoint going forward:

Deprecated endpoints Replacement endpoints
/oauth2/connect/register /oauth2/register

Deprecated endpoints (AM 5)

The following endpoints are deprecated in AM 5; you should use the replacement endpoints going forward:

Deprecated endpoints Replacement endpoints
/json/realms /json/global-service/realms
/frrest/oauth2/token

/oauth2/introspect (to read and list OAuth 2.0 tokens)

/oauth2/token/revoke (to delete (revoke) OAuth 2.0 tokens)

/json/sessions/?_action=getTimeLeft

/json/sessions/?_action=getMaxSessionTime

/json/sessions/?_action=getMaxIdle

/json/sessions/?_action=getIdle

/json/sessions/?_action=getSessionInfo
/json/sessions/?_action=isActive&refresh=true /json/sessions/?_action=refresh

/json/sessions/?_action=getPropertyNames

/json/sessions/?_action=getProperty

/json/sessions/?_action=getSessionProperties
/json/sessions/?_action=setProperty /json/sessions/?_action=updateSessionProperties

Deprecated endpoints (OpenAM 13.5)

The following endpoints are deprecated in OpenAM 13.5; you should use the replacement endpoints going forward:

Deprecated endpoints Replacement endpoints
/json/sessions/?_action=getMaxTime /json/sessions/?_action=getTimeLeft
/json/users/_action=register /json/selfservice/userRegistration
/json/users/?_action=confirm /json/selfservice/userRegistration
/json/users/?_action=anonymousCreate /json/selfservice/userRegistration
/json/users/?_action=forgotPassword /json/selfservice/forgottenPassword
/json/users/?_action=forgotPasswordReset /json/selfservice/forgottenPassword

Removed endpoints (OpenAM 13)

The following endpoints are removed in OpenAM 13; you should use the replacement endpoints going forward (where they are available):

Removed endpoints Replacement endpoints
/ws/1/entitlement/decision, /ws/1/entitlement/decisions, /ws/1/entitlement/entitlement, /ws/1/entitlement/entitlements /json/policies?_action=evaluate, /json/policies?_evaluateTree
/identity/log --
/identity/getCookieNamesForToken --
/identity/getCookieNamesToForward --
/json/[realm/]referrals --
/ws/1/entitlement/listener --
/ws/1/entitlement/privilege --
/ws/1/token​ --

Unsupported action values

The following _action values are unsupported in OpenAM 13 for the /json/users endpoint since they relate to the legacy user self service features:

/json/users/?_action=register 
/json/users/?_action=confirm 
/json/users/?_action=anonymousCreate 
/json/users/?_action=forgotPassword 
/json/users/?_action=forgotPasswordReset

See OpenAM 13 Release Notes › Important Changes to Existing Functionality for further information about this change, which was introduced in Version 3.0 of the /json/users endpoint.

You should use the new user self-service features instead as detailed in User Self Service Guide › Implementing User Self Service. This includes the use of the new /json/selfservice endpoints.

Deprecated endpoints (OpenAM 12)

The following endpoints are deprecated in OpenAM 12; you should use the replacement endpoints going forward:

Deprecated endpoints Replacement endpoints
/identity/attributes /json/users
/identity/authenticate /json/authenticate
/identity/authorize /json/policies?_action=evaluate, /json/policies?_evaluateTree
/identity/create, /identity/delete, /identity/read, /identity/search, /identity/update /json/agents, /json/groups, /json/realms, /json/users
/identity/isTokenValid /json/sessions/tokenId?_action=validate
/identity/logout /json/sessions/?_action=logout
/ws/1/entitlement/decision, /ws/1/entitlement/decisions, /ws/1/entitlement/entitlement, /ws/1/entitlement/entitlements /json/policies?_action=evaluate, /json/policies?_evaluateTree

See Also

Development Guide › Developing with the REST API

Development Guide › Introducing the API Explorer

AM 5.5 Release Notes › Deprecated Functionality

AM 5 Release Notes › Deprecated Functionality

OpenAM 13.5 Release Notes › Deprecated Functionality

OpenAM 13 Release Notes › Removed Functionality

OpenAM 12 Release Notes › Deprecated Functionality

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3877 (Changing password through new REST endpoint fails if default AuthN chain needs more than just the password to authenticate)


How do I change the data store minimum password length in AM/OpenAM (All versions)?

The purpose of this article is to provide information on changing the data store minimum password length in AM/OpenAM. The minimum password length defaults to 8; this is a data store setting that applies to password changes (when existing users reset their password or change their password) and is independent of any password length restrictions in DS/OpenDJ. This also includes forgotten password resets made via the REST API user self-service functionality (XUI).

Overview

You can change the data store minimum password length using ssoadm (in all versions) or Amster (in AM 5 and later):

This setting cannot be changed in the console.

Using Amster

You can change the data store minimum password length using Amster; you can do this globally or in a specific realm, where realm level takes precedence over the global level. 

Follow the steps in How do I update property values in AM (All versions) using Amster?with these values:

  • Entity: IdRepository
  • Property: minimumPasswordLength
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes. 

Using ssoadm

You can change the data store minimum password length using ssoadm; you can do this globally or in a specific realm, where realm level takes precedence over the global level:

  • ssoadm - Global: 
    1. Run the following command to create a data file (called DATA_FILE to match the next command), which is populated with the current sunIdRepoAttributeValidator property values to ensure you don't lose any existing changes:
      $ ./ssoadm get-attr-defs -s sunIdentityRepositoryService -t Organization -u [adminID] -f [passwordfile] | grep sunIdRepoAttributeValidator > DATA_FILE
      
      replacing [adminID] and [passwordfile] with appropriate values.
    2. Update the data file you just created by amending the sunIdRepoAttributeValidator=minimumPasswordLength property value. For example, if you want to increase the minimum password length to 10, you would change it to:
      sunIdRepoAttributeValidator=minimumPasswordLength=10
    3. Run the following command to update the sunIdRepoAttributeValidator property values:
      $ ./ssoadm set-attr-defs -s sunIdentityRepositoryService -t Organization -u [adminID] -f [passwordfile] -D DATA_FILE
      replacing [adminID] and [passwordfile] with appropriate values.
    4. Restart the web application container in which AM/OpenAM runs to apply these configuration changes.
  • ssoadm - Realm:
    1. Run the following command to create a data file (called DATA_FILE to match the next command), which is populated with the current sunIdRepoAttributeValidator property values to ensure you don't lose any existing changes:
      $ ./ssoadm get-realm-svc-attrs -s sunIdentityRepositoryService -e [realmname] -u [adminID] -f [passwordfile] | grep sunIdRepoAttributeValidator > DATA_FILE
      
      replacing [realmname], [adminID] and [passwordfile] with appropriate values.
    2. Update the data file you just created by amending the sunIdRepoAttributeValidator=minimumPasswordLength property value. For example, if you want to increase the minimum password length to 10, you would change it to:
      sunIdRepoAttributeValidator=minimumPasswordLength=10
    3. Run the following command to update the sunIdRepoAttributeValidator property values:
      $ ./ssoadm set-realm-svc-attrs -s sunIdentityRepositoryService -e [realmname] -u [adminID] -f [passwordfile] -D DATA_FILE
      replacing [realmname], [adminID] and [passwordfile] with appropriate values.
Note

When changing the data store minimum password length in OpenAM 13.5.x, AM 5 or AM 5.1, you may encounter an "Exception in thread "SystemTimer" java.lang.Error: java.lang.ExceptionInInitializerError" response. This error can be safely ignored since the operation performed by ssoadm still completes successfully. See java.lang.ExceptionInInitializerError when using ssoadm commands in AM 5, 5.1 and OpenAM 13, 13.5, 13.5.1 for further information.

See Also

Forgotten password reset or password change fails with Minimum password length is 8 error in AM/OpenAM (All versions)

How do I change what characters are permitted in user names in AM/OpenAM (All versions) for authentication purposes?

Setup and Maintenance Guide › Setting Up Realms › Changing Passwords using the REST API

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8999 (Incorrect messages are displayed when a user tries to change their password and it does not meet the minimum length)

OPENAM-6867 (changePassword REST endpoint is not returning LDAP issues that are related to a user mistake.)

OPENAM-6166 (Allow Forgotten Password functionality in OpenAM to use other user attributes besides uid and mail)


FAQ: Customizing, branding and localizing XUI end user pages in AM/OpenAM

The purpose of this FAQ is to provide answers to commonly asked questions regarding customizing, branding and localizing XUI end user pages in AM/OpenAM. It also includes information on other customizations such as error messages and forgotten password emails.

Frequently asked questions

Q. How do I customize user-facing pages in the XUI?

A. As of OpenAM 13 you can use themes to alter the appearance of user-facing XUI pages. The XUI is built with the Bootstrap framework, and supports Bootstrap themes to customize the look and feel of the user interface. You can apply themes to specific realms, and also to specific authentication chains within those realms. These themes apply to all user-facing XUI pages (Login, User profile, User Self-Service and UMA). Additionally, you can make changes to template files to change how pages display and function.

See UI Customization Guide › Customizing the User Interface for further information on customizing the user-facing pages.

In OpenAM 12.x, the XUI interface is still evolving and theming is handled differently as described in OpenAM 12 Installation Guide › Configuring the XUI.

Note

For production deployments, you should unzip the AM/OpenAM .war file, add your customizations and then rezip the .war file before deploying.

Q. Why are my theme changes being ignored?

A. This is likely a cache issue. You should completely clear your browser cache after making any changes.

During the customization process, you can set the org.forgerock.openam.core.resource.lookup.cache.enabled advanced server property to false. This setting allows AM/OpenAM to immediately pick up changes to the files located in the /path/to/tomcat/webapps/openam/config/auth/ directory as you customize them. These files include the authentication module (callback) XML files and legacy UI template files.

You can set this advanced property using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Deployment > Servers > [Server Name] > Advanced and add the org.forgerock.openam.core.resource.lookup.cache.enabled property and set it to false.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > [Server Name] > Advanced and add the org.forgerock.openam.core.resource.lookup.cache.enabled property and set it to false.
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -s [serverName] -u [adminID] -f [passwordfile] -a org.forgerock.openam.core.resource.lookup.cache.enabled=false
    replacing [serverName], [adminID] and [passwordfile] with appropriate values.
Note

Before using AM/OpenAM in production, you should set this property back to the default setting of true to improve performance.

Q. How can I ensure end users see the latest file rather than a cached version?

A. In AM 6 and later, file names include a .[hash] suffix, where [hash] is an alphanumeric value generated each time the XUI is rebuilt. This hash ensures the latest version is always loaded. However, this doesn't apply to translations or CSS files per known issue: OPENAM-14096 (No Cache Busting in XUI for i18n or CSS).

Pre-AM 6

If you are customizing files such as .html, .css or .js, you can ensure updated files are loaded in the browser instead of earlier cached versions by changing the urlArgs value in the index.html file (located in the /path/to/tomcat/webapps/openam/XUI directory) at the same time. For example, in AM 5, you could add -1 to the default of 14.0.0:

        <script type="text/javascript">
            var require = {
                urlArgs : "v=14.0.0-1",
                deps : ['main']
            };
        </script>

This value is appended to files as a parameter when they are called, which ensures the new files are loaded rather than a cached version. You can see this in the browser using developer tools, for example:

DataStore1.html?v=14.0.0-1

 Index.html has a cache time of max-age=300, so users should see any changes quite quickly.

Q. What troubleshooting steps should I take if my theme is not applied as expected?

A. The first troubleshooting step you should take is to check that you don't have any typos in your theme configuration files. For JSON files, you can use a JSON validator in your IDE or text editor to verify the JSON syntax, or use http://jsonlint.com.

In AM / OpenAM 13.x, you should also check the following:

  • Ensure your Bootstrap theme follows standard conventions and complies with the Bootstrap framework.
  • Check the order of elements in the mappings array in the ThemeConfiguration.[hash].js file in AM 6 and later (where [hash] is an alphanumeric value generated each time the XUI is rebuilt) or the ThemeConfiguration.js file in AM 5.x and OpenAM 13.x. These files are located in the /path/to/tomcat/webapps/openam/XUI/config/ directory. Mappings are evaluated in order starting at the top; the first theme that matches the current realm and/or authentication chain is applied and all subsequent mappings are ignored even if they are true.

Q. How do I customize the Login page?

A. You can customize the login page by amending the associated template files. The default login page with a DataStore authentication module uses the DataStore1.html, NavigationTemplate.html, LoginBaseTemplate.html and FooterTemplate.html template files. For example, you can add additional HTML fields to the DataStore1.html file or script blocks, which will be executed when the page loads to extend the functionality further. To customize login pages for other authentication modules, you need to create a new file based on DataStore1.html. For example, you would create LDAP1.html for the LDAP authentication module by copying DataStore1.html and amending as needed.

See How do I modify the text on the XUI Login page for one or more realms in AM/OpenAM (All versions)? for information on customizing the text on the login page, which uses a different file.

AM 6 and later

Changes have been made in AM 6 to optimize XUI delivery using Webpack as detailed in the Release Notes › Major Improvements (General).

You can customize these templates files by following the steps in UI Customization Guide › Customizing the User Interface to download, rebuild and deploy the XUI project. Once you have downloaded the XUI source, you can edit the following template files as required:

  • DataStore1.html file is located in the /am-external/openam-ui/openam-ui-ria/src/main/resources/templates/openam/authn directory.
  • The other template files are located in the /am-external/openam-ui/openam-ui-ria/src/main/resources/templates/common directory.

Pre-AM 6

The DataStore1.html file is located in the /path/to/tomcat/webapps/openam/XUI/templates/openam/authn directory where AM/OpenAM is deployed and the other template files are located in the /path/to/tomcat/webapps/openam/XUI/templates/common directory where AM/OpenAM is deployed.

You can change these template files as needed and restart the web application container in which AM/OpenAM runs.

Q. Aren't the authentication module XML files legacy?

A. No, the authentication module XML files (located in the /path/to/tomcat/webapps/openam/config/auth/ directory where AM/OpenAM is deployed) are not legacy. Although these files do affect the content seen by the end-user using the classic UI, they also affect the pages when XUI is used.

Q. How do I change the user naming attribute value for the User Profile page?

A. The uid value is used by default for the Username field on the User Profile page. If you have made changes to your data store configuration (such as replacing uid with cn) or you use Active Directory® for your data store (which does not use uid), you can map the uid attribute to the one you use to ensure the user name is shown correctly on the User Profile page:

Navigate to: Realms > [Realm Name] > Data Stores > [Data Store Name] > Attribute Name Mapping and specify your mapping, for example:

uid=cn

Q. How do I customize error / user messages displayed in AM/OpenAM?

A. You should amend the text in the translation.json file to customize the displayed user messages. The file containing the English text is located in the /path/to/tomcat/webapps/openam/XUI/locales/en directory where AM/OpenAM is deployed. However, depending on where AM/OpenAM is retrieving the requested locale from, you may need to create a new locale folder. For example, if the locale in your browser is set to en-US and AM/OpenAM is retrieving the requested locale from the "Accept-Language" HTTP header in the web browser, you must create an en-US directory in the XUI/locales directory, copy the contents from the en directory to this new directory and modify the translation.json file in the en-US directory.

See UI Customization Guide › Localizing the XUI for further information on using this file to translate AM/OpenAM text. 

Authentication Failed message

The Authentication Failed message displayed in a red popup when logging in is the response from the REST /json/authenticate endpoint:

{
  "code": 401,
  "reason": "Unauthorized",
  "message": "Authentication Failed"
}
{"code":401,"reason":"Unauthorized","message":"Access Denied"}

This means you cannot change it via the translation.json file.

This message comes from amAuth.properties (errorCode: 107) within the openam-core-*.jar file. You can extract this file from the jar, customize the message and place the updated amAuth.properties file in the /path/to/tomcat/webapps/openam/WEB-INF/classes directory. You will need to restart the web application container in which AM/OpenAM runs for it to take affect. 

Note

You cannot localize the Authentication Failed message per known issue:  OPENAM-4201 (XUI returning messages based on localised responses from REST authentication interface).

Q. How do I include the user's email address or username in the forgotten password email?

A. Allowing the username to be sent via the change password functionality requires custom coding. There is a RFE to include this option: OPENAM-10464 (Allow OpenAM to include the username/email of the user whose password is being reset in the forgotten password reset link).

If you require this functionality, you can customize the following Forgotten Password Service Config Provider Class that is used by the forgotten password function:

org.forgerock.openam.selfservice.config.flows.ForgottenPasswordConfigProvider

The org.forgerock.openam.selfservice.config.flows.ForgottenUsernameConfigProvider class described in User Self Service Guide › Advanced Configuration sends the username by passing the %username% function; you can use this as the basis for customizing the forgotten password class. You should be able to make similar customizations to make the email address available in the forgotten password email as well.

Note

This change is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.

Q. How do I customize the self-registration or forgotten password pages in AM / OpenAM 13.x?

A. You can configure which fields are shown on the following user self-service pages as described in How do I customize the fields for User Self-Service pages in AM (All versions) and OpenAM 13.x?

  • User Registration
  • Password Reset
  • Forgotten Username

See Custom Stages to User Self-Service for information on adding custom plugins or stages to further extend the functionality; although this blog post mainly references OpenIDM, it is a common self-service so the same steps are applicable.

Q. How do I customize the Authorization Consent page (oauth2/authorize endpoint)?

A. This depends on what version of AM/OpenAM you are using:

AM 6.5

As of AM 6.5, you can customize this page (and other user-facing pages) on a per realm basis using the logo_uri, client_uri and policy_uri parameters (RFC 7591). See OAuth 2.0 Guide › Advanced for further information.

Pre-AM 6.5

The OAuth Authorization Consent page is rendered by a template (authorize.ftl). This template is located inside the openam-oauth2-x.x.x.jar (OpenAM 13.5 and later) or the oauth2-restlet-1x.0.x.jar (pre-OpenAM 13.5), which is in the WEB-INF/lib directory within openam.war.

Extract a version of the authorize.ftl file from the templates/page directory within the jar file and copy it to the /path/to/tomcat/webapps/openam/WEB-INF/classes/templates/pages directory where AM/OpenAM is deployed. You can then edit this file to customize the Authorization Consent page, ensuring you do not change any of the tags. Any changes you make in this way apply to all realms.

Q. How do I customize other OAuth 2.0 pages?

A. Similar to the Authorization Consent page, it depends on what version of AM/OpenAM you are using:

AM 6.5

As of AM 6.5, you can customize user-facing pages on a per realm basis using the logo_uri, client_uri and policy_uri parameters (RFC 7591). See OAuth 2.0 Guide › Advanced for further information.

Pre-AM 6.5

The other OAuth 2.0 pages are rendered by template files (*.ftl). These template files are located inside the openam-oauth2-x.x.x.jar (OpenAM 13.5 and later) or the oauth2-restlet-1x.0.x.jar (pre-OpenAM 13.5), which is in the WEB-INF/lib directory within openam.war.

Extract a version of the required *.ftl file from the templates/ directory within the jar file and copy it to the corresponding /path/to/tomcat/webapps/openam/WEB-INF/classes/templates/ directory where AM/OpenAM is deployed. You can then edit this file to customize the page, ensuring you do not change any of the tags. Any changes you make in this way apply to all realms.

Q. How do I change or remove the link associated with the ForgeRock logo on the Login page in OpenAM 12.x?

A. In OpenAM 12.x, the ForgeRock logo is a link that returns you to the top level realm login page.

You can change or remove this link functionality as follows: 

  1. Edit the LoginBaseTemplate.html file (located in the /path/to/tomcat/webapps/openam/XUI/templates/common directory where OpenAM is deployed) and update the following line:
    <a href="#" title="{{theme.settings.logo.title}}">
    
  2. You can change this link as follows depending on what you're trying to achieve:
    • Remove link:
      <a title="{{theme.settings.logo.title}}">
      
    • Change link:
      <a href="http://www.newlink.com" title="{{theme.settings.logo.title}}">
      
  3. Clear the browser cache and retest; you should now see your changes.

Q. How should I call a realm level login page?

A. The correct format for the URL with the realm parameter depends on your version:

  • AM 5 and later:
    http://host1.example.com:8080/openam/XUI/?realm=/RealmName#login
  • Pre-AM 5:
    http://host1.example.com:8080/openam/XUI/#login/&realm=RealmName

See AM Authentication and Single Sign-On Guide › Specifying the Realm in the Login URL or OpenAM 13.5 Administration Guide › Specifying the Realm in the Login URL for further information.

Note

There is a known issue with including the realm in the URL: OPENAM-6470 (ThemeManager.js doesn't need to strip "/" anymore when loading theme for realm). This is fixed in OpenAM 12.0.4. As a workaround in earlier versions, you can remove the first letter from your sub-realm name in themeConfig.json.

Q. Is JavaScript® required for logging into AM/OpenAM?

A. Yes it is, the console and login pages packaged with AM/OpenAM are JavaScript based, so a browser needs JavaScript enabled to render these pages correctly. You could create a custom interface using the REST API if a non-JavaScript based UI was required.

Q. Why do country specific locale pages display the default en language?

A. If you have created a translation.json file for a new locale (for example zh), the appropriate customizations are shown when your locale is zh. However, by default, any country specific locales within that locale (for example zh-HK), fall back to the default en customizations rather than the expected zh customizations.

To ensure the correct customizations are shown for country specific locales, you need to add a new config option (with the i18nLoad option set to specific) to the index.html file (located in the /path/to/tomcat/webapps/openam/XUI directory). The updated section should now look like this:

        <script type="text/javascript">
            var require = {
                urlArgs : "v=13.5.0",
                config : {
                   'org/forgerock/commons/ui/common/main/i18nManager': {
                      i18nLoad: 'specific'
                   }
                },
                deps : ['main']
            };
        </script>

See  OPENAM-7123 (Allow country-specific localization in XUI) for further information.

Q. How does AM/OpenAM choose the language shown in user-facing XUI pages?

A. AM/OpenAM chooses which language to show content in (and loads the associated translation file) based on the user's locale. The user's locale is derived in the following order:

  1. The locale query string parameter in the URL, for example, &locale=fr
  2. The locale set in the user’s browser, which is a 2 or 5 character long language or locale, for example en or en-US.
  3. The Default locale, which is set to en by default. This is used when neither a query string parameter or browser language is set. 

Default locale

You can change the default locale using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Server Defaults > General > System > Default Locale and specify the default locale.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > General > System > Default Locale and specify the default locale.
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.iplanet.am.locale=[locale]
    replacing [adminID], [passwordfile] and [locale] with appropriate values.

See UI Customization Guide › Customizing the User Interface › Localizing the XUI for further details. This section explains how to localize the text that is generated for the user-facing XUI pages.

Q. Can I make pages responsive for use on mobile devices?

A. AM / OpenAM 13.x has a responsive design by default. In OpenAM 12.x, you need to customize the XUI files to make the CSS responsive. There is a known limitation regarding pages that include tables; these cannot be made fully responsive due to the particular library that was used in OpenAM 12.

Q. Can I customize the JSP files in XUI?

A. No, you cannot. The JSP files are specific to the Classic UI and do not affect the appearance of the XUI.

Q. Can I use the Classic UI instead of the XUI?

A. Although you can use the Classic UI, it is not recommended because the XUI has a more modern REST architecture. Additionally, the Classic UI is deprecated in OpenAM 13 and likely to be removed in a future release.

See Also

Understanding and customizing the XUI in OpenAM 12.x

How do I add a new custom XUI page in AM 5.x and OpenAM 13.x?

Customizing AM/OpenAM

Related Training

ForgeRock Access Management Core Concepts (AM-400)

ForgeRock Access Management Customization and APIs (AM-421)

Related Issue Tracker IDs

OPENAM-8452 (Cannot access Sub Realm with DNS Alias set (XUI) with 404 Not Found)

OPENAM-8342 (AuthorizeTemplate ignores custom theme)

OPENAM-7282 (Forgotten password submit button is disabled when using autocomplete)


How do I customize the fields for User Self-Service pages in AM (All versions) and OpenAM 13.x?

The purpose of this article is to provide information on customizing the User Self-Service pages (XUI) in AM/OpenAM. This information will help you add and remove fields from the User Registration, Password Reset and Forgotten Username pages.

Overview

Each of the user self-service pages are associated with a template.

The basic process to add and remove fields from these pages is the same; you just need to make the changes to the appropriate template. Customizing the User Registration page includes an extra step to configure the user attributes the user can set during registration. These attributes must exist in the AM/OpenAM identity repository; if they do not, you can add them as detailed in Setup and Maintenance Guide › Customizing Profile Attributes before following these steps.

If you have added a new field, you also need to update the translation.json file. This file is located in the /path/to/tomcat/webapps/openam/XUI/locales/en directory by default. However, depending on where AM/OpenAM is retrieving the requested locale from, you may need to create a new locale folder. For example, if the locale in your browser is set to en-US and AM/OpenAM is retrieving the requested locale from the "Accept-Language" HTTP header in the web browser, you must create an en-US directory in the XUI/locales directory, copy the contents from the en directory to this new directory and modify the translation.json file in the en-US directory.

Note

You should take backups of any files you plan to change to ensure you can revert your changes if needed.

The details for where the template files are located and how you retrieve them differ according to your version:

There is also a worked example which shows how you would add and remove fields from the User Registration page; this example applies to all versions.

Customizing the User Self-Service pages (AM 6 and later)

Changes have been made in AM 6 to optimize XUI delivery using Webpack as detailed in the Release Notes › Major Improvements (General).

The following templates are located in the /am-external/openam-ui/openam-ui-ria/src/main/resources/templates/user/process directory once you have obtained the source:

  • User Registration page - registration/userDetails-initial.html
  • Password Reset page - reset/userQuery-initial.html
  • Forgotten Username page - username/userQuery-initial.html

You can customize these pages as follows (worked examples are shown below to give more details):

  1. Follow the steps in UI Customization Guide › Downloading the XUI to obtain the XUI source.
  2. Edit the required template file (located in the /am-external/openam-ui/openam-ui-ria/src/main/resources/templates/user/process directory):
    • To remove an existing field: Remove the div element associated with the field you want to remove.
    • To add a new field: Add a div element for the new field based on the other fields in the template.
  3. Follow steps in UI Customization Guide › Testing and Deploying the XUI to test your changes, then rebuild and deploy.
  4. If you have added a new field: Update the translation.json file to add a mapping for the new field if it does not already exist. Navigate to the "user" : { section and skip past the page specific translations (such as userQuery, passwordReset etc) until you reach the list of fields that include the following:
    "user" : {
                "userQuery" : {
    ...
    
      "username" : "Username",
      "emailAddress" : "Email address",
      "givenName" : "First Name",
      "sn" : "Last Name",
      ...
    }
    
    Add the new field in the same format with the label you want displayed.
  5. If you are updating the User Registration page: Update the user attributes the user can set during registration. These attributes must exist in the identity repository and correspond to the fields you have added or removed. You can update these attributes using either the console, Amster or ssoadm:
    • Console: navigate to: Configure > Global Services > User Self Service > User Registration > Valid Creation Attributes and add the additional user attributes / delete any that have been removed.
    • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
      • Entity: UserSelfService
      • Property: userRegistrationValidUserAttributes
    • ssoadm: enter the following command:
      $ ./ssoadm set-attr-defs -s selfService -t organization -u [adminID] -f [passwordfile] -a selfServiceUserRegistrationValidUserAttributes=[userAttribute] selfServiceUserRegistrationValidUserAttributes=[userAttribute] selfServiceUserRegistrationValidUserAttributes=[userAttribute] ...
      replacing [adminID], [passwordfile] and [userAttribute] with appropriate values.
Caution

You must include the selfServiceUserRegistrationValidUserAttributes attribute for each required attribute, including any that already exist. The ones you add with this command will overwrite any that have already been set.

  1. Clear your browser cache and restart the web application container in which AM runs to apply these changes. 

Customizing the User Self-Service pages (AM 5.x and OpenAM 13.x)

The following templates are located in the /path/to/tomcat/webapps/openam/XUI/templates/user/process directory:

  • User Registration page - registration/userDetails-initial.html
  • Password Reset page - reset/userQuery-initial.html
  • Forgotten Username page - username/userQuery-initial.html

You can customize these pages as follows (worked examples are shown below to give more details):

  1. Edit the required template file:
    • To remove an existing field: Remove the div element associated with the field you want to remove.
    • To add a new field: Add a div element for the new field based on the other fields in the template.
  2. If you have added a new field: Update the translation.json file to add a mapping for the new field if it does not already exist. Navigate to the "user" : { section and skip past the page specific translations (such as userQuery, passwordReset etc) until you reach the list of fields that include the following:
    "user" : {
                "userQuery" : {
    ...
    
      "username" : "Username",
      "emailAddress" : "Email address",
      "givenName" : "First Name",
      "sn" : "Last Name",
      ...
    }
    
    Add the new field in the same format with the label you want displayed.
  3. If you are updating the User Registration page: Update the user attributes the user can set during registration. These attributes must exist in the identity repository and correspond to the fields you have added or removed. You can update these attributes using either the console, Amster (AM 5.x) or ssoadm:
    • AM 5.x / OpenAM 13.5 console: navigate to: Configure > Global Services > User Self Service > User Registration > Valid Creation Attributes and add the additional user attributes / delete any that have been removed.
    • OpenAM 13 console: navigate to: Configuration > Global > User Self Service > User Registration > Valid Creation Attributes and add the additional user attributes / delete any that have been removed.
    • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
      • Entity: UserSelfService
      • Property: userRegistrationValidUserAttributes
    • ssoadm: enter the following command:
      $ ./ssoadm set-attr-defs -s selfService -t organization -u [adminID] -f [passwordfile] -a selfServiceUserRegistrationValidUserAttributes=[userAttribute] selfServiceUserRegistrationValidUserAttributes=[userAttribute] selfServiceUserRegistrationValidUserAttributes=[userAttribute] ...
      replacing [adminID], [passwordfile] and [userAttribute] with appropriate values.
Caution

You must include the selfServiceUserRegistrationValidUserAttributes attribute for each required attribute, including any that already exist. The ones you add with this command will overwrite any that have already been set.

  1. Clear your browser cache and restart the web application container in which AM/OpenAM runs to apply these changes. 

Example changes to the User Registration page

This worked example removes the First Name field from the User Registration page and adds a Title field:

  1. Edit the registration/userDetails-initial.html file.
  2. Remove the First Name field by removing the following div element:
        <div class="form-group">
            <label class="sr-only separator" for="input-givenName">
                <span>{{t 'common.user.givenName'}}</span>
            </label>
            <input type="text" placeholder="{{t 'common.user.givenName'}}" id="input-givenName" name="user.givenName" class="form-control input-lg" />
        </div>
    
    
  3. Add the Title field by adding a new div element as follows:
        <div class="form-group">
            <label class="sr-only separator" for="input-title">
                <span>{{t 'common.user.title'}}</span>
            </label>
            <input type="text" placeholder="{{t 'common.user.title'}}" id="input-title" name="user.title" class="form-control input-lg" />
        </div>
    
  4. Update the translation.json file to add a new mapping for the Title field. This mapping should be in the list of fields within the "user" : { section (seen once you have skipped past the page specific translations such as userQuery, passwordReset etc). For example, append the Title field at the end of this list of fields as follows:
    "user" : {
                "userQuery" : {
    ...
    
      "username" : "Username",
      "emailAddress" : "Email address",
      "givenName" : "First Name",
      "sn" : "Last Name",
      ...
      ...
      "title" : "Title",
    },
    
  5. Update the valid creation attributes. For example using the ssoadm command: 
    $ ./ssoadm set-attr-defs -s selfService -t organization -u amadmin -f pwd.txt -a selfServiceUserRegistrationValidUserAttributes=mail selfServiceUserRegistrationValidUserAttributes=inetUserStatus selfServiceUserRegistrationValidUserAttributes=sn selfServiceUserRegistrationValidUserAttributes=username selfServiceUserRegistrationValidUserAttributes=userPassword selfServiceUserRegistrationValidUserAttributes=kbaInfo
    selfServiceUserRegistrationValidUserAttributes=title
  6. Clear your browser cache and restart the web application container in which AM/OpenAM runs to apply these changes. 

See Also

FAQ: Customizing, branding and localizing XUI end user pages in AM/OpenAM

How do I add a new custom XUI page in AM 5.x and OpenAM 13.x?

How do I change the title shown on the browser tab in AM 5.x and OpenAM 13.x?

User Self-Service in AM/OpenAM

User Self Service Guide › Implementing User Self Service

Related Training

ForgeRock Access Management Core Concepts (AM-400)

ForgeRock Access Management Customization and APIs (AM-421)

Related Issue Tracker IDs

N/A


Known Issues


Forgotten password reset or password change fails with Minimum password length is 8 error in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if the forgotten password reset or password change fails with a "Minimum password length is 8." error in AM/OpenAM. This includes forgotten password resets made via the REST API user self-service functionality and can occur even if DS/OpenDJ does not have a minimum password length specified.

Symptoms

The following response is received when changing a user's password using the REST API:

{"code":400,"reason":"Bad Request","message":"Minimum password length is 8."}

An error similar to the following is shown in the CoreSystem log:

frRest:03/23/2015 12:21:47:014 PM EST: Thread[http-/192.168.48.10:8080-1,5,main]
Validated token with ID, /yYP00ugcvJhNAnaPT4qUV+aJ+M=, in realm, /internal against GlJuGh/4ZqIlJe8Qew4JOjWPMuc=
amIdentityServices:02/23/2015 12:37:20:023 PM EST:
Thread[http-/192.168.48.10:8080-1,5,main]
**********************************************
amIdentityServices:03/23/2015 12:21:47:023 PM EST:
Thread[http-/192.168.48.10:8080-1,5,main]
ERROR: IdentityServicesImpl:update
Message:Minimum password length is 8.

        at
com.sun.identity.idm.server.IdRepoAttributeValidatorImpl.validateAttributes(IdRepoAttributeValidatorImpl.java:114)
        at
com.sun.identity.idm.server.IdServicesImpl.setAttributes(IdServicesImpl.java:1688)
        at
com.sun.identity.idm.server.IdCachedServicesImpl.setAttributes(IdCachedServicesImpl.java:525)
       at com.sun.identity.idm.AMIdentity.store(AMIdentity.java:535)
        at
com.sun.identity.idsvcs.opensso.IdentityServicesImpl.update(IdentityServicesImpl.java:1157)
        at
org.forgerock.openam.forgerockrest.IdentityResourceV2.updateInstance(IdentityResourceV2.java:948)
        at
org.forgerock.openam.forgerockrest.IdentityResourceV2.anonymousUpdate(IdentityResourceV2.java:893)
        at
org.forgerock.openam.forgerockrest.IdentityResourceV2.actionCollection(IdentityResourceV2.java:651)
        at
org.forgerock.json.resource.Resources$CollectionHandler.handleAction(Resources.java:226)
        at org.forgerock.json.resource.Router.handleAction(Router.java:208)
        at
org.forgerock.json.resource.VersionRouter$VersionRouterImpl.handleAction(VersionRouter.java:463)
        at org.forgerock.json.resource.Router.handleAction(Router.java:208)
        at
org.forgerock.json.resource.VersionRouter.handleAction(VersionRouter.java:300)
        at
org.forgerock.openam.rest.resource.CrestRouter.handleAction(CrestRouter.java:76)
[...]

frRest:02/23/2015 12:37:20:024 PM EST: Thread[http-/192.168.58.10:8080-1,5,main]
ERROR: IdentityResource.updateInstance() :: Cannot UPDATE!
com.sun.identity.idsvcs.GeneralFailure: Minimum password length is 8.

Recent Changes

Implemented the user self-service functionality to reset forgotten passwords.

Causes

The minimum password length is a data store setting that applies to password changes and is independent of any password length restrictions in DS/OpenDJ. When a new password with less than 8 characters (default minimum password length) is specified, the forgotten password reset or password change fails.

Solution

This issue can be resolved by ensuring all users comply with the minimum password length or by adjusting the minimum password length required.

See How do I change the data store minimum password length in AM/OpenAM (All versions)? for further information.

See Also

How do I change the data store minimum password length in AM/OpenAM (All versions)?

Setup and Maintenance Guide › Setting Up Realms › Changing Passwords

Related Training

N/A

Related Issue Tracker IDs

OPENAM-6166 (Allow Forgotten Password functionality in OpenAM to use other user attributes besides uid and mail)

OPENAM-6867 (changePassword REST endpoint is not returning LDAP issues that are related to a user mistake.)

OPENAM-8999 (Incorrect messages are displayed when a user tries to change their password and it does not meet the minimum length)


Internal server error when using User Self-Service in AM 5 and 5.1

The purpose of this article is to provide assistance if a user gets an "Internal server error" when using the User Self-Service in AM 5 and 5.1, for example, they click the Forgotten Password? link on the login page. You will also see an "ERROR: Unable to handle read" message in the logs.

Symptoms

The following message is shown when using the User Self-Service:

Internal server error

An error similar to the following is shown in the org.forgerock.openam.selfservice.SelfServiceRequestHandler debug log:

org.forgerock.openam.selfservice.SelfServiceRequestHandler:04/18/2017 02:11:39:934 PM BST: Thread[http-bio-8080-exec-10,5,main]: TransactionId[86089244-87fc-458f-8b1d-d2e1d6668aec-241]
ERROR: Unable to handle read
java.lang.IllegalArgumentException: Required attribute selfServiceForgottenPasswordEmailBody
   at org.forgerock.openam.sm.config.ConsoleConfigHandlerImpl.populateAnnotatedMethods(ConsoleConfigHandlerImpl.java:143)
   at org.forgerock.openam.sm.config.ConsoleConfigHandlerImpl.getConfig(ConsoleConfigHandlerImpl.java:79)
   at org.forgerock.openam.selfservice.SelfServiceRequestHandler.createNewService(SelfServiceRequestHandler.java:173)
   at org.forgerock.openam.selfservice.SelfServiceRequestHandler.getService(SelfServiceRequestHandler.java:163)
   at org.forgerock.openam.selfservice.SelfServiceRequestHandler.handleRead(SelfServiceRequestHandler.java:133)
   at org.forgerock.json.resource.Router.handleRead(Router.java:333)
   at org.forgerock.json.resource.FilterChain$Cursor.handleRead(FilterChain.java:105)
Note

The required attribute specified in the log may vary. For example, "Required attribute selfServiceEncryptionKeyPairAlias" has also been seen.

Recent Changes

Upgraded to, or installed AM 5 or 5.1.

Configured User Self-Service as a Global Service (navigate to: Configure > Global Services > User Self-Service).

Causes

There is a known issue: OPENAM-11057 (Global User Self Service UI does not display values), where the global User Self-Service UI does not display the default values that are returned by the server. When you configure User Self-Service at a global level, only the settings you specify are saved and any default values are removed upon Save.

Solution

This issue can be resolved by upgrading to AM 5.1.1 or later; you can download this from BackStage.

Workaround

This issue can be resolved by configuring all the necessary values using ssoadm or the console:

ssoadm: The following process steps through checking what settings have been saved and then adding new values via ssoadm:

  1. Check what settings have actually been set using the ssoadm get-attr-defs command, for example:
    $ ./ssoadm get-attr-defs -s selfService -t organization -u amadmin -f pwd.txt
    
    selfServiceProfileProtectedUserAttributes=
    selfServiceValidQueryAttributes=uid
    selfServiceValidQueryAttributes=mail
    selfServiceValidQueryAttributes=sn
    selfServiceValidQueryAttributes=givenName
    selfServiceForgottenUsernameCaptchaEnabled=false
    selfServiceForgottenPasswordServiceConfigClass=org.forgerock.openam.selfservice.config.flows.ForgottenPasswordConfigProvider
    selfServiceSigningSecretKeyAlias=
    selfServiceForgottenUsernameEmailUsernameEnabled=true
    selfServiceForgottenPasswordConfirmationUrl=http://host1.example.com:8080/openam/XUI/?realm=${realm}#passwordReset/
    selfServiceUserRegistrationCaptchaEnabled=false
    selfServiceUserRegistrationServiceConfigClass=org.forgerock.openam.selfservice.config.flows.UserRegistrationConfigProvider
    selfServiceForgottenUsernameShowUsernameEnabled=false
    selfServiceMinimumAnswersToVerify=1
    selfServiceForgottenPasswordEnabled=false
    KeyAliasValidator=org.forgerock.openam.selfservice.config.KeyAliasValidator
    selfServiceCaptchaSiteKey=
    selfServiceCaptchaSecretKey=
    selfServiceUserRegistrationEnabled=false
    selfServiceUserRegistrationDestination=default
    selfServiceUserRegistrationValidUserAttributes=inetUserStatus
    selfServiceUserRegistrationValidUserAttributes=mail
    selfServiceUserRegistrationValidUserAttributes=username
    selfServiceUserRegistrationValidUserAttributes=sn
    selfServiceUserRegistrationValidUserAttributes=userPassword
    selfServiceUserRegistrationValidUserAttributes=kbaInfo
    selfServiceUserRegistrationValidUserAttributes=givenName
    selfServiceMinimumAnswersToDefine=1
    selfServiceForgottenUsernameKbaEnabled=false
    selfServiceForgottenUsernameEmailBody=en|<h2>Your username is <span style="color:blue">%username%</span>.</h2>
    selfServiceForgottenPasswordEmailVerificationEnabled=true
    selfServiceForgottenUsernameTokenTTL=900
    selfServiceUserRegistrationTokenTTL=900
    selfServiceUserRegistrationKbaEnabled=false
    selfServiceEncryptionKeyPairAlias=
    selfServiceUserRegistrationEmailBody=en|<h2>Click on this <a href="%link%">link</a> to register.</h2>
    selfServiceUserRegistrationEmailSubject=en|Registration email
    selfServiceUserRegistrationEmailVerificationEnabled=true
    selfServiceForgottenUsernameServiceConfigClass=org.forgerock.openam.selfservice.config.flows.ForgottenUsernameConfigProvider
    selfServiceForgottenUsernameEnabled=false
    selfServiceForgottenUsernameEmailSubject=en|Forgotten username email
    selfServiceCaptchaVerificationUrl=https://www.google.com/recaptcha/api/siteverify
    selfServiceForgottenPasswordTokenTTL=900
    selfServiceForgottenPasswordEmailSubject=en|Forgotten password email
    selfServiceUserRegistrationConfirmationUrl=http://host1.example.com:8080/openam/XUI/?realm=${realm}#register/
    selfServiceForgottenPasswordCaptchaEnabled=false
    selfServiceForgottenPasswordKbaEnabled=false
    selfServiceKBAQuestions=4|en|What is your mother's maiden name?
    selfServiceKBAQuestions=2|en|What was the model of your first car?
    selfServiceKBAQuestions=1|en|What is the name of your favourite restaurant?
    selfServiceKBAQuestions=3|en|What was the name of your childhood pet?
    
    Schema attribute defaults were returned.
  2. Add any missing attributes, using the ssoadm set-attr-defs command. For example, to set the selfServiceForgottenPasswordEmailBody attribute noted in the log:
    $ ./ssoadm set-attr-defs -s selfService -t organization -u amadmin -f pwd.txt -a selfServiceForgottenPasswordEmailBody="en|<h2>Click on this <a 
    href="%link%">link</a> to reset your password.</h2>"
    You can set multiple attributes using ssoadm as detailed in How do I add multiple attributes with a single ssoadm command in AM/OpenAM (All versions)?
Note

You must add the attributes as shown in the log / get-attr-defs output, that is, they must have the selfService prefix. There is a known issue with the documentation whereby they are shown without this prefix: OPENAM-11046 (ssoadm properties in Self-Service docs are missing selfService prefix).    

Console: Navigate to: Configure > Global Services > User Self-Service and complete all the required fields on the General Configuration tab and the tab specific to the functionality you are configuring. (You can also do this at the realm level by navigating to: Realms > [Realm Name] > Services and adding the User Self-Service.)

For example, the following screenshots display the default settings needed to configure the Forgotten Password functionality for all realms (the General Configuration tab must be completed for all areas of User Self-Service):

  • General Configuration tab:

  • Forgotten Password tab:

See Also

User Self Service Guide

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11057 (Global User Self Service UI does not display values)

OPENAM-11046 (ssoadm properties in Self-Service docs are missing selfService prefix)


goto parameter is lost at end of the User Self-Service Forgot Password flow in OpenAM 13.0 and 13.5

The purpose of this article is to provide assistance when parameters, including the goto parameter, are lost after completing the User Self-Service Forgot Password (XUI) flow in OpenAM 13.0 and 13.5. This occurs when the user clicks the Return to Login Page link.

Symptoms

The goto parameter that is present in the login URL, for example:

http://host1.example.com:8080/openam/XUI/#login/&goto=http://forgerock.com

is removed after the user resets their password (using the Forgot Password link) and returns to the login page (using the Return to Login Page link).

This behavior can also be seen in SAML 2 federation where the IdP or SP initiated login URL contains parameters; when selecting the Forgot Password link on the IdP, these parameters are also lost at the end of the flow.

Recent Changes

Implemented the user self-service Forgotten Password Reset feature.

Causes

The XUI strips out the parameters from the login URL at the end of the Forgot Password flow instead of preserving them throughout the process.

Solution

This issue can be resolved by upgrading to OpenAM 13.5.1 or later; you can download this from BackStage.

Note

The goto parameter is retained if the user remains within the browser throughout the process, however, it is lost once the process leaves the UI. This means the goto parameter is still removed if you have email verification switched on. There is an RFE to ensure the goto parameter is retained when email verification is used: OPENAM-10394 (RFE: Include goto URL in verification email sent during User Registration / Forgot Password flow).

See Also

Internal server error when using User Self-Service in AM 5 and 5.1

Link in Forgotten Password and User Registration emails in AM/OpenAM (All versions) does not work in Outlook 2007 and 2010

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11057 (Global User Self Service UI does not display values)

OPENAM-10394 (RFE: Include goto URL in verification email sent during User Registration / Forgot Password flow)

OPENAM-9597 (Goto URL with multiple query string parameters incorrectly decoded)

OPENAM-9238 (USS Forgotten password flow on subrealm loses the realm)

OPENAM-9125 (The XUI needs to pass the goto=URL through whole password reset journey)

OPENAM-8998 (Completing USS Forgot Password flow results in lost goto parameter on Return to Login Page link)


Link in Forgotten Password and User Registration emails in AM/OpenAM (All versions) does not work in Outlook 2007 and 2010

The purpose of this article is to provide assistance if the link in the Forgotten Password and User Registration emails generated by AM/OpenAM does not work in Microsoft® Outlook® 2007 and 2010.

Symptoms

The link included in the Forgotten Password and User Registration emails does not work when clicked in Outlook 2007 or 2010. It works when copied to a browser.

Recent Changes

Configured the Forgotten Password Reset and/or User Self-Registration functionality.

Causes

There is a limitation in Outlook 2007 and 2010 where hyperlinks do not work if they exceed a certain length (~1030 characters). This limitation does not affect later versions of Outlook, other email clients or other Microsoft Office 2007 / 2010 applications. 

It is not possible to shorten the link generated by AM/OpenAM as it contains the JSON Web Token (JWT) token required for the password reset / registration process. An RFE exists to address this: OPENAM-10755 (Limitation in MS Outlook 's password reset link. The token URL generated is too long for Outlook to handle. ) 

Solution

A suggested workaround for this issue is to customize the email sent to end users to advise Outlook 2007 and 2010 users to copy and paste the link into their browser instead. The link should be left for users not affected by this issue. You can do this by changing the Outgoing Email Body for the Forgotten Password and/or User Registration emails.

The following example guides you through changing the Outgoing Email Body for the Forgotten Password email. The same concept applies to the User Registration email, which is found on the User Registration tab under User Self Service:

  1. Navigate to:
    • AM / OpenAM 13.5 console: navigate to: Configure > Global Services > User Self Service > Forgotten Password > Outgoing Email Body
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Global > User Self Service > Forgotten Password > Outgoing Email Body
  2. Remove the following text:
    en|<h2>Click on this <a href="%link%">link</a> to reset your password </h2>
    And replace with your customized message, for example:
    en|<h2>Click on this <a href="%link%">link</a> to reset your password </h2> <h2> If you are an Outlook 2007 or 2010 user, please copy and paste the following link into your browser to reset your password: %link% </h2>
  3. Save your changes.

The resulting email in this example will look like this:

Click on this link to reset your password
If you are an Outlook 2007 or 2010 user, please copy and paste the following link into your browser to reset your password: http://host1.example.com:8080/openam/XUI/#passwordReset/&realm=/&token=eyAidHlwIjogIkpXRSIsICJhbGciOiAiSFMyNTYiIH0.ZXlBaWRIbHdJam9nSWtwWFZDSXNJQ0poYkdjaU9pQWlVbE5CUlZOZlVFdERVekZmVmpGZk5TSXNJQ0psYm1NaU9pQWlRVEV5T0VOQ1ExOUlVekkxTmlJZ2ZRLnJTUEZVekljR0psTTg3OEVTRGFKRFRLblVNUWFtd2txMnhUVXJRUmhfbTJGYzJYeDIyNVpnLVVvMGxNM1I5bUxLbjhtTER5TDRwTzl4Mkk5UUpDdkRqOExoaEl4NXRuWmxBdnpob0xjZTVNTHludnQ2Y1dXN1ZCeExDNFMyQkFKWVNoYUFrRXlqYXJGM2hqWFNGQThlWmtWXzZlenM2bi1KaG9pdGdKSHo2OC5sSi01WjhCeWpYVkhxcGJXcHV6ZnV3LlJUWVhqcWhYT21Sd0ZmVnBJNjNtYURubmJBT2ZtSVUtVXE5dDA1MURNT1FuLU1RVHlhUmFBYWM0ajJMUTBJbzc1aUdJcjhqMjd1aHdXTVV1MU96am9rbWpoQXFWWGlRanlGa2ktbjRKZi15dzc5LThOVkctRXRUdFFsMHhGLUcwdzBNZThMaU0xd2Q2NFZHWFlZRDZ3SXRDQkxLUHo5ZExxSTJHZU9McjJuYlZaRVQyUHZncG94RTZoSG4wRHJ1cmc0cUZDQ0RsNzdhTjZKdVBuRjhuMWRyLVYxVkFqR3FPX3dtb2E1M0psVEk2ZFVHQlNoNXhfMDFSOVRaUFVKV1VNM0pCWkxNNEg3OG94WHktTnN6Uzc4cDRibTB0OUdHQXB2UGYtNndTU0JWYmpjQjlCSnk3Nk1yZklYSFJWZkRjbF9jR0NiWWZGSk0yZ182YThpd1VOa0VqM0ltblNxWkd5Mko1WTFkZ0dzQjZKQ1lGUXdFM3JlWUMxX1FYSUtFNi5jRmw0bDVzT3A4eDkwczhlOEZWaGZR.wmjwcpTjLqoiyqCka-UHv5pnImB8K6KZW_FuF2yC-Xo&code=0e6ae09d-6fbd-412b-8ad6-b45d8d89cc34

See Also

goto parameter is lost at end of the User Self-Service Forgot Password flow in OpenAM 13.0 and 13.5

How do I customize the fields for User Self-Service pages in AM (All versions) and OpenAM 13.x?

User Self Service Guide › Implementing User Self Service › Configuring the Forgotten Password Reset Feature

User Self Service Guide › Implementing User Self Service › Configuring User Self-Registration

Related Training

N/A

Related Issue Tracker IDs

OPENAM-10755 (Limitation in MS Outlook 's password reset link. The token URL generated is too long for Outlook to handle. )

OPENAM-3393 (Implement templates for emails sent by OpenAM REST services)

USS-116 (RFE: Password reset URL should be shorter to ensure compatibility with Outlook 2007/2010)


User forced to change password again after resetting password during Forgot Password flow in AM 5.x and OpenAM (All versions)

The purpose of this article is to provide assistance if users are forced to change their password again when logging in after they have reset their password through the Forgotten Password link in AM/OpenAM User Self-Service functionality. This issue only happens when you are using DS/OpenDJ for the user store and have added it as an LDAP module (where LDAP Behera Password Policy Support is enabled).

Symptoms

User clicks the Forgotten Password link and resets their password. They then log in using their new password and are prompted to change their password again.

Recent Changes

Set the following property to true in the DS/OpenDJ password policy:

force-change-on-reset:true

Causes

When a password is reset during the Forgotten Password flow, the self-service password reset functionality changes the user’s password as an administrator. This administrative change creates the pwdReset operational attribute, which prompts a password reset when force-change-on-reset:true is enabled and upon the next login attempt. Per the password policy, the pwdReset=true flag is only removed after a login or proof of knowledge that the end user knows the password the admin set.

In summary, you are enforcing the behavior on both AM/OpenAM and DS/OpenDJ.

Solution

This issue can be resolved by upgrading to AM 6 or later; you can download this from BackStage. Once you have upgraded, you must enable the LDAP Proxied Authorization option, which supports the force-change-on-reset password policy. See Setup and Maintenance Guide › Directory Services Configuration Properties for further information.

Workarounds

If users only change their password through AM/OpenAM, you can use the force-change-on-add property instead. For example, these properties would be set as follows:

force-change-on-add:true
force-change-on-reset:false

These settings mean that users who were added to the system and logging into AM/OpenAM for the first time would be prompted to change their password, but users who reset their password via the Forgotten Password link would not be prompted again.

If you have a use case which prevents you setting the force-change-on-reset property to false, a suggested workaround is to use proxy authorization. Proxy authorization allows you to connect to a directory server as one user, yet perform operations as another user. For example, if your user data store connects as cn=Directory Manager or a similar admin user, proxy authorization lets you use uid=ANotherUser when performing an operation. You can read more about proxy authorization in these documentation links and blog posts:

You can also extend the IdRepo plugin class (typically DJLDAPv3Repo) and change the behavior of the setAttributes() method. You can specify a custom plugin class in the data store configuration as follows:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Data Stores > [Data Store Name] > Plug-in Configuration > LDAPv3 Repository Plugin Class Name and enter the name of your custom plugin class.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Data Stores > [Data Store Name] > Plug-in Configuration > LDAPv3 Repository Plugin Class Name and enter the name of your custom plugin class.
  • ssoadm: enter the following command:
    $ ./ssoadm update-datastore -e [realmname] -m [datastorename] -u [adminID] -f [passwordfile] -a sunIdRepoClass=[customPlugin]
    
    replacing [realmname], [datastorename], [adminID], [passwordfile] and [customPlugin] with appropriate values. If you are making changes against the top level realm, you must specify -e /
Note

Using proxy authorization and extending the IdRepo plugin class are outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.

See Also

Forgotten password reset or password change fails with Minimum password length is 8 error in AM/OpenAM (All versions)

Link in Forgotten Password and User Registration emails in AM/OpenAM (All versions) does not work in Outlook 2007 and 2010

goto parameter is lost at end of the User Self-Service Forgot Password flow in OpenAM 13.0 and 13.5

Internal server error when using User Self-Service in AM 5 and 5.1

How do I customize the fields for User Self-Service pages in AM (All versions) and OpenAM 13.x?

User Self Service Guide › Configuring the Forgotten Password Reset Feature

Related Training

N/A

Related Issue Tracker IDs

OPENAM-6618 (OpenAM "Forgot Password" makes the user change their password twice, if the OpenDJ Password Policy includes "force-change-on-reset")

OPENAM-5159 (Request to improve REST forgotPasswordReset page flow )


Copyright and TrademarksCopyright © 2018 - 2019 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...