Sun OpenSSO Enterprise 8.0 Developer's Guide

User Interface Files You Can Modify

The authentication GUI dynamically displays the required credentials information depending upon the authentication module invoked at run time. The following table lists the types of files you can modify to customize the login pages, logout pages, and error messages. Detailed information is provided in subsequent sections.

Table 13–1 Authentication User Interface Files and Their Locations at Installation


File Type	Default Location
Java Server Page (JSP) Files	See `OpenSSO-Deploy-base/config/auth/default`
XML Files	See `OpenSSO-Deploy-base/config/auth/default`
JavaScript Files	See `OpenSSO-Deploy-base/js`
Cascading Style Sheets	See `OpenSSO-Deploy-base/css`
Images	See `OpenSSO-Deploy-base/login_images`
Localization Files	See `OpenSSO-Deploy-base/WEB-INF/classes`
`OpenSSO-Deploy-base` represents the deployment directory where the web container deploys the `opensso.war` file

Java Server Page (JSP) Files

The authentication GUI pages are .jsp files with embedded JATO tags. You do not need to understand JATO to customize the GUI pages. Java server pages handle both the UI elements and the disciplines displayed through peer ViewBeans.

By default, JSP pages are installed and looked up in the following directory:

OpenSSO-Deploy-base/config/auth/default

Customizing the Login Page

The login page is a common page used by most authentication modules except for the Membership module. For all other modules, at run time the login page dynamically displays all necessary GUI elements for the user to enter the required credentials. For example, the LDAP authentication module login page dynamically displays the LDAP module header, LDAP user name, and password fields.

To access the default login page, use the following URL:

server-protocol://server-host.server-domain:server-port/service-deploy-uri/UI/Login

To access the default logout page, use the following URL:

server-protocol://server-host.server-domain:server-port/service-deploy-uri/UI/Logout

You can customize the following login page UI elements:

Module Header text
User Name label and field
Password label and field
Choice value label and field.

The field is a radio button by default, but can be change to a check box.
Image (at the module level)
Login button

Customizing JSP Templates

Use the JSP templates to customize the look and feel presented in the graphical user interface (GUI). Customizing JSP Templates provides descriptions of templates you can customize. The templates are located in the following directory:

OpenSSO-Deploy-base/config/auth/default

Table 13–2 Customizable JSP Templates


File Name	Purpose
`account_expired.jsp`	Informs the user that their account has expired and should contact the system administrator.
`auth_error_template.jsp`	Informs the user when an internal authentication error has occurred. This JSP usually indicates an authentication service configuration issue.
`authException.jsp`	Informs the user that an error has occurred during authentication.
`configuration.jsp`	Configuration error page that displays during the Self-Registration process.
`disclaimer.jsp`	Customizable disclaimer page used in the self-registration authentication module.
`Exception.jsp`	Informs the user that an error has occurred.
`invalidAuthlevel.jsp`	Informs the user that the authentication level invoked was invalid.
`invalid_domain.jsp`	Informs the user that no such domain exists.
`invalidPassword.jsp`	Informs the user that the password entered does not contain enough characters.
`invalidPCookieUserid.jsp`	Informs the user that a persistent cookie user name does not exist in the persistent cookie domain.
`Login.jsp`	This is a login and password template.
`login_denied.jsp`	Informs the user that no profile has been found in this domain.
`login_failed_template.jsp`	Informs the user that authentication has failed.
`Logout.jsp`	Informs the user that they have logged out.
`maxSessions.jsp`	Informs the user that the maximum sessions have been reached.
`membership.jsp`	A login page for the self-registration module.
`Message.jsp`	A generic message template for a general error not defined in one of the other error message pages.
`missingReqField.jsp`	Informs the user that a required field has not been completed.
`module_denied.jsp`	Informs the user that the user does not have access to the module.
`module_template.jsp`	Customizable module page.
`new_org.jsp`	Displayed when a user with a valid session in one organization wants to login to another organization.
`noConfig.jsp`	Informs the user that no module configuration has been defined.
`noConfirmation.jsp`	Informs the user that the password confirmation field has not been entered.
`noPassword.jsp`	Informs the user that no password has been entered.
`noUserName.jsp`	Informs the user that no user name has been entered. It links back to the login page.
`noUserProfile.jsp`	Informs the user that no profile has been found. It gives them the option to try again or select New User and links back to the login page.
`org_inactive.jsp`	Informs the user that the organization they are attempting to authenticate to is no longer active.
`passwordMismatch.jsp`	Called when the password and confirming password do not match.
`profileException.jsp`	Informs the user that an error has occurred while storing the user profile.
`Redirect.jsp`	Includes a link to a page that has been moved.
`register.jsp`	User self-registration page.
`session_timeout.jsp`	Informs the user that their current login session has timed out.
`userDenied.jsp`	Informs the user that they do not possess the necessary role (for role-based authentication.)
`userExists.jsp`	Called if a new user is registering with a user name that already exists.
`user_inactive.jsp`	Informs the user that they are not active.
`userPasswordSame.jsp`	Called if a new user is registering with a user name field and password field have the same value.
`wrongPassword.jsp`	Informs the user that the password entered is invalid.

XML Files

XML files describe the authentication module-specific properties based on the Authentication Module properties DTD file:

OpenSSO-Deploy-base/WEB-INF/Auth_Module_Properties.dtd

OpenSSO Enterprise defines required credentials and callback information for each of the default authentication modules. By default, authentication XML files are installed in the following directory:

OpenSSO-Deploy-base/config/auth/default

The following table provides descriptions of the authentication module configuration files.

Table 13–3 Authentication Module Configuration XML Files


File Name	Description
`AD.xml`	Defines a Login screen for use with Active Directory authentication.
`amAuthUnix.xml`	Defines a Login screen for use with Unix authentication
`Anonymous.xml`	For anonymous authentication, although there are no specific credentials required to authenticate.
`Application.xml`	Needed for application authentication.
`Cert.xml`	For certificate-based authentication although there are no specific credentials required to authenticate.
`HTTPBasic.xml`	Defines one screen with a header only as credentials are requested via the user’s web browser.
`JDBC.xml`	Defines a Login screen for use with Java Database Connectivity (JDBC) authentication.
`LDAP.xml`	Defines a Login screen, a Change Password screen and two error message screens (Reset Password and User Inactive).
`Membership.xml`	Default data interface which can be used to customize for any domain.
`MSISDN.xml`	Defines a Login screen for use with Mobile Subscriber ISDN (MSISDN).
`NT.xml`	Defines a Login screen.
`RADIUS.xml`	Defines a Login screen and a RADIUS Password Challenge screen.
`SafeWord.xml`	Defines two Login screens: one for User Name and the next for Password.
`SAE.xml`	Defines a Login screen for Virtual Federation Proxy (Secure Attributes Exchange)
`SAML.xml`	Defines a Login screen for SAML authentication.
`SecurID.xml`	Defines five Login screens including `UserID` and `Passcode`, PIN mode, and Token Passcode.
`Unix.xml`	Defines a Login screen and an Expired Password screen.
`WindowsDesktopSSO.xml`	Defines a Login screen for Windows Desktop SSO Authentication

Callbacks Elements

Nested Elements

The following table describes nested elements for the Callbacks element.

The Callbacks element is used to define the information a module needs to gather from the client requesting authentication. Each Callbacks element signifies a separate screen that can be called during the authentication process.

Table 13–4 Nested Elements


Element	Required	Description
`NameCallback`	*	Requests data from the user; for example, a user identification.
`PasswordCallback`	*	Requests password data to be entered by the user.
`ChoiceCallback`	*	Used when the application user must choose from multiple values.
`ConfirmationCallback`	*	Sends button information such as text which needs to be rendered on the module’s screen to the authentication interface.
`HttpCallback`	*	Used by the authentication module with HTTP-based handshaking negotiation.
`SAMLCallback`		Used for passing either Web artifact or SAML POST response from SAML service to the SAML authentication module when this module requests for the respective credentials. This authentication module behaves as SAML recipient for both (Web artifact or SAML POST response) and retrieves and validates SAML assertions.

Attributes

The following table describes attributes for the Callbacks element.

length: Number or length of callbacks.
order: Sequence of the group of callbacks.
timeout: Number of seconds the user has to enter credentials before the page times out. Default is 60.
template: Defines the UI .jsp template name to be displayed.
image: Defines the UI or page-level image attributes for the UI customization
header: Text header information to be displayed on the UI. Default is Authentication.
error: Indicates whether authentication framework/module needs to terminate the authentication process. If yes, then the value is true. Default is false .

ConfirmationCallback Element

The ConfirmtationCallback element is used by the authentication module to send button information for multiple buttons. An example is the button text that must be rendered on the UI page. The ConfirmationCallback element also receives the selected button information from the UI.

Nested Element

ConfirmationCallback has one nested element named OptionValues. The OptionValues element provides a list or an array of button text information to be rendered on the UI page.OptionValues takes no attributes.

If there is only one button on the UI page, then the module is not required to send this callback. If ConfirmationCallback is not provided through the Authentication Module properties XML file, then anAuthUI.properties will be used to pick and display the button text or label for the Login button. anAuthUI.properties is the global UI properties file for all modules.

Callbacks length value should be adjusted accordingly after addition of the new callback.

Example:

<ConfirmationCallback>
    <OptionValues>
        <OptionValue>
            <Value> <required button text> </Value>
        </OptionValue>
    </OptionValues>
</ConfirmationCallback>

JavaScript Files

JavaScript files are parsed within the Login.jsp file. You can add custom functions to the JavaScript files in the following directory:

OpenSSO-Deploy-base/js

The Authentication Service uses the following JavaScript files:

Table 13–5 JavaScript Files Used by the Authentication Service


File	Description
`auth.js`	Used by `Login.jsp` for parsing all module files to display login requirement screens.
`browserVersion.js`	Used by `Login.jsp` to detect the client type.
`admincli.js`	Used by the admin CLI.
`opensso.js`	Used to get the context path.

Cascading Style Sheets

To define the look and feel of the UI, modify the cascading style sheets (CSS) files. Characteristics such as fonts and font weights, background colors, and link colors are specified in the CSS files. You must choose the appropriate .css file for your browser in order to customize the look and feel on the user interface.

In the appropriate .css file, change the background-color attribute. For example:

.button-content-enabled { background-color:red; }
button-link:link, a.button-link:visited { color: #000;
background-color: red;
text-decoration: none; }

Browser-specific CSS files are installed with OpenSSO Enterprise in the following directory:

OpenSSO-Deploy-base/css

The following table describes each CSS file.

Table 13–6 OpenSSO Enterprise Cascading Style Sheet (CSS) Files


File Name	Purpose
`css_ie6win.css`	Configured specifically for Microsoft Internet Explorer 6 for Windows.
`css_ie5win.css`	Configured specifically for Microsoft Internet Explorer 5 for Windows.
`css_ns6up.css`	Configured specifically for Netscape Communicator 6.
`css_ns4sol.css`	Configured specifically for Netscape Communicator 4 for Solaris systems.
`css_ns4win.css`	Configured specifically for Netscape Communicator 4 for Windows.
`styles.css`	Used in JSP pages as a default style sheet.

Images

The default authentication GUI is branded with Sun Microsystems, Inc. logos and images. By default, the GIF files are installed in the following directory:

OpenSSO-Deploy-base/login_images

These images can be replaced with images relevant to your company or organization. The following table describes each GIF image used for the default GUI.

Table 13–7 Sun Microsystems Branded GIF Images


File Name	Purpose
`adminstyle.css`, `master-style.css`, and `CCCSS_Default.css`	Style sheets
`Identity_LogIn.gif`	Sun Java System Access Manager banner
`error_32_sunplex.gif`	Error indicator
`info_32_sunplex.gif`	Information indicator
`spacer.gif`	Spacer graphic
`logo_sun.gif`	Sun Microsystems logo graphic
`Java.gif`	Java graphic
`spacer.gif`	A one pixel clear image used for layout purposes

Localization Files

After you deploy the opensso.war file the localized files are located in the following directory:

OpenSSO-Deploy-base/WEB-INF/classes

OpenSSO-Deploy-base represents the deployment directory where the web container deployed the opensso.war file.

In addition to US English (en_US), OpenSSO Enterprise includes localized properties files for these languages:

German (de)
Spanish (es)
French (fr)
Japanese (ja)
Korean (ko)
Simplified Chinese (zh)
Traditional Chinese (zh_TW)

A localization properties file, sometimes also referred to as an i18n (internationalization) properties file, specifies the screen text and error messages that an administrator or user sees when directed to the attribute configuration page for an authentication module. The properties files are global to the OpenSSO Enterprise instance.

Each authentication module has its own properties file that follows the naming following format:

amAuthmodulename.properties

For example, amAuthLDAP.properties is for the default language (US English, ISO-8859-1), amAuthLDAP_ja.properties is for Japanese, and so on.

You can adapt Java applications to these various languages without code changes by translating the values in these respective localization properties file.

The following table summarizes the localization properties files for each authentication module.

Table 13–8 Localization Properties Files for Authentication Modules


File Name	Description
`amAuth.properties`	Core Authentication Service
`amAuthAD.properties`	Microsoft Active Directory Authentication Module
`amAuthAnonymous.properties`	Anonymous Authentication Module
`amAuthApplication.properties`	For OpenSSO Enterprise internal use only. Do not remove or modify this file.
`amAuthCert.properties`	Certificate Authentication Module
`amAuthConfig.properties`	Authentication Configuration Module
`amAuthContext.properties`	Localized error messages for the `AuthContext` Java class
`amAuthContextLocal.properties`	For OpenSSO Enterprise internal use only. Do not remove or modify this file.
`amDataStore.properties`	Data Store Authentication Module
`amAuthHTTPBasic.properties`	HTTP Basic Authentication Module
`amAuthJDBC.properties`	Java Database Connectivity (JDBC) Authentication Module
`amAuthLDAP.properties`	LDAP Authentication Module
`amAuthMembership.properties`	Membership Authentication Module
`amAuthMSISDN.properties`	Mobile Subscriber ISDN Authentication Module
`amAuthNT.properties`	Windows NT Authentication Module
`amAuthRadius.properties`	RADIUS Authentication Module
`amAuthSafeWord.properties`	Safeword Authentication Module
`amAuthSAML.properties`	SAML Authentication Module
`amAuthSecurID.properties`	SecurID Authentication Module
`amAuthUI.properties`	Labels used in the authentication user interface
`amAuthUnix.properties`	UNIX Authentication Module
`amAuthWindowsDesktopSSO.properties`	Windows Desktop SSO Authentication Module