Tuesday, 31 January 2012

Customizing OpenAM pages

First, take a look at official WIKI page and documentation. Information there is pretty vague, but at least gives some hints. In the rest of this article I'll try to fill in some gaps.
I had to modify default login, logout and error pages for root realm. Although official documentation suggests not to modify default pages, but that was the solution that worked for me. I modified following pages in config/auth/default/ folder under OpenAM web context:
  • login_failed_template.jsp - displayed after unsuccessful login - usually because of invalid username/password
  • Login.jsp - login form
  • Logout.jsp - showed after user hits "logout" and terminates his SSO session
  • session_timeout.jsp - showed if user's session timed out due to inacitivty
The trick is to leave ALL jato:* elements in place. You can delete all tables, rows, replace them with DIVs, add additional DIV elements, etc, but JATO's must be left intact. I couldn't find a good documentation about that framework, hence all you can do is follow your intuition and find out the correct page structure using good old trial and error method.
In order to add additional localization (e.g. 'lv'):
  • Create new directory:
    mkdir /config/auth/default_lv
  • Copy the file that JATO uses for form i18n:
    cp /config/auth/default_en/DataStore.xml /config/auth/default_en/
  • Copy the file that contains all messages used int authentication views:
    cp WEB-INF/classes/amAuthUI.properties WEB-INF/classes/amAuthUI_lv.properties
  • ... translate copied files
None of *.jsp file changes require server restart since servlet container can pick up changes dynamically (at least Tomcat can), but .properties file changes won't be reflected until web context or server is restarted.
One more thing - you can change selected locale. If you want to provide users with an ability to switch between locales (override locale detected by browser request), you must specify a 'locale' request parameter (this one I had to dig out from source code). And in order to pass it to latter pages (not to lose it after unsuccessful login attempts), in the form at the end of Login.jsp add:
<input type="hidden" name="locale" value="<%=request.getParameter("locale")%>" />


  1. The WIKI link seems to be broken. Other wise great article!

    1. Fixed that... a year after your notice :) Tanks for pointing out the problem. I really appreciate it.

  2. Simple and small article !! Helped me in basic understanding. Thanks