Configuring Identity Server to Use Custom Login Pages

You can configure Identity Server in two ways to use a custom login page. You can use properties or you can modify the main.jsp file. Select the method depending upon your modifications.

Use properties if you created your custom page from Access Manager 3.2 or later login.jsp page. See Using Properties to Specify the Login Page.
If you created your custom page from the nidp_legacy.jsp file, you cannot use properties to specify the main custom page for authentication. You must modify the main.jsp file. See Adding Logic to the main.jsp File.

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 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:

Create a method for a custom login page:
1. Click Devices > Identity Servers > Edit > Local > Methods.
2. Select one of the following actions:
  - If you have created a method for a Query property to be used with your custom login page, click the name of the method.
  - If you did not modify the credentials on the login page, click New, specify a display name, select a password class, and configure a user store.
3. In the Properties section, click New, then specify the following:
  
  Property Name: MainJSP
  
  Property Value: true
  
  This property indicates that you want to use a custom login page with this method. It also indicates that the custom login page contains the prompts for user credentials.
  
  Property names and values are case-sensitive.
4. Click OK.
5. (Conditional) If the Properties section does not contain a JSP property, click New, and specify the following values:
  
  Property Name: JSP
  
  Property Value: custom1
  
  The property value for the JSP property is the name of the custom login file without the JSP extension. Replace custom1 with the name of your custom login file. This property determines which login page is displayed when this method is used. The filename cannot contain nidp as part of its name.
6. Click OK.
  
  See Specifying Common Class Properties.
7. (Conditional) If you created multiple custom login pages, repeat Step 1.b through Step 1.e for each page.
For each method that you modified for a custom login page, create a contract.
1. Click Contracts > New.
2. Specify the details as per the needs of the resource, but ensure that to assign the custom method as the method for the contract.
3. Click Next, configure a card for the contract, and then click Finish.
Update Identity Server.
For each resource that you have created a custom login page, assign that resource to use the contract that is configured to display the appropriate login page.
1. Click Devices > Access Gateways > Edit > [Reverse Proxy Name] > [Proxy Service Name] > Protected Resources.
2. Select each protected resource for which you have created a custom contract, and then configure it to use the custom contract.
Update Access Gateway.
(Conditional) If the custom page is not displayed correctly, see Troubleshooting Tips for Custom Login Pages.

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:

You cannot rename the main.jsp file. Therefore, any modifications you make to this file can be lost whenever you upgrade Identity Server. During the upgrade, you must select to restore custom files or you must restore your modified file after the upgrade. If this is the only JSP file that you modified that uses an Identity Server name, it is recommended to manually restore this file after an upgrade.
Modifying the main.jsp file requires knowledge of JSP programming and if/else statements.

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

You can create multiple customized nidp_legacy.jsp pages. For example: custom1.jsp, custom2.jsp, and custom3.jsp.
You can create multiple customized login.jsp pages that request different login credentials. For example:

login1.jsp: Configured to request username and password.

login2.jsp: Configured to request username, email, and password.

login3.jsp: Configured to request email and password.

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.

Contract	Configuration Details
Contract1	URI	login1/custom1
	Method1	Configured with the following JSP property: Property Name: JSP Property Value: login1 This method does not need a query property unless you are using an attribute other than the cn attribute for the username.
Contract2	URI	login2/custom2
	Method2	Configured with the following two properties: Property Name: JSP Property Value: login2 Property Name: Query Property Value: (&(objectclass=person)(mail=%Ecom_User_ID%)))
Contract3	URI	login3/custom3
	Method3	Configured with the following two properties: Property Name: JSP Property Value: login3 Property Name: Query Property Value: (&(objectclass=person)(mail=%Ecom_User_ID%))

Perform the following steps to configure Access Manager to display these custom login pages with custom credentials:

Create a unique method for each custom login.jps file:
1. Click Devices > Identity Servers > Edit > Local > Methods > New.
2. Specify the following details:
  
  Display name: Specify a name for the method. Use a name that indicates which login page is assigned to this method.
  
  Class: Select a name/password class.
  
  Configure the other fields to match your requirements.
3. In the Properties section, add a Query property if the page uses custom credentials.
  
  For example, to add an email address to the login prompts, add the following property:
  
  Property Name: Query
  
  Property Value: (&(objectclass=person)(mail=%Ecom_User_ID%))
  
  If you are creating a method for Contract 1 in the previous example (which prompts for a username and password), you do not need to add a query property unless you are using an attribute other than the cn attribute for the username.
4. In the Properties section, add a JSP property to specify which login.jsp file to use with this method.
  
  For example:
  
  Property Name: JSP
  
  Property Value: login2
5. Click Finish.
6. If you have created more than one custom login.jsp files, repeat Step 1.b through Step 1.e for each page.
  
  To configure the scenario described in this section, repeat these steps for three login pages.
Create a unique contract URI.
1. Click Contracts > New.
2. Specify the following details:
  
  Display name: Specify a name for the contract. Use a name that indicates which login page is assigned to this contract.
  
  URI: Specify a value that uniquely identifies the contract from all other contracts. Spaces are not allowed. Use a name that indicates the custom login page and custom credential page, such as login1/custom1.
  
  Methods and Available Methods: Select the authentication method you configured in Step 1.
3. Configure the other fields to meet your network requirements, and then click Next.
4. Configure the authentication card, and then click Finish.
5. (Conditional) If you have created multiple custom login pages, repeat Step 2.b to Step 2.d for each page.
  
  To configure the scenario described in this section, repeat these steps for /login2/custom2 and /login3/custom3.
6. Click OK, and then update Identity Server.

Modify main.jsp to add the following line near the top of the file:

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

String strContractURI = hand.getContractURI();

This sets the strContractURI variable to the value of the contract URI that is being used for authentication. These lines must look similar to the following:

<%
    ContentHandler hand = new ContentHandler(request,response);
    String strContractURI = hand.getContractURI();

    // Is there a JSP defined on a class definition or a method 
    // definition that must be displayed as the main jsp here?
    if (handler.contractDefinesMainJSP())
    {
%>

After the if statement, add an else if statement for each contract URI you have created. For example:

<% }
else if(strContractURI != null && strContractURI.equals("login1/custom1"))
    {
%>
     <%@ include file="custom1.jsp" %>

<%  }
else if(strContractURI != null && strContractURI.equals("login2/custom2"))
    {
%>
        <%@ include file="custom2.jsp" %>

<% }
else if(strContractURI != null && strContractURI.equals("login3/custom3"))
    {
%>
        <%@ include file="custom3.jsp" %>

These else if statements set up three contracts for customized login pages:

The first else if statement specifies the URI of the login1 contract and configures it to display the custom1.jsp page for authentication.
The second else if statement specifies the URI of the login2 contract and configures it to display the custom2.jsp page for authentication.
The third else if statement specifies the URI of the login3 contract and configures it to display the custom3.jsp page for authentication.

Your file must look similar to the following:

<%@ page language="java" %>
<%@ page pageEncoding="UTF-8" contentType="text/html; charset=UTF-8"%>
<%@ page import="com.novell.nidp.*" %>
<%@ page import="com.novell.nidp.resource.jsp.*" %>
<%@ page import="com.novell.nidp.ui.*" %>
<%@ page import="com.novell.nidp.common.util.*" %>
<%@ page import="com.novell.nidp.liberty.wsf.idsis.apservice.schema.*" %>

<%
    ContentHandler hand = new ContentHandler(request,response);
    String strContractURI = hand.getContractURI();

    // Is there a JSP defined on a class definition 
    // or a method definition that must be displayed 
    // as the main jsp here?
    if (hand.contractDefinesMainJSP())
    {
%>
        <%@ include file="mainRedirect.jsp" %>
<%  }
    else if(strContractURI != null && strContractURI.equals("login1/custom1"))
    {
%>
     <%@ include file="custom1.jsp" %>

<%  }
else if(strContractURI != null && strContractURI.equals("login2/custom2"))
    {
%>
        <%@ include file="custom2.jsp" %>

else if(strContractURI != null && strContractURI.equals("login3/custom3"))
    {
%>
        <%@ include file="custom3.jsp" %>

<%  }    // This is the jsp used by default
    else
    {
%>
        <%@ include file="nidp.jsp" %>
<%  }  %>

Back up your customized files.
For each resource for which you created a custom login page, assign that resource to use the contract that is configured to display the appropriate login page.
1. Click Devices > Access Gateways > Edit > [Reverse Proxy Name] > [Proxy Service Name] > Protected Resources.
2. For each protected resource that you have created a custom contract for, select the protected resource, then configure it to use the custom contract.
3. Update Access Gateway.
(Conditional) If the custom page is not displayed correctly, see Troubleshooting Tips for Custom Login Pages.