How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated Apr 13, 2021

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.


2 readers recommend this article

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


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