Appboard/2.4/builder/system administration/login page/custom

Overview

This document provides some examples of modifying and producing completely custom login pages for AppBoard. For more general information about login pages and how to configure the system login page, refer to the Login Page documentation.

By default the different login page styles shipped with AppBoard are simple HTML forms that allow the user to enter the required information, and then POST it to the server so the server can authenticate and establish a session.

Typical customizations are:

• simply changing the logo graphic
• various styling changes (colours, fonts, etc...)
• addition of notices or terms & conditions
• hiding the Domain field for single-domain implementations
• making the Domain field a drop-down

Included Login Pages

The login pages shipped with AppBoard all follow the same structure. A main login.jsp Java Server Page which performs browser version checking, auto-fills previous values, handles error responses, presents a HTML form for the user to complete. Along with the JSP there will be other supporting images and CSS resources.

Browser Type Checking

If a client does not meed the minimum browser requirements the login page will redirect the client to /enportal/enPortalInvalidBrowser.jsp.

This works in three parts with the default login pages. The first is to load the Edge JspConfigBean:

<jsp:useBean id="JspConfigBean" scope="application" class="com.edgetech.util.config.JspConfig">
<% config.getServletContext().setAttribute("JspConfigBean", JspConfigBean); %>
</jsp:useBean>

Then the default minimum versions are retrieved by the JSP:

// get minimum versions from the Portal server
float minIEVersion = JspConfigBean.getMinIEVersion();
float minNetscapeVersion = JspConfigBean.getMinNetscapeVersion();
float minChromeVersion = JspConfigBean.getMinChromeVersion();

And finally a check is performed to determine whether to redirect:

if ( ! ((isChrome && version < <%=minChromeVersion%>) || (isNav && version < <%=minNetscapeVersion%>) || (isIE && version < <%=minIEVersion%>)) ) {
...
} else {
    // The user is trying to use an unsupported version of IE or netscape.
    rootWindow.location.replace("<%=JSPUtilities.out(URLUtil.getPortalContext(), true)%>/enPortalInvalidBrowser.jsp");
}

Depending on the deployment it may be useful to remove this check, or make this check more explicit due to standard operating environment and/or applications used within the organization.

Auto-fill User Name and Domain Fields

{{{1}}}

If a user has previously logged into AppBoard then it's possible for the server to retrieve the users User Name and Domain last used via cookies stored in the browser. This is implemented in the default JSP pages by first loading some utilities:

<%@ page import="com.edgetech.eportal.util.*" %>
<%@ page import="com.edgetech.eportal.dispatch.DispatchUtilities" %>
<%@ page import="com.edgetech.eportal.web.JSPUtilities" %>

Then doing some lookups and setting default values for the user and domain:

// Lookup the UserID/Domain values from the cookie to pre-fill the login form
String user = DispatchUtilities.getRequestAccessor().getUserName(request);
String domain = DispatchUtilities.getRequestAccessor().getDomainName(request);
if ( (domain == null) || domain.equals("null") ) {
    domain = "";
}
if ( (user == null) || user.equals("null") ) {
    user = "";
}

user = JSPUtilities.toHTMLString(user);
domain = JSPUtilities.toHTMLString(domain);

Handling Errors

In the event of an un-successful login attempt it should be indicated to the user. The JSP handles this by checking for error conditions on loading:

String error_Text = request.getParameter("error");
if (error_Text == null)
{
    error_Text = (String) request.getAttribute("error");
}
if (error_Text == null)
{
    error_Text = "";
}

Once the page loads there is a javascript call made to error_checks. This actually performs a number of checks including the minimum browser checks. If anything is in error then setErrorState is called to modify the style of the page to indicate an error condition.

Examples

Minimal Login Page

The most basic login page is a HTML form without using JSP, javascript, or images and styling. Of course this doesn't handle error checking or browser detection etc... but serves as an example of the minimum needed to write a completely custom login page:

[html,N]

<html>
<head>
<title>Basic Enportal Login page</title>
</head>
<body>

Basic enPortal Login Page

<form name="loginForm" method=post action="/enportal/servlet/pd">
<input name="login" type="hidden" value="yes">

UserID:	<input type="text" name="userid" size="12" maxlength="15">
Pwd:	<input type="text" name="password" size="12" maxlength="15">
Domain:	<input type="text" name="domainSelect" size="12" maxlength="80">
<input type="submit" value=”login”>

</form>
</body>
</html>

Login Page Elements

All Login Pages must contain certain elements. This section describes the necessary and optional elements of Login Pages for custom Login Page authors. The following table outlines the Login Page elements:

Login Element	Class	Description
Login Form	Required	HTML Login form which provides entry into the enPortal system.
Browser Type Checking	Optional	Servlet/Javascript to determine minimum browser requirements.
Auto-Fill UserID and Domain	Optional	Functions to pre-fill the user and domain fields of the login form with most recent values.
Error Message	Optional	JSP/Javascript functions to read and display any error messages returned from Login process.

Login Form

The login page must contain an HTML form with the parameters described in the following table:

Parameter	Value
Form method	POST
Form action	/enportal/servlet/pd (assuming this is on the same HTTP server, otherwise the full URL of the enPortal server plus this path must be listed as the action)
Hidden input	<input name="login" type="hidden" value="yes">
UserID field	name=”userid”
Password field	name="password"
Domain field	name=”domainSelect”

Hard-coding a Default Domain

AppBoard/enPortal requires three elements for a User to successfully log in to the system: Username, Password, and Domain. In some cases, all of the Users may be in a single Domain, and it may be a nuisance for the User to have to enter the Domain in order to log in. In this case, you can pre-fill a Domain name in the login form, or even hide the field completely and just have the Login Page auto-submit the hard-coded value for everyone who submits a login request.

Perform the following steps to hard-code a value in the Domain field in the login form:

1. Open the Login Page jsp file for editing in a text editor.
2. Search for the following text in the login page:
   • <input type="text" id="domain" value="<%=domain%>" name="domainSelect"
3. Change "value=" to a hard-coded value.
   • Example: <input type="text" id="domain" value="CustomerName" name="domainSelect"

The above will force the default Domain to be “CustomerName” instead of whatever domain was last accessed (<%=domain%>). To hide the field completely from view, change the input type from "text" to "hidden". You will want to hide the "Domain" label for the field also.

Implementing a Custom Login Page

Once you have created a custom Login Page, implement the new Login Page by completing the following:

1. Place the Login Page in the appropriate location on the server.
   • [INSTALL_HOME]/webapps/enportal/login_pages/custom/[loginpagename].jsp
2. Assign the Login Page to the system or individual Domain(s).
   • To assign to the entire system:
     • Log in to enPortal/Appboard as the administrator.
     • Go to the enPortal admin URL: http://<hostname>:<port>/enportal/home#.
     • Mouse over "Advanced" and select "Explore System".
     • Right-click "Explorer" and select "System Login Page".
     • Enter the relative path/name of the Login Page to use.
       • Example: custom/myloginpage.jsp
   • To specifying a default Login Page for a Domain:
     • Select the Domain for which you would like to specify a default Login Page.
     • Log in to enPortal/Appboard as the administrator.
     • Go to the enPortal admin URL: http://<hostname>:<port>/enportal/home#.
     • Click the "Users" tab.
     • Right-click the Domain name and select "Edit".
     • Under "Default Login Page", enter the relative path/name of the Login Page to use.
       • Example: custom/myloginpage.jsp
     • Click "Save".

If a Login Page is assigned to a Domain, a User in that Domain will need to log in and log out once to that Domain to set the cookie that will provide that custom Login Page the next time that User logs in.