How do I customize the fields for User Self-Service pages in AM (All versions)?

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 identity repository; if they do not, you can add them as detailed in Add custom user 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 /am-external/openam-ui/openam-ui-user/src/resources/locales/en directory in the XUI source code (AM 7 and later) or the /path/to/tomcat/webapps/am/XUI/locales/en directory (AM 6.x) by default. However, depending on where AM 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 is retrieving the requested locale from the "Accept-Language" HTTP header in the web browser, you must create an en-US directory in the 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 Localize AM for further information.

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

• Customizing the User Self-Service pages (AM 7 and later)
• Customizing the User Self-Service pages (AM 6.x)

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 7 and later)

Changes have been made in AM 7, which mean you need to rebuild the UI to apply changes to user-facing UI text as detailed in the Important Changes AM 7 (Localizing User-Facing UI Text Requires Rebuilding the UI).

The following templates are located in the /am-external/openam-ui/openam-ui-user/src/resources/themes/default/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 Download the XUI to obtain the XUI source.
2. Edit the required template file (located in the /am-external/openam-ui/openam-ui-user/src/resources/themes/default/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. 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.
4. Follow steps in Test and deploying the XUI to test your changes, then rebuild and deploy.
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 AM admin UI, Amster or ssoadm:
   • AM admin UI: 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.

6. 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 6.x)

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 Download 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 Test 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 AM admin UI, Amster or ssoadm:
   • AM admin UI: 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.

6. Clear your browser cache and restart the web application container in which AM 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:
   • AM 7 and later: $ ./ssoadm set-attr-defs -s selfService -t organization -u uid=amAdmin,ou=People,dc=am,dc=forgerock,dc=org -f pwd.txt -a selfServiceUserRegistrationValidUserAttributes=mail selfServiceUserRegistrationValidUserAttributes=inetUserStatus selfServiceUserRegistrationValidUserAttributes=sn selfServiceUserRegistrationValidUserAttributes=username selfServiceUserRegistrationValidUserAttributes=userPassword selfServiceUserRegistrationValidUserAttributes=kbaInfo selfServiceUserRegistrationValidUserAttributes=title
   • AM 6.x: $ ./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 runs to apply these changes.

See Also

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

Customizing AM

User Self-Service in AM

User self-service

Related Training

ForgeRock Access Management Customization and APIs (AM-421)

Related Issue Tracker IDs

N/A