FAQ: Customizing, branding and localizing end user pages in the OpenAM Classic UI
The purpose of this FAQ is to provide answers to commonly asked questions regarding customizing, branding and localizing end user pages in the OpenAM Classic UI. Common end user pages to customize include the Login page, Password Reset page, Security Questions page and Logout page. The Classic UI is deprecated in OpenAM 13.
4 readers recommend this article
Archived
This article has been archived and is no longer maintained by ForgeRock.
Frequently asked questions
- Q. How do I customize end user pages in the Classic UI?
- Q. Which end user pages can be customized?
- Q. How does OpenAM choose which UI file to use?
- Q. How does OpenAM determine the requested locale to use when returning localized files?
- Q. What is the "Accept-Language" HTTP header in the web browser?
- Q. What is the "locale" GET variable?
- Q. What is the Default locale?
- Q. What is the platform locale?
- Q. How do I customize the Password Reset page?
- Q. How do I change the password input from *** to plain text in the Login page?
- Q. How do I translate an authentication module in OpenAM into a different language?
- Q. How does OpenAM choose which .properties file to use?
- Q. How do I customize messages defined in the amAuthUI.properties file?
- Q. Can I reuse a customized .properties file from a previous release?
- Q. How can I customize pages such as the Login page for use on mobile devices?
- Q. Can the platform locales be different on different servers running behind a load balancer?
- Q. How do I remove attributes from the EndUser page?
- Q. How do I customize the EndUser page to make it display-only?
- Q. Can I add custom functionality to a page such as an additional check box?
Q. How do I customize end user pages in the Classic UI?
A. The procedure for customizing end user pages is described in OpenAM Installation Guide › Customizing the OpenAM End User Pages › Updating the Classic UI (Legacy).
Note
For production deployments, you must package your changes in a custom OpenAM deployable .war file. To create a deployable .war, unpack the OpenAM .war file from ~/Downloads/openam into a staging directory, apply your changes in the staging directory, and use the jar command to prepare the deployable .war.
Q. Which end user pages can be customized?
A. All the end user pages that can be customized are located in the /path/to/tomcat/webapps/openam/config/auth/default directory where OpenAM is deployed.
Images are stored in the /path/to/tomcat/webapps/openam/images directory where OpenAM is deployed and the CSS is stored in the /path/to/tomcat/webapps/openam/css directory where OpenAM is deployed.
The .jsp files that you can customize are detailed in OpenAM Reference › Service Endpoints › Default Authentication JSP Endpoints.
Note
Be careful when editing the UI files that you do not to change the JSP tags that govern how the pages work. Modify the localized text, using UTF-8 without escaped characters, by changing only the original text strings in the .xml files.
If necessary, restart OpenAM to test the changes you have made.
Q. How does OpenAM choose which UI file to use?
A. See OpenAM Installation Guide › Customizing the OpenAM End User Pages › How OpenAM Looks Up UI Files for further information. The platform locale is also involved in looking up UI files.
Q. How does OpenAM determine the requested locale to use when returning localized files?
A. OpenAM first looks for the "locale" Get variable and uses this as the requested locale if it exists. If this does not exist, OpenAM then looks for the first locale value specified in the "Accept-Language" HTTP header in the web browser. OpenAM does not currently consider all the other locales as potential values for the requested locale due to a known issue: OPENAM-4792 (Accept-Language header : consider the next language wished if the current one isn't implemented).
If neither the "locale" Get variable or the "Accept-Language" values are populated, the Default Locale value is used to return files.
Note
The requested locale is used to return .properties files and UI files. The requested locale is set during the login process in the authentication context and is used for all the HTTP requests until you log out; you must re-authenticate to change locales.
Q. What is the "Accept-Language" HTTP header in the web browser?
A. You can set an ordered list of different languages in the HTTP header by setting the Accept-Language variable. This variable is then added to every HTTP request you make from your web browser.
In Firefox® for example, you can set this by navigating to Preferences > Content and then click Choose... in the Languages section. Create the language ordered list for the Accept-Language header variable.
Q. What is the "locale" GET variable?
A. This variable allows you to modify the requested locale value. It is often useful during the customization development phase to check that a translation has been successfully implemented.
To assign this variable, you can add it to the GET parameters of your URL, for example:
http://openam.example.com/openam/UI/Login?locale=frQ. What is the Default locale?
A. This locale is used in deriving the requested locale. It is used when no locale can be found for your request, that is, the "locale" GET variable and web browser locales list are empty. The Default Locale is set to en_US by default. You can change this setting using either the OpenAM console or ssoadm:
- OpenAM console: navigate to: Configuration > Servers and Sites > Default Server Settings > 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.
Q. What is the platform locale?
A. The platform locale is defined by the JVM where OpenAM is running. By default, the JVM uses the system locale but you can also set up the JVM locale manually:
java -Duser.country=CA -Duser.language=fr ... com.x.MainOpenAM uses the platform locale when it cannot find files for the requested locale; it is important to test this use case when you are localizing files.
Note
The issue with setting the locale at the JVM level is that even technical elements (like stack traces) will be translated into the desired language, which is not very user friendly for our support team.
Q. How do I customize the Password Reset page?
A. You can customize the Password Reset page by editing the property values in the amPasswordReset.properties file.
This file is located inside the openam-core-12.0.x.jar (for OpenAM 12.0.x), which you can find in the WEB-INF/lib directory where OpenAM is installed. Extract a version of the amPasswordReset.properties file from openam-core-12.0.x.jar and copy it to the /path/to/tomcat/webapps/openam/WEB-INF/classes directory where OpenAM is deployed. You can then edit this file to customize the Password Reset page.
See OpenAM Administration Guide › Configuring User Self-Service Features › Resetting Forgotten Passwords (Legacy) for further information.
Note
The REST endpoint used by the legacy resetting a forgotten password feature is disabled by default in OpenAM 13.
Q. How do I change the password input from *** to plain text in the Login page?
A. You can change the password input by changing the following text in the Login.jsp page (located in the /path/to/tomcat/webapps/openam/config/auth/default directory where OpenAM is deployed):
<input class="textbox" type="password" name="...to:
<input class="textbox" type="text" name="...Note
You must restart the web application container in which OpenAM runs to apply these configuration changes.
Q. How do I translate an authentication module in OpenAM into a different language?
A. Translating an authentication module requires you to translate the UI folder files and the .properties files. These are located in the /path/to/tomcat/webapps/openam/WEB-INF/classes directory where OpenAM is deployed.
Note
An authentication module in OpenAM can have more than one .properties file and can also use .properties files from other modules. Therefore, if you are translating an authentication module, you may have to translate multiple .properties files to complete the translation.
Q. How does OpenAM choose which .properties file to use?
A. OpenAM determines the requested locale and then looks for the .properties file based on this locale. In this example, we will show how OpenAM looks for the amAuthUI.properties file with a requested locale of en_CA.
- OpenAM looks up the Java® classes path, which is:
- the /path/to/tomcat/webapps/openam/WEB-INF/classes/ directory where OpenAM is deployed.
- the /path/to/tomcat/webapps/openam/WEB-INF/lib/openam-core-xx.x.x.jar/ directory where OpenAM is deployed (for example, /path/to/tomcat/webapps/openam/WEB-INF/lib/openam-core-12.0.0.jar/ for OpenAM 12).
- OpenAM firstly looks for the file amAuthUI_en_CA.properties in the /path/to/tomcat/webapps/openam/WEB-INF/classes/ directory. If it can't find it in this directory, it will look in every jar file. If no file is found, OpenAM goes to the next step.
- OpenAM restarts step 2 with the file amAuthUI_en.properties. If no file is found, OpenAM goes to the next step.
- OpenAM restarts step 2 with the platform locale. If no file is found, OpenAM goes to the next step.
- OpenAM restarts step 2 with amAuthUI.properties. This file will always be found as it exists in the core module.
Q. How do I customize messages defined in the amAuthUI.properties file?
A. A lot of the messages displayed to users on .jsp files are defined in the amAuthUI.properties file.
The amAuthUI.properties file is located inside the openam-core-12.0.x.jar (for OpenAM 12.0.x), which you can find in the WEB-INF/lib directory where OpenAM is installed. Extract a version of the amAuthUI.properties file from openam-core-12.0.x.jar and copy it to the /path/to/tomcat/webapps/openam/WEB-INF/classes directory where OpenAM is deployed. You can then edit this file to customize any messages you require.
The .jsp files that have messages defined in the amAuthUI.properties file are detailed in OpenAM Reference › Service Endpoints › Default Authentication JSP Endpoints.
Note
Other .properties files, such as amConsole.properties, are also located in the openam-core-12.0.x.jar file (for OpenAM 12.0.x) and can be modified in the same way as described above.
Q. Can I reuse a customized .properties file from a previous release?
A. Yes you can. If you already have a customized .properties file (for example, amAuthUI.properties), you can copy this file into the WEB-INF/classes directory as this file will be used instead of the file found in the JAR as per the default classloading order.
Q. How can I customize pages such as the Login page for use on mobile devices?
A. ForgeRock does not currently have any specific guidelines or templates for modifying the CSS for limited screen resolution devices. You can customize pages for use on mobile devices using any responsive css framework to adapt the existing CSS.
Q. Can the platform locales be different on different servers running behind a load balancer?
A. No, you should ensure that the platform locales are the same on all servers running behind a load balancer. The platform locales could be different even if the OpenAM configuration is the same (by replication or by connecting the two OpenAM servers to one configuration store).
In the following example, there are two OpenAM servers; one with an English platform locale and the other one with a Spanish platform locale. Both English and Spanish translations exist.
When a user makes a request with a French request locale, OpenAM will read the platform locale in both cases since French isn't implemented. In one case, our user will see Spanish content, in the other one English. This situation can be avoided by setting the same platform locale in both environments.
Q. How do I remove attributes from the EndUser page?
A. The EndUser page displays attributes as defined in the amUser.xml services configuration in your configuration store. You can modify the amUser.xml file to remove attributes from the EndUser page as described in OpenAM Developer's Guide › Customizing Profile Attributes.
Caution
This schema affects the whole of the OpenAM console, not just the EndUser page; therefore, you should consider the impact of this before removing any attributes.
Q. How do I customize the EndUser page to make it display-only?
A. If your purpose for customizing the EndUser page is to show users their basic details without permitting changes, it is preferable to create a custom JSP page instead, which fetches the required attributes directly. You can then remove the EndUser page or prevent access to it (for example via your load balancer or reverse proxy).
For example, a simple custom JSP page (without any real error handling or styling) would look like this:
<%@ page import="com.iplanet.sso.*" %> <%@ page import="com.sun.identity.idm.AMIdentity" %> <%@ page contentType="text/html; charset=UTF-8" %> <% try { SSOTokenManager manager = SSOTokenManager.getInstance(); SSOToken ssoToken = manager.createSSOToken(request); // This will be your incoming user/token. AMIdentity user = new AMIdentity(ssoToken); out.println(user.getName()); // Note these are HashSets, since attributes can be multi-valued. out.println(user.getAttribute("telephonenumber")); out.println(user.getAttribute("cn")); out.println(user.getAttribute("mail")); } catch (SSOException e) { // If the user is not authenticated, redirect them to Login response.sendRedirect("UI/Login?goto=../showuser.jsp"); } %>Q. Can I add custom functionality to a page such as an additional check box?
A. You can extend the functionality of a page by adding your own JavaScript® providing it is well formed and properly encapsulated in <script> tags.
If you add JavaScript to call an object such as a check box, you must include this in the goto parameter that is appended to the URL. First you must URLdecode the goto parameter, then append your object name and finally re-encode the goto parameter for inclusion in the URL.