Customizing the nidp_latest.jsp file

The nidp_latest.jsp file provides the default layout for Identity Server authentication pages. This section provides the details of the concepts that the implementation addresses to populate the different layout components on the page. With this understanding, a developer can identify sections of the implementation that address each concept.

The following are main concepts throughout the nidp_latest.jsp implementation:

Authentication methods (cards) to be displayed
URL to be used for populating the Content Area (<div id="theNidpContent">)
The end user messages to be displayed

You can query Identity Server to get the required data. The access point into Identity Server internal data structures is the ContentHandler Java class.

The following line, found at the top of nidp_latest.jsp, represents a new ContentHandler and initializes it for the current HTTP request and response:

ContentHandler handler = new ContentHandler(request,response);

NOTE:The handler variable is used throughout the Identity Server code.

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 set of all available Authentication Cards.

This query is used for populating the drop-down hamburger menu where the user can choose from the available authentications.
The set of authentications already completed by the current user.

This query is used for placing a check mark next to the completed authentications in the drop-down hamburger menu.
The authentication that is currently executing.

This query is required to display the current authentication in the content section of the UI.

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:

No Authentication Cards.
Only one Authentication Card, and that card is the current Authentication Card.
An error message is displayed.
The logout confirmation page is displayed.
The page is being rendered for a Mobile application.

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.

NOTE:The nidp_latest.jsp implementation includes a JavaScript function with signature getToContent(strUrl, strTargetDivId) that makes a JQuery AJAX HTTP Get request to the URL supplied in the parameter strUrl, and then writes the returned HTML to the <div> element identified by the parameter strTargetDivId.

The content_latest.jsp implementation also uses this JavaScript function for the same purpose.

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

Navigate to Administration Console Dashboard > Branding.
Select the required Identity Server cluster.
Modify Title as per requirement.
Modify the background color using Left Background Color and Right Background Color.
Click Change Image to replace the NetIQ logo on the right of the header.
Continue with one of the following tasks:
- Modify the credential frame. See Customizing the Credential Frame.
- Control the cards displayed in the Authentication Cards section. See Customizing the Card Display.
- Configure Identity Server to use custom pages. See Adding Logic to the main.jsp File.
- View a sample custom page with these modifications. See Examples for Customizing the User Portal Page Using Configuration Files.

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 5.1.4, Configuring Authentication Contracts.

Perform one of the following tasks:

To modify what appears in the credential frame, continue with Customizing the Credential Frame.
To configure Identity Server to use your custom pages, see Adding Logic to the main.jsp File.

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.

Create a method with the appropriate query:

Click Devices > Identity Servers > Edit > Local > Methods.
Click New, and then specify a Display Name.
Select a class that is a username/password class from the list.
Keep Identifies User selected, and configure the user store option according to your needs.

In the Properties section, click New, and set the following properties:

Property Name	Property Value
Query	(&(objectclass=person)(mail=%Ecom_User_ID%)) This property is defined to query the user store for the attribute you want to use rather than the cn attribute (in this case, the mail attribute of the person class). Change mail to the name of the attribute in your user store that you want to use for the user identifier. The %Ecom_User_ID% variable is the default variable name on the login page. You can change this to something similar to %EMail_Address% if you also change the value in your custom login page. For more information about how to use this property, see Query Property.
JSP	<filename> Replace <filename> with the name of the custom login.jsp page you are going to create, so that the page prompts the user for an e-mail address rather than a username. This must be the filename without the JSP extension. For example, if the name of your file is email_login.jsp, then specify email_login for the property value.

Property Name

Property Value

Query

(&(objectclass=person)(mail=%Ecom_User_ID%))

This property is defined to query the user store for the attribute you want to use rather than the cn attribute (in this case, the mail attribute of the person class). Change mail to the name of the attribute in your user store that you want to use for the user identifier.

The %Ecom_User_ID% variable is the default variable name on the login page. You can change this to something similar to %EMail_Address% if you also change the value in your custom login page.

For more information about how to use this property, see Query Property.

JSP

Replace <filename> with the name of the custom login.jsp page you are going to create, so that the page prompts the user for an e-mail address rather than a username. This must be the filename without the JSP extension. For example, if the name of your file is email_login.jsp, then specify email_login for the property value.

Click OK.

Create a contract that uses this method:
1. Click Contracts > New.
2. Select the method you just created.
3. Configure the other options to fit your requirements.
  
  If you are creating multiple custom login pages with customized credentials, you might want to use the URI to hint at which custom login.jsp file is used with which custom nidp_latest.jsp file. For example, the following URI values have the filename of the login page followed by the name of the custom nidp_latest.jsp page:
```
login1/custom1
login2/custom2
login3/custom3
```
  See Section 5.1.4, Configuring Authentication Contracts.
4. Update Identity Server.
Modify the login.jsp file.
1. (Conditional) If you modified the %Ecom_User_ID% variable, find the string in the file and replace it with your variable.
2. (Conditional) If you need to support only one language, modify the prompt as follows:
  1. Locate the following string in the file:
    <label><%=handler.getResource(JSPResDesc.USERNAME)%></label>
  2. Replace it with the string you want. For example, <label>Email Address:</label>
For information about how to modify a file, see Modifying Configurations.
(Conditional) If you need to localize the prompt for multiple languages, create a custom message properties file for the login prompt. See To Customize Identity Server Messages.
1. Add the following definition t your custom file to prompt the user for an e-mail address:
```
JSP.50=Email Address:
```
2. Translate the value and add this entry to your localized custom properties files.
3. Add the custom properties files to the /opt/novell/nam/idp/webapps/nidp/WEB-INF/classes folder of the appropriate Identity Server cluster using Advanced File Configurator. For more information, see Adding Configurations to a Cluster.
To specify which customized nidp_latest.jsp to display with the contract, you must modify the main.jsp file. Continue with Adding Logic to the main.jsp File.

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 nidp JSP file 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 the InvalidNameIDPolicy error for SAML 2.0.

Perform the following steps to customize error message:

Generate an error condition with, for example, Invalid Name ID Policy.

In the nidp_latest.jsp file, add the following code for redirection:

com.novell.nidp.ui.MenuHandler redirectMenuHandler;
        com.novell.nidp.NIDPMessage redirectMessage;
    String redirectCause;

        redirectMenuHandler = new MenuHandler(request, response);
        redirectMessage = redirectMenuHandler.getMessage(true);
        if (redirectMessage != null && redirectMessage instanceof
com.novell.nidp.NIDPError) {
        redirectCause = ((com.novell.nidp.NIDPError)
redirectMessage).getNIDPExceptionMsg();
        System.out.println("************** redirectCause" + redirectCause);
        if (redirectCause != null && 
redirectCause.indexOf("InvalidNameIDPolicy") != -1) {
        response.sendRedirect("http://www.novell.com"); 
            return;
       }
    }

For information about how to modify a file, see Modifying Configurations.

Verify that when failure occurs, SAML shows the following message in the authentication response:

<samlp:Status><samlp:StatusCode
Value="urn:oasis:names:tc:SAML:2.0:status:Responder"><samlp:StatusCode
Value="urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy"/></samlp:StatusCode>

Due to the customized nidp_latest.jsp file, SAML redirects to the specified location.

Rerun the failure and verify that instead of displaying 300101008, the nidp page redirects to the specified www.novell.com location.