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.
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
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.
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:
- 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||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||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.
The realmname directory must all be in lower case for the realm customizations to be located.
- 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.
- 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.
- 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.
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):