FAQ
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated Apr 13, 2021

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.


4 readers recommend this article

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


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.