If you have customized the .jsp files for Access Gateway, you must perform the following steps to maintain the customized files before upgrading Access Manager. If you do not, Access Manager overwrites the customized .jsp files. For more information, see Maintaining Customized JSP Files for Access Gateway in the NetIQ Access Manager 4.5 Installation and Upgrade Guide.
Access Gateway uses the custom error page template to rebrand and localize the language of error pages that are published to the browser.
By default, Access Gateway contains the following files to help customize and localize the error messages:
The error page configuration file, ErrorPagesConfig.xml
The error messages file, ErrorMessages.xml.en
NOTE:If you are modifying any of the these files, ensure that you retain the original filenames.
Access Gateway maintains /opt/novell/nam/mag/webapps/agm/WEB-INF/config/current/ directory to save files that are used for error page configuration.
You can customize and localize the error template and the error messages:
When Access Gateway serves an error message to the browser by using the Accept-Language header value received from the browser, it selects a suitable error template and an error message file. To localize the error messages, you must to do the following:
Localize or customize the error messages in the ErrorPagesConfig.xml file and save it with the language extension.
The error messages contained in the ErrorMessages.xml.en file can be localized in various languages and stored as ErrorMessages.xml.<lang>, where <lang> is the fileXn attribute value. You can also customize the English error messages present in the ErrorMessages.xml.en file.
NOTE:You cannot customize an error message that is not available in ErrorMessages.xml.en.
To localize the error messages, perform the following steps:
Log in as root.
Open the ErrorMessages.xml.<lang> file.
Copy the error messages that you have localized or customized to within the <TranslatedMessage></TranslatedMessage> tags. For example:
</Message>
<Message id="<ID No>" name="<ERROR_MESSAGE_NAME>" enable="yes">
<EnglishMessage>English Message goes here</EnglishMessage>
<TranslatedMessage>
Localized message goes here
</TranslatedMessage>
</Message>
Do not delete the contents within the <TranslatedMessage></TranslatedMessage> tags from an English file because, the ErrorPagesConfig.xml file selects the error message within these tags for display.
Save the file.
If Access Gateway belongs to a cluster, copy the modified file to each member of the cluster, then restart that member.
Edit the configuration and make dummy changes and push the configuration.
Access Gateway uses the Apache method for localizing error messages. You can modify these messages or customize the page they are displayed on.
To change a message:
Change to the Apache message configuration directory:
Linux: /etc/opt/novell/apache2/conf/extra
Windows: \Program Files\Novell\apache\conf\extra
Open the http-multilang-errordoc.conf file.
The first few lines of this file contains comments on how Apache recommends modifying the error messages. You can select to use their method or continue with the following steps.
Locate the ErrorDocument section and determine the error code message you want to modify. Make note of the *.var filename.
Change to the Apache error directory:
Linux: /opt/novell/apache2/share/apache2/error
Windows: \Program Files\Novell\apache\error
Open the *.var file that you want to modify.
The message is listed alphabetically by language code.
Save the changes.
To change the header of the error page:
Change to the Apache error include directory:
Linux: /opt/novell/apache2/share/apache2/error/include
Windows: \Program Files\Novell\apache\error\include
Open the top.html page.
To change the title of the page, locate the following line:
<title>Access Gateway<\title>
Replace the Access Gateway string with the content you require.
To replace the image in the header, locate the following line:
<img src="/NAGErrors/images/header_550.png" alt="" height="50px" width="550px" border="0">
Replace header_550.png with the filename of the image you want to display.
Adjust the height and width values to match your image.
Save the file.
Copy your image to the images directory:
Linux: /opt/novell/apache2/share/apache2/error/images
Windows: \Program Files\Novell\apache\error\images
To change the footer of the error page:
Change to the Apache error include directory:
Linux: /opt/novell/apache2/share/apache2/error/include
Windows: \Program Files\Novell\apache\error\include
Open the bottom.html page.
To change the image, find the following line:
<td style="background-color: #E6D88C; padding-left: 10px"><img style="padding-right: 200px" src="/NAGErrors/images/LAP_interoperable_logo_100.gif" align="absmiddle" border="0">
Change LAP_interoperable_logo_100.gif to the filename of the image you want to display.
Save the file.
Copy your image to the images directory:
Linux: /opt/novell/apache2/share/apache2/error/images
Windows: \Program Files\Novell\apache\error\images
Copy all modified files and image files to all Access Gateways in the cluster.
The err_legacy.jsp file will also log the ESP error messages. For more information about customizing the err_legacy.jsp page, see Customizing Identity Server Messages. The procedure for customizing is the same except the paths for Access Gateway. The following are the path changes:
In Customizing Identity Server Messages, the paths for Access Gateway are as follows:
In Customizing the Branding of the Error Page, the path for err_legacy.jsp in the ESP on Linux is /opt/novell/nam/mag/webapps/nesp/jsp and on Windows is /Program Files/Novell/Tomcat/webapps/nesp/jsp/.
If any of your protected resources have a logout page or button, you need to redirect the user’s logout request to Access Gateway logout page. Access Gateway can then clear the user’s session and log the user out of any other resources that have been enabled for single sign-on. If you do not redirect the user’s logout request, the user is logged out of one resource, but the user’s session remains active until inactivity closes the session. If the user accesses the resource again before the session is closed, single sign-on reauthenticates the user to the resource, and it appears that the logout did nothing.
Click Devices > Access Gateways > Edit > Reverse Proxy / Authentication.
In the Embedded Service Provider section, view the path to the AGLogout page in the Logout URL option.
The Logout URL displays the URL that you need to use for logging users out of protected resources. This option is not displayed until you have created at least one reverse proxy with a proxy service. If you create two or more reverse proxies, you can select which one is used for authentication, and the logout URL changes to match the assigned reverse proxy. For more information about how to change the authentication proxy, see Changing the Authentication Proxy Service.
Redirect application logout requests to the AGLogout page.
Click OK.
Access Gateway does not support the following logout pages that were used in previous version of Access Manager and iChain:
/cmd/BM-Logout
/cmd/ICSLogout
You can create your own logout page and configure Access Gateway to use it. To do this, you need to modify the logoutSuccess_legacy.jsp file on Access Gateway. It is located in the following directory:
Linux: /opt/novell/nesp/lib/webapp/jsp
Windows: \Program Files\Novell\Tomcat\webapp\nesp\jsp
You can modify the file to display what you want or you can modify it to redirect the user to your custom page. The following sections provide some tips for accomplishing this task:
The logoutSuccess_legacy.jsp file is called in a frame from the nidp_legacy.jsp file. The branding in the header of the logout page is controlled by the branding of the nidp.jsp file. For information about how to modify nidp_legacy.jsp for logos, titles, and colors, see Rebranding the Header.
IMPORTANT:Take a backup of nidp_legacy.jsp file before modifications. Every time you upgrade your Access Gateway, upgrade process overrides any custom changes made to JSP files that use the same filename as those included with the product. If you want the modified file, you need to restore the nidp_legacy.jsp file. During an upgrade, you can select to restore custom login pages, but NetIQ still recommends that you have your own backup of any customized files.
One way to provide redirection is to replace the information in the <body> element of the logoutSuccess_legacy.jsp file with something similar to the following:
<body>
<script language="JavaScript">
top.location.href='http://<hostname/path>';
</script>
</body>
Replace the <hostname/path> string with the location of your customized logout page.
IMPORTANT:Take a backup of logoutSuccess_legacy.jsp file before modifications. Every time you upgrade your Access Gateway, upgrade process overrides any custom changes made to JSP files that use the same filename as those included with the product. If you want the modified file, you need to restore the nidp_legacy.jsp file. During an upgrade, you can select to restore custom login pages, but NetIQ still recommends that you have your own backup of any customized files
If you need to use a different logout page for specific protected resources, you need to modify the logout button of the applications to use the AGLogout URL rather than the plogout URL (see Customizing Applications to Use Access Gateway Logout Page). The AGLogout page redirects to the plogout page, which calls the logoutSuccess_legacy.jsp. Any parameter added to the AGLogout or plogout URL is saved and passed to the logoutSuccess_legacy.jsp file.
The parameter passed to the logoutSuccess_legacy.jsp file can be used with if/else logic in the body of the page to load different custom logout pages based on the parameter value.
To use the plogout URL, you need to modify the application’s logout button to call the following URL:
<ESP Domain>/nesp/app/plogout
Replace <ESP Domain> with the same value as the AGLogout value. For example, suppose your AGLogout value is the following:
https://jwilson1.provo.novell.com:443/AGLogout
You would replace it with the following value:
https://jwilson1.provo.novell.com:443/nesp/app/plogout
If you add a parameter to the URL, it would look similar to the following:
https://jwilson1.provo.novell.com:443/nesp/app/plogout?app=email
When you have both Liberty and SAML 2.0 sessions running on Identity Server and you log out of Access Gateway, the logoutSuccess_legacy.jsp page is not executed with the customizations you have made to the logout page. You will be able to log out of Access Gateway but the customizations you made are lost.
If the logutSuccess_legacy.jsp file is not loaded in a frame, the banner will not be displayed, and Access Gateway will comment out the content in the logoutSuccess_legacy.jsp file. Add the below line after the <body> tag in the logoutSuccess_legacy.jsp file.
<!-- BANNER LOADS IF THIS PAGE IS NOT LOADED IN REGULAR FRAME -->
<%@include file="logoutHeader.jsp"%>
When a user clicks the logout button and the user is logging out of an Access Gateway that is a member of a cluster, the user is not immediately disconnected from the resource. The logout message must be sent to each member of the cluster. The default interval for checking the pending logout message queue is 30 seconds. If this interval is too long, you can configure a shorter interval in the web.xml file of the Embedded Service Provider. This must be set on each Access Gateway in the cluster.
Log in to Access Gateway as the root or administrator user.
Open web.xml.
Linux: /opt/novell/nesp/lib/webapps/WEB-INF/web.xml
Windows: /Program Files/Novell/nesp/lib/webapps/WEB-INF/web.xml
Find the <context-param> section in the file.
Add the following parameter to the <context-param> section.
<context-param>
<param-name>logoutRetirementFrequency</param-name>
<param-value>15000</param-value>
</context-param>Set the <param-value> element to a value between 5000 and 30000 milliseconds (5 seconds and 30 seconds).
Restart the Embedded Service Provider.
For information about how to restart the Embedded Service Provider from Administration Console, see Section 3.2.3, Managing Access Gateways Settings.