Customizing AM

This book provides information on customizing AM including customizing the XUI.


How do I modify the prompt text shown when authenticating to a tree in AM 5.5.x, 6.x and 7.x?

The purpose of this article is to provide assistance if you want to customize the prompt text displayed when authenticating to a tree. This article focuses on changing the User Name and Password prompts.

Background information

Collector nodes provide a callback mechanism where input is collected. A typical example is the username collector, which provides a single text-based callback.

The two main collectors of interest when customizing the login process are the Username Collector Node and the Password Collector Node; each of the collector nodes have a corresponding properties file, which contains the callback.[name] property. This property defines the prompt text.

The collector nodes' property files are located in the auth-nodes-<version>.jar file in the WEB-INF/lib directory of the AM WAR file. You can find these files in the following path within the jar file: org/forgerock/openam/auth/nodes.

Note

Authentication nodes do not have customizable HTML files in the same way that authentication modules do. An RFE exists for this: OPENAM-14467 (RFE: Ability to customise Authentication Tree's).

Modifying the prompt text

The following example demonstrates changing the user name and password prompts:

  1. Unpack the AM WAR file and extract the auth-nodes-<version>.jar file from the WEB-INF/lib directory.
  2. Navigate to the org/forgerock/openam/auth/nodes path within the extracted jar.
  3. If you want localized versions: copy the UsernameCollectorNode.properties and PasswordCollectorNode.properties files to UsernameCollectorNode_xx.properties and PasswordCollectorNode_xx.properties respectively, where _xx corresponds to the required locale, for example _en for English.
  4. Edit the UsernameCollectorNode.properties file (or the UsernameCollectorNode_xx.properties files if you have localized versions) to update the callback.username property to the prompt of your choice, for example: callback.username=Your User Name
  5. Edit the PasswordCollectorNode.properties file (or the PasswordCollectorNode_xx.properties files if you have localized versions) to update the callback.password property to the prompt of your choice, for example: callback.password=Your Password
  6. Repack the auth-nodes-<version>.jar with your changes.
  7. Add your customization to the AM WAR file:
    • Replace the existing jar file in the WEB-INF/lib directory with your customized jar file.
    • Repack the AM WAR file and deploy as normal.
  8. Restart the web application container in which AM runs.
  9. Test your changes.

The resulting login page looks like this after a restart:

Followed by the Password Collector Node:

See Also

Best practice for migrating Authentication Chains to Trees in AM 6.x

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

How do I customize authentication tree nodes using source code in AM 5.5.x and 6?

Authentication and Single Sign-On Guide › Configuring Authentication Trees

Related Training

N/A

Related Issue Tracker IDs

OPENAM-14467 (RFE: Ability to customise Authentication Tree's)

OPENAM-12978 (API Explorer - Create Page Node Example Value is inadequate)


How do I modify the text on the XUI Login page for one or more realms in AM (All versions)?

The purpose of this article is to provide assistance if you want to customize the text on the XUI Login page for one or more realms in AM if you are authenticating to a chain.

Overview

Before starting your customizations, it is recommended that you set the following advanced server property to false:

org.forgerock.openam.core.resource.lookup.cache.enabled = false

This setting allows AM to immediately pick up changes to the files as you customize them

See FAQ: Customizing, branding and localizing XUI end user pages in AM (Q. Why are my theme changes being ignored?) for further information on setting this property.

Assumptions

The following instructions assume you are using the default configuration suffix (dc=openam,dc=forgerock,dc=org) and are changing English text. You should be aware of the following if either or both of these assumptions are not true of your deployment:

  • Configuration Suffix: where the instructions refer to creating an openam or openam_en directory, the openam prefix refers to the RDN of the configuration suffix dc=openam,dc=forgerock,dc=org.
  • Localization: where the instructions refer to creating an openam_en directory, the _en refers to the English locale. If you want to customize the Login page for a different language, you should create an openam_xx directory that corresponds to your locale of choice. The default directories for supported locales can be found by navigating to the /path/to/tomcat/webapps/openam/config/auth directory.

Depending on your deployment, you may need to make both of these changes by substituting the example directory names openam and openam_en in the instructions to match your RDN and Locale. For example, if you have changed the default configuration suffix to dc=acme,dc=com and you want to change the French language text for the login page in the employees realm, you would create a directory named acme_fr/services/employees/html directory:

/path/to/tomcat/webapps/openam/config/auth/acme_fr/services/employees/html
Note

It is best practice to make your changes in both the openam directory and the openam_en directory as this ensures all users will see your changes regardless of their locale. Customizations in the openam directory are seen by users whose locale does not match one of the available locales. However, depending on your requirements, it may be sufficient to just make changes in the openam directory.

Modifying the text on the Login page for one or more realms

You can customize the Login page for the top level realm, an individual realm or all / the majority of realms depending on where you make your changes:

  1. Create a directory in the path that AM will use to look up your customized files. Navigate to the /path/to/tomcat/webapps/openam/config/auth directory and create one or more directories as follows depending on where you want your customizations to apply:
Directory Location Directory to create Resulting path
openam Top level realm openam/html  /path/to/tomcat/webapps/openam/config/auth/openam/html 
openam Individual realm openam/services/realmname/html  /path/to/tomcat/webapps/openam/config/auth/openam/services/realmname/html 
openam All or the majority of realms openam/services/html  /path/to/tomcat/webapps/openam/config/auth/openam/services/html 
openam_en  Top level realm openam_en/html  /path/to/tomcat/webapps/openam/config/auth/openam_en/html 
openam_en  Individual realm openam_en/services/realmname/html  /path/to/tomcat/webapps/openam/config/auth/openam_en/services/realmname/html  
openam_en  All or the majority of realms openam_en/services/html  /path/to/tomcat/webapps/openam/config/auth/openam_en/services/html 

If you choose to make changes that affect all or the majority of realms, these customizations will affect all realms that do not have a corresponding realmname/html directory.

Note

The realmname directory must all be in lower case for the realm customizations to be located.

  1. Copy the contents of the /path/to/tomcat/webapps/openam/config/auth/default and/or /path/to/tomcat/webapps/openam/config/auth/default_en directory to your new /html directories.
  2. Edit the .xml file applicable to the authentication module for which you want to customize the login page; such as, the DataStore.xml file for the Data Store authentication module. You can change the header or prompt text shown, add additional HTML fields and even add script blocks, which will be executed when the page loads.
  3. Restart the web application container in which AM runs.

You can have a combination of customizations, for example, you can have a login page for the top level realm, one for the customers realm and a separate one for all other realms by changing the relevant .xml file in all three places.

Example changes in the DataStore.xml file

The following example DataStore.xml file has been updated to change the prompts for user name and password, and also the header text shown:

<ModuleProperties moduleName="DataStore" version="1.0" >    <Callbacks length="2" order="1" timeout="120" header="Sign in to AM" >         <NameCallback>             <Prompt>Your User Name:</Prompt>         </NameCallback>         <PasswordCallback echoPassword="false" >             <Prompt>Your Password:</Prompt>         </PasswordCallback>     </Callbacks> </ModuleProperties>

The resulting login page looks like this after a restart (in AM 7):

See Also

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

How do I configure login page session timeouts in AM (All versions) when using authentication modules?

UI Customization Guide › Customizing the UI Layout

Authentication and Single Sign-On Guide › Configuring Authentication Chains

Related Training

ForgeRock Access Management Core Concepts (AM-400)

ForgeRock Access Management Customization and APIs (AM-421)

Related Issue Tracker IDs

N/A


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

The purpose of this article is to provide information on customizing the User Self-Service pages (XUI) in AM. 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 identity repository; if they do not, you can add them as detailed in Setup Guide › Adding 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/openam/XUI/locales/en directory (pre-AM 7) 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 UI Customization Guide › Localizing AM for further information.

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 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 Release Notes › 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 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-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 UI Customization Guide › Testing 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 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 6.x)

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)

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 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.

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=openam,dc=forgerock,dc=org -f pwd.txt -a selfServiceUserRegistrationValidUserAttributes=mail selfServiceUserRegistrationValidUserAttributes=inetUserStatus selfServiceUserRegistrationValidUserAttributes=sn selfServiceUserRegistrationValidUserAttributes=username selfServiceUserRegistrationValidUserAttributes=userPassword selfServiceUserRegistrationValidUserAttributes=kbaInfo selfServiceUserRegistrationValidUserAttributes=title
    • Pre-AM 7: $ ./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 XUI end user pages in AM

Customizing AM

User Self-Service in AM

User Self-Service Guide

Related Training

ForgeRock Access Management Customization and APIs (AM-421)

Related Issue Tracker IDs

N/A


Frequently Asked Questions


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

The purpose of this FAQ is to provide answers to commonly asked questions regarding customizing, branding and localizing XUI end user pages in AM. 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. 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 UI Layout for further information on customizing the user-facing pages.

Note

For production deployments, you should unzip the AM .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 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:

  • 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.
  • ssoadm: enter the following command: $ ./ssoadm update-server-cfg -s [serverName] -u [adminID] -f [passwordfile] -a org.forgerock.openam.core.resource.lookup.cache.enabled=falsereplacing [serverName], [adminID] and [passwordfile] with appropriate values.
Note

Before using AM 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 in AM 6.x per known issue: OPENAM-14096 (No Cache Busting in XUI for i18n or CSS), which is resolved in AM 7.

AM 5.x

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.

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. 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 (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 to download, rebuild and deploy the XUI project. Once you have downloaded the XUI source, you can edit the following template files as required:

  • AM 7 and later:
    • DataStore1.html file is located in the /am-external/openam-ui/openam-ui-user/src/resources/themes/default/templates/openam/authn directory.
    • The other template files are located in the /am-external/openam-ui/openam-ui-user/src/resources/themes/default/templates/common directory.
  • AM 6.x:
    • 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.

AM 5.x

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

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

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 or user messages displayed in AM?

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 /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/openam/XUI/locales/en directory (pre-AM 7) 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 UI Customization Guide › Localizing AM for further information.

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 runs for it to take effect.

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.

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 Reference › 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?

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)?

  • 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 IDM, 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 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 › Client Registration 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, 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 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 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 › Client Registration 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, 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 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 should I call a realm level login page?

A. The correct format for the URL with the realm parameter is as follows: http://host1.example.com:8080/openam/XUI/?realm=/RealmName#login

See Authentication and Single Sign-On Guide › Specifying the Realm in the URL for further information.

Q. Is JavaScript® required for logging into AM?

A. Yes it is, the console and login pages packaged with AM 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=7.0.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 choose the language shown in user-facing XUI pages?

A. AM 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:

  • Console: navigate to: Configure > Server Defaults > 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 › Localizing AM 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 has a responsive design by default.

See Also

Customizing AM

UI Customization Guide

Related Training

ForgeRock Access Management Customization and APIs (AM-421)

Related Issue Tracker IDs

N/A


Source Code


How do I update and recompile the iOS authenticator app with custom branding in AM (All versions)?

The purpose of this article is to provide information on updating and recompiling the iOS® authenticator app in AM so that it can be published to the Apple® App Store. Changes include renaming the app and rebranding changes, such as updating the Splashscreen video, updating the app icon and changing default colors.

Warning

ForgeRock support covers the use of the official binary builds made available and downloaded from our customer portal: BackStage. We will support builds made from source providing no changes have been made to the core code of the product, the product was built from a tag that matches an official release, for example, 6 and said product was built using the ForgeRock build scripts provided as part of the source. In the event that a customer experiences an issue with a ForgeRock product built from source where ForgeRock believe the issue is as a result of the build process, ForgeRock reserves the right to ask the customer to attempt to reproduce the issue on an official ForgeRock binary build. Customers who are running custom builds or who need further clarification should contact their ForgeRock sales representative.

Overview

This article explains how to clone the iOS ForgeRock Authenticator app source code and create your own version of the app that you can publish to the Apple App Store. There is also a section that provides links relevant to setting up Push notifications.

High level steps

  1. Create a new iOS App Bundle ID
  2. Obtain Authenticator source, prepare a project and open in Xcode
  3. Launch the App on an iPhone®
  4. Rename the project
  5. Rename the scheme
  6. Update the CocoaPods configuration
  7. Rename the ForgeRock-Authenticator directory
  8. Rename the Entitlements file
  9. Update the Build settings and rebuild
  10. Update the Test Build settings
  11. Update the Splashscreen video
  12. Update App Permission Request dialogs
  13. Update Localizable.strings
  14. Update About.strings
  15. Update the App icon
  16. Update the Default Account icon
  17. Update the Default colors
  18. Publish your App

These steps were completed using Xcode Version 10.0 (10A255).

Note

Before updating the Authenticator app, please make sure Xcode® is installed and up-to-date.

Create a new iOS App Bundle ID

  1. Log in to your paid Apple Developer account (http://developer.apple.com/account).
  2. Select Certificates, Identifiers & Profiles.
  3. Select App IDs (under Identifiers in the menu on the left).
  4. Select the “+” (Add) icon.
  5. Complete the Registering an App ID form:
    1. Enter an App ID description, for example “ACME Authenticator”.
    2. Select Explicit App ID and enter a bundle ID, for example “com.acme.authenticator”.
    3. Leave default selections for App Services (we will enable “Push Notifications” later in this article):
  1. Select “Register”, then “Done” to complete creation of your new iOS App Bundle ID.

Obtain Authenticator source, prepare a project and open in Xcode

Note

To clone the source code with a SSH URL, you must have created a SSH key and added it to your Bitbucket profile.

  1. Git clone the ForgeRock Authenticator iOS repository: $ git clone ssh://git@stash.forgerock.org:7999/openam/forgerock-authenticator-ios.git
  2. Install CocoaPods. See CocoaPods - Getting Started for further information.
  3. Prepare the project to be opened in Xcode:
    1. Navigate to the project’s root directory on the command line and download the project’s dependencies: $ cd forgerock-authenticator-ios $ pod install 
    2. Open the project in Xcode: $ open ForgeRock.xcworkspace/
  4. Select the “ForgeRock” folder from the “Project Navigator View” in Xcode to view the app’s configuration in the main Xcode view.
  5. Update the App Identity settings:
    1. Bundle identifier, this should be the same as set in step 5b in the previous section, for example “com.acme.authenticator”.
    2. Version, for example “1.0.0”.
    3. Build, for example “1”.
  6. Update the App Signing settings:
    1. Enable “Automatically manage signing”; this is enabled for the official ForgeRock app.
    2. Team, this should refer to your Apple developer account.
    3. Provisioning profile, you should have a provisioning profile.
    4. Signing certificate, you should have a signing certificate.

Before making further changes, now would be a good time to verify that you are able to run the code on a physical device as detailed in Launch the App on an iPhone.

Dependency versions

Downloading the project's dependencies captures the versions in the Podfile.lock file (located in the project's root directory). This ensures that the same versions will be downloaded if the pod install command is re-run.

To update to a newer version of a dependency, you can use a combination of pod outdated to identify dependencies that are outdated and pod update to update them. See CocoaPods install vs update documentation for further details. If you make changes to third-party dependencies, you must also update the LIBRARIES file.

Launch the App on an iPhone

  1. Connect an iPhone to the laptop running Xcode.
  2. Accept the dialog displayed on your iPhone asking if you would like to trust your computer.
  3. Select your phone from the devices dropdown in the top-left of Xcode.
  4. Select the “Play” icon.

Rename the project

  1. Select the “ForgeRock” folder from the “Project Navigator View” in Xcode to view the app’s configuration in the main Xcode view.
  2. Select the "File inspector" on the right hand-side; the name of your project should be in there under "Identity and Type":
  1. Change the name of your project to a new name, for example to “ACME”.
  2. Review the contents that will be renamed by Xcode and select “Rename”:

See How do I completely rename an Xcode project (i.e. inclusive of folders)? for further information on these steps.

Rename the scheme

  1. Click on the scheme for your OLD product (in the top bar near the "Stop" icon), then select "Manage schemes":
  1. Click on the OLD name in the scheme to make it editable and change the name:

See How do I completely rename an Xcode project (i.e. inclusive of folders)? for further information on these steps.

Update the CocoaPods configuration

  1. Close Xcode.
  2. Open the Podfile (located in the project's root directory) in a text editor and update as follows:
    • Rename the target “ForgeRock”, for example to “ACME”.
    • Rename the target “ForgeRockTests”, for example to “ACMETests”:
  1. Navigate to the project’s root directory on the command line and and run the pod install command again to apply the CocoaPods changes: $ cd [project_root_dir] $ pod install
  2. Remove the ForgeRock.xcworkspace directory (also in the project’s root directory): $ rm -rf ForgeRock.xcworkspace
  3. Open the updated project in Xcode: $ open ACME.xcworkspace/

Rename the ForgeRock-Authenticator directory

  1. Close Xcode.
  2. Rename the directory using Git in order to preserve the history: $ git mv ForgeRock-Authenticator ACME-Authenticator
  3. Re-open the project in Xcode: $ open ACME.xcworkspace/
  4. Dismiss any warnings regarding missing files.
  5. Select “Authenticator” from the “Project Navigator View” in Xcode; it should be shown in red.
  6. Navigate to the Utilities pane under "Identity and Type" where you will see the "Name" entry.
  7. Select the folder icon to show a new dialog and update the location:

Rename the Entitlements file

  1. Rename the ForgeRock.entitlements file (located in the project's root directory), for example to ACME.entitlements:

Update the Build settings and rebuild

  1. Select the project from the “Project Navigator View” in Xcode.
  2. Select “General”, scroll down to the “Linked Frameworks and Libraries” section and remove the “libPods-ForgeRock.a” entry:
  1. Select "Build Settings", followed by “Packaging” and update the “Info.plist File” path, for example to “ACME-Authenticator/ACME-Info.plist”:
  1. Navigate to "Signing" and update the following:
    1. “Code Signing Entitlements” path, for example to “ACME.entitlements”.
    2. “Prefix header”, for example to “ACME-Authenticator/ACME-Prefix.pch”:
  1. Rebuild the project:
    1. Command + Shift + K to clean.
    2. Command + B to build.

Before making further changes, now would be a good time to verify that you are able to run the code on a physical device as detailed in Launch the App on an iPhone.

Update the Test Build settings

  1. Select the project from the “Project Navigator View” in Xcode.
  2. Select the “ACMETests” target in the main view.
  3. Select "Build Settings", followed by “Bundle Loader” and update the following:
    1. “Debug” path, for example to “$(BUILT_PRODUCTS_DIR)/ACME.app/ACME”.
    2. “Release” path, for example to “$(BUILT_PRODUCTS_DIR)/ACME.app/ACME”:
  1. Select “Build Phases”, followed by “Link Binary with Libraries” and remove the “libPods-ForgeRockTests.a” entry:

Update the Splashscreen video

  1. Replace the splashvideo.mp4 file (located in the [project_root_dir]/ACME-Authenticator directory) with the updated video file. Keeping the same filename means you do not have to update other project files.

Update App Permission Request dialogs

  1. Replace references to ForgeRock within the ACME-Info.plist file (located in the [project_root_dir]/ACME-Authenticator directory). For example, change them to ACME:

Update Localizable.strings

  1. Replace references to ForgeRock within the Localizable.strings file (located in the [project_root_dir]/ACME-Authenticator/en.lproj directory). For example, change them to ACME:

Update About.strings

  1. Replace relevant references to ForgeRock within the About.strings (located in the [project_root_dir]/ACME-Authenticator/Settings.bundle/en.lproj directory). For example, change them to ACME:
Note

ForgeRock and other copyright attributions should not be changed.

Update the App icon

  1. Generate a new set of icon files and a Contents.json file. These can be generated from a single source image using an online service such as https://appicon.co/.
  2. Replace the contents of the [project_root_dir]/ACME-Authenticator/Images.xcassets/AppIcon.appiconset/ directory with the set of icon files and a Contents.json file:

Update the Default Account icon

  1. Replace the forgerock-logo.png file (located in the [project_root_dir]/ACME-Authenticator directory) with an updated icon. If you want to change the name of this file, for example to acme-logo.png, then you must also update the references to it in the following files (using a text editor to find and replace is likely the easiest approach):
    • FRAUIUtils.m (located in the [project_root_dir]/ACME-Authenticator directory).
    • Main.storyboard (located in the [project_root_dir]/ACME-Authenticator directory)
    • project.pbxproj (located in the [project_root_dir]/ACME.xcodeproj directory):

Optional

You can delete the following files (located in the [project_root_dir]/ACME-Authenticator directory) from Xcode and the file system if you want as they are not used:

  • forgerock-logo-text.png 
  • forgerock-logo-opaque.png 

Update the Default colors

  1. Update colors in the following files (located in the [project_root_dir]/ACME-Authenticator directory); colors to update are specified in brackets:
    • FRANotificationsTableViewController.m (seaGreen and dashboardRed)
    • FRACircleProgressView.m (lightGrey)
    • FRAOathMechanismTableViewCellController.m (seaGreen and dashboardRed)
  2. Update colors and layout defined in the Main.storyboard file (located in the [project_root_dir]/ACME-Authenticator directory) if necessary.
Note

Any changes made to the Main.storyboard file will result in merge conflicts when rebasing over later changes to the official app; ForgeRock's development approach allows edits to this file by only one developer at a time.

Publish your App

Once you have completed all your changes and rebuilt the app, you can submit your app to the Apple App Store. The following links provide useful Apple resources on the next steps:

Set up Push notifications

Refer to the following articles for further information on setting up Push notifications:

See Also

FAQ: Source code in AM

Xcode Help

CocoaPods Guides


Copyright and TrademarksCopyright © 2021 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...