2.3 Customizing Identity Server Messages

2.3.1 Customizing Messages

  1. To customize the error pages, determine whether you need one custom file or multiple files:

    • If you do not need to support multiple languages, you can create one custom file for all your customized messages.

    • If you need to support multiple languages, you need to create a custom file for each language you want to customize.

  2. Create the custom properties file and name it:

    To support one language, name the file nidp_custom_resources.properties.

    To support multiple languages, create a nidp_custom_resources.<le_cy>.properties file for each supported language. Replace <le_cy> with the standard convention for Java Resource Bundles for the language or the language and country. For example:

    nidp_custom_resources_en_US.properties
    nidp_custom_resources_fr.properties
    nidp_custom_resources_es.properties
    

    If you want to support a custom messages for a language and a country and for just the language, you must create two files. For example:

    nidp_custom_resources_es_VE.properties
    nidp_custom_resources_es.properties
    
  3. Copy the nidp.jar file to a working area. This file is located in the following directory:

    Linux: /var/opt/novell/tomcat5/webapps/nidp/WEB-INF/lib

    Windows Server 2003: \Program Files\Novell\Tomcat\webapps\nidp\WEB-INF\lib

    Windows Server 2008: \Program Files (x86)\Novell\Tomcat\webapps\nidp\WEB-INF\lib

  4. Unzip the nidp.jar file in your working directory.

  5. In your working directory, locate the .properties files in the following directories.

    com/novell/nidp/resource/strings
    com/novell/nidp/resource/logging
    com/novell/nidp/resource/jsp
    com/novell/nidp/resource/jcc
    com/novell/nidp/resource/noxlate
    com/novell/nidp/liberty/wsf/idsis/ppservice/model
    com/novell/nidp/liberty/wsf/idsis/epservice/model
    com/novell/nidp/liberty/wsf/idsis/opservice/model
    com/novell/nidp/liberty/wsf/idsis/apservice/model
    com/novell/nidp/liberty/wsf/interaction
    com/novell/nidp/liberty/wsf/idsis/ssservice/model
    com/novell/nidp/servlets/handler/identityeditor
    com/novell/nidp/servlets/handler/identityaccesseditor
    com/novell/nidp/liberty/wsf/idsis/model
    com/novell/nidp/liberty/wsf/idsis/authority/ldap/attribute/plugins/resources
    com/novell/nidp/liberty/wsf/idsis/ldapservice/model
    

    The properties files that have been localized contain the messages that end users might see. The properties files that have not been localized contain messages that the end users should not see.

  6. Locate the messages you want to customize and copy them to your custom file.

    All the messages you want to customize are placed in this file, even though they come from different properties files. Your file should look similar to the following if you selected to customize messages from the nidp_resources_en_US.properties file and the SSModelResources_en_US.properties file. For example:

    NIDPMAIN.100=An Identity Provider response was received that failed to authenticate this session.
    NIDPMAIN.101=A request for identity federation could not be completed.
    NIDPMAIN.102=A request for identity federation termination could not be completed.
    
    SS.WKSLdapCreds = LDAP Credentials
    SS.WKSELdapCredsUserName = LDAP User Name
    SS.WKSELdapCredsUserDN = LDAP User DN
    SS.WKSELdapCredsUserPassword = LDAP Password
    SS.WKSX509Creds = X509 Credentials
    
  7. (Conditional) If you are supporting multiple languages, copy the messages to each custom language file.

  8. Replace the messages in the file with your custom messages.

    Replace the string after the equals (=) sign with your translated or customized message.

    If you are using double-byte characters, the characters need to be in Unicode, hexadecimal format with a \u prefix. For example: \u5c71.

  9. Save the file.

  10. Copy the custom properties file to the following directory on all Identity Servers in the cluster:

    Linux: /var/opt/novell/tomcat5/webapps/nidp/WEB-INF/classes

    Windows Server 2003: \Program Files\Novell\Tomcat\webapps\nidp\WEB-INF\classes

    Windows Server 2008: \Program Files (x86)\Novell\Tomcat\webapps\nidp\WEB-INF\classes

  11. (Optional) To enable messages about the loading of the custom properties files, enable debug logging:

    1. In the Administration Console, click Devices > Identity Servers > Edit > Logging.

    2. In the Component File Logger Levels section, select Debug level for Application.

    3. Click OK, then update the Identity Server.

  12. Restart Tomcat.

    • Linux Identity Server: Enter the following command:

      /etc/init.d/novell-tomcat5 restart

    • Windows Identity Server: Enter the following commands:

      net stop Tomcat5

      net start Tomcat5

  13. (Optional) To verify the loading of the custom properties files:

    1. View the log file by clicking Auditing > General Logging.

    2. Search for messages similar to the following in the catalina.out or stdout.log file:

      The named Custom Properties File was loaded and will be used:
      
      Custom Properties File successfully loaded! Name: <Custom Properties FileName> 
      
      An error occurred loading a specific Custom Properties File. Loading of other Custom Properties Files will continue.
      
      <Error Description>, Attempting to load Custom Properties File! Name: <Custom Properties FileName>
      
      The locale specifier in the Custom Properties File filename could not be successfully parsed into a valid locale. Loading of other Custom Properties Files will continue.
      
      Custom Properties File load failed. Could not determine correct locale! Name: <Custom Properties FileName>
      
      A general error occurred loading Custom Properties Files. Loading will stop and all un-loaded Custom Properties Files will not be loaded.
      
      <Error Description>, Attempting to load Custom Properties Files!
      

To create custom error pages for the Access Gateway, see Customizing Error Pages on the Access Gateway Appliance in the Novell Access Manager 3.1 SP2 Access Gateway Guide.

2.3.2 Customizing the Branding of the Error Page

The following page (err.jsp) is returned when the Identity Server encounters an error:

The file is located in the following directory.

Linux: /var/opt/novell/tomcat5/webapps/nidp/jsp

Windows Server 2003: \Program Files\Novell\Tomcat\webapps\nidp\jsp

Windows Server 2008: \Program Files (x86)\Novell\Tomcat\webapps\nidp\jsp

IMPORTANT:After you have customized this page, you need to ensure you back up this page before doing an upgrade. The upgrade process overrides any custom changes made to the err.jsp page.

For information on customizing the error message, see Section 2.3.1, Customizing Messages.

You can customize the following items:

Customizing the Titles

The window title appears in the browser title bar. To replace this text, open the err.jsp file and locate the following text that appears between the <head></head> tags:

<title><%=handler.getResource(JSPResDesc.TITLE)%></title>

Replace the content between the <title> and </title> tags with the title you want to appear. For example:

<title>My Company</title>

The display title is the title that appears in the top frame of the page. Locate the following text that appears in the <body> of the page:

<div id="title"><%=handler.getResource(JSPResDesc.PRODUCT)%></div>

Replace the content between the <div id="title"> and </div> with the title you want to appear. For example:

<div id="title">My Company</div>

Customizing the Images

To replace the header image, open the err.jsp file and locate the following text in the body of the file.

<div><img src="/nesp/images/AccessMan_Login_Head.png"></div>

Replace the value of the src attribute with the path and filename of the image you want to use.

To replace the Novell logo image, locate the following text in the body of the file.

<div id="logo"><img src="/nesp/images/AccessMan31_Nlogo.png"></div>

Replace the value of the src attribute with the path and filename of the image you want to use.

Customizing the Colors

To change the background colors on the page, modify the color values in the <style> section of the <head>.

2.3.3 Customizing Tooltip Text for Authentication Contracts

The strings that users see when they mouse over the cards for authentication contracts can be customized. If you need to support only one language, modify the text in the Administration Console.

  1. In the Administration Console, click Devices > Identity Servers > Edit > Local > Contracts.

  2. Click the name of a contract, then click Authentication Card.

  3. Replace the English text in the Text option with the required language, then click OK.

  4. Repeat Step 2 and Step 3 for each contract in the list.

  5. Click OK, then update the Identity Server.

If you need to support multiple languages, you need to localize the tooltips. The nidsCardText attribute of the nidsAuthLocalContract object needs to be changed to a resource ID. The following procedure explains how to do this in the Administration Console. You can also use an LDAP browser.

  1. In the Administration Console, click Devices > Identity Servers > Edit > Local > Contracts.

  2. Click the name of a contract, then click Authentication Card.

  3. Replace the text in the Text option with a resource ID.

    For example, replace Name/Password - Form with CUSTOM_NamePwdFormToolTip.

  4. Click OK.

  5. Repeat Step 2 through Step 4 for each contract in the list.

  6. Click OK, then update the Identity Server.

  7. Use custom string resource files to define the localized strings:

    1. Change to the WEB-INF/classes directory.

    2. For each supported language, create a properties file. For example:

      nidp_custom_resources_fr.properties
      nidp_custom_resources_es.properties
      

      If you have already created these files for custom messages (see Section 2.3.1, Customizing Messages), use the existing files.

    3. For each resource ID you have created, add an entry that contains the resource ID and the text you want displayed for that language. For example:

      CUSTOM_NamePwdFormToolTip=Forma de Nombre/Clave
      
    4. Repeat Step 7.c for each supported language file.

  8. Restart Tomcat.

    • Linux Identity Server: Enter the following command:

      /etc/init.d/novell-tomcat5 restart

    • Windows Identity Server: Enter the following commands:

      net stop Tomcat5 net start Tomcat5