3.1.3 Customizing Identity Server

Detecting for JavaScript

The nidp_latest.jsp implementation includes the empty DOM element:

<div id="runningInEndUserLoginEnvironment" style="display: none"></div>

JSP JavaScript code can query for the existence of this DOM element. If it exists it can be assumed that the JSP is running inside of the nidp_latest.jsp environment.

var proofOfEndUserEnvironment=
  document.getElementById('runningInEndUserLoginEnvironment');

Detecting for Java

The JavaScript function getToContent(strUrl strTargetDivId) adds an HTTP request parameter that names the identifier of the <div> element that is the target of the request.

strUrl = updateQueryString(
"<%=NIDPConstants.HTTP_REQUEST_PARAM_NAME_UIDESTINATION%>", "<%=NIDPConstants.HTTP_REQUEST_PARAM_NAME_UIDESTINATION_VALUE_CONTENTDIV%>",
strUrl);

The JSP Java code runs on the server and the request is the JQuery AJAX HTTP Get request sent by getToContent(). Therefore, the Java code can query the existence and value of the NIDPConstants.HTTP_REQUEST_PARAM_NAME_UIDESTINATION request parameter. If it exists, the Java code can determine the target <div> element and know that the current request is an AJAX request produced by getToContent().

String strUIDestinationId =
  (String) request.getParameter(NIDPConstants.HTTP_REQUEST_PARAM_NAME_UIDESTINATION);
if (!StringUtil.isDefined(strUIDestinationId) ||            (!strUIDestinationId.equals(NIDPConstants.HTTP_REQUEST_PARAM_NAME_UIDESTINATION_VALUE_CONTENTDIV)))
{
  bProofOfEndUserEnvironment = false;
}

Customizing the Page Title

Perform the following steps to customize the page title of the User Portal:

Customizing the Default Login Page to Prompt for Different Credentials

This section explains how to prompt the users for an identifier other than the user’s name. Figure 3-1 displays the default login page with the username prompt.

Figure 3-1 Modifying the Credential Prompts

This section explains only how to modify the content of the login_latest.jsp file. If you want to modify other aspects of this page, you need to select one of the other methods.

The instructions explain how to create a method that sets up the appropriate query so that the user can be found in the user store with an identifier other than the username (the cn attribute). The instructions also explain how to create a contract that uses this method and how to modify the login_latest.jsp page so that it prompts for the appropriate identifier such as an email address instead of a username.

Modifying the login.jsp File

The login.jsp file gives you the credential frame with the login prompts in an iframe. It has no branding header. If you use this page, you need to write the HTML code for the header and the branding.

Customizing JSP Files

Three general types of customizable UI files are associated with Identity Server: JSP files, CSS files, and JavaScript (JS) files. To obtain an initial working set of these files for customization, perform the following steps:

Authentication Method (cards) to be Displayed

The term card refers to Authentication Card in Administration Console. When editing Identity Server in Administration Console, an authentication is comprised of an Authentication Contract that contains one or more authentication methods and each Authentication Method references to an Authentication Class.

To make an Authentication Contract visible in the user interface, an Authentication Card is associated with Authentication Contract. Authentication Card displays an icon and a name to the end user for a defined Authentication Contract.

The nidp_latest.jsp implementation queries Identity Server to gather the following Authentication Card information:

The Java variable showCards is used for indicating if the drop-down hamburger menu should be shown. It is initialized to true and the situations that would make it false are tested.

The drop-down hamburger menu is not shown in the following scenarios:

The drop-down hamburger menu is divided into local, remote, and federated authentication sections.

A local login is an authentication that Identity Server can use without involving an external identity provider. LDAP and JDBC logins are examples of local logins. In these cases, Identity Server locally logs into a local directory or a database to authenticate an end user.

A social media authentication, such as Facebook or Twitter login, is a remote authentication.

A login at a federated external identity provider (often using a protocol, such as SAML) is an example of federated login.

The implementation examines each Authentication Card and sorts them into these three categories. The drop-down hamburger menu is populated with federated cards, followed by remote cards, and then local cards.

The URL to be Used for Populating the Content Area

The goal of the nidp_latest.jsp implementation is to display the current activity to the end user. The current activity can be an authentication, a confirmation, or a user message. This activity is loaded into the <div id="<%=NIDP_JSP_CONTENT_DIV_ID%>">…</div> area using a JQuery AJAX HTTP call to Identity Server. The HTML returned from this request is “set” into the content div.

To go to the correct activity, nidp_latest.jsp must build the correct URL for the call to getToContent(strUrl, strTargetDivId) JavaScript Function.

GenericURI builderContentDivUrl = 
new GenericURI(handler.getJSP(handler.isJSPMsg() ?
handler.getJSPMessage().getJSP() :
NIDPConstants.JSP_CONTENT));

A GenericURI Java object wraps a standard URI allowing easier creation and editing of URLs.

If Identity Server specifically indicates that a particular JSP must be displayed by returning true from handler.isJSPMsg(), then that JSP name is used to build the URL. Otherwise, the system JSP content_latest.jsp is used.

The handler.getJSP() method creates a URL formatted similar to the following:

[IDP domain]:[IDP port]/nidp/jsp/[JSP Name].jsp?sid=[session data id]

The query string parameters from the current HTTP request (the request that invoked nidp_latest.jsp) are copied to the content <div> url, then the current Authentication Card identifier is added to the query string.

builderContentDivUrl.setQueryItem(ContentHandler.CARD_PARM,
currentAuthCard.getID(true));

This ensures that the identity provider is executing the correct authentication method.

Lastly, the JavaScript getToContent() function is called to invoke the JQuery AJAX HTTP call:

getToContent('<%=strContentDivUrl%>', '<%=NIDP_JSP_CONTENT_DIV_ID%>');

The Message to be Displayed

All user messages are displayed in the Global Message Area.

The Global Message Area is the layout section of nidp_latest.jsp that gets data from the <divid="globalMessage"> element.

A user message can be displayed as a prompt that correlates with the current activity that is executing in the content div area. For example, Authentication Failed: Invalid Credentials can be displayed during a Name / Password login while the content <div> refreshes the login form.

A user message can also be displayed when the Content Area is empty. This situation arises when the user message is terminal in nature to the previously executed Content Area activity. For example, when an error occurs during an X509 Mutual Certificate Authentication, the message, Error occurred during User Certificate Authentication. Please contact Administrator is displayed in the Global Message Area and the Content Area will be empty.

In the nidp_latest.jsp implementation, many Identity Server conditions are verified that can lead to setting a value for the Global Message Area. The value is set using code similar to the following:

strGlobalMessageText =
    handler.getResource(JSPResDesc.LOGOUT_SUCCESS_MSG);

The messages that cause the Content Area to be empty are those that are queried from Identity Server.

NIDPMessage msg = handler.getMessage(true);

If the message is an error message, then it is displayed in the Global Message Area and the getToContent() JavaScript function is not called to populate the Content Area. This mechanism uses the message_latest.jsp file to set the Global Message Area value.

The following sections explain how to modify the login page that the JSP files create:

Rebranding the Header

Customizing the Card Display

To control what appears in the Authentication Cards section, use the Show Card option that appears on the definition of each card. If this option is not selected, the card does not appear in the Authentication Cards section. Each contract has an associated card. For information about modifying the card options, see Section 4.1.4, Configuring Authentication Contracts.

Perform one of the following tasks:

Customizing the Credential Frame

You can modify login.jsp to prompt users for an identifier other than the username. To do this, you need to create a method that sets up the appropriate query to find the user in the user store with an identifier other than the username. Then create a contract that uses this method. You also need to modify the prompt in login.jsp to match the identifier you are prompting for.

Customizing the nidp.jsp File to Customize Error Message

Identity Server publishes a generic error message for the error code during SAML failure, such as request denied or Invalid Name ID Policy. You can customize the NIDP jsp file available at /opt/novell/nids/lib/webapp/jsp and write an appropriate error message for redirection or to inform the user about the issue.

In the following example, the specified code snippet is for simulating InvalidNameIDPolicy error for SAML 2.0.

Perform the following steps to customize error message:

Using Properties to Specify the Login Page

For each resource that needs a unique login page, you need to create an authentication method and add the JSP and MainJSP properties to the method. You then need to create a contract for each method.

The following steps assume that the custom login page is called custom1.jsp:

Adding Logic to the main.jsp File

You can modify the main.jsp file and use the contract URI to specify the login page to display.

Consider the following points:

Modifying the main.jsp file enables you to perform the following actions:

With this type of configuration, you must create three different authentication contracts with an authentication method with a JSP property defined for each of them. These contracts require the types of values listed in the following table. The URI is defined so that it reflects the custom login.jsp and the custom nidp_legacy.jps that are used by the contract.

The following procedure explains how to configure Access Manager to display these custom login pages with custom credentials:

Customizing the Titles

The window title appears in the browser title bar. To replace this text, open the err_latest.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_latest.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>.