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 User Interface Files You Can Modify lists the types of files you can modify to convey custom representations of Login pages, Logout pages, and error messages. Detailed information is provided in following sections.

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

File Type	Default Location
Staging Area for Files to be Customized	AccessManager-base/SUNWam/web-src/services
Java Server Pages	AccessManager-base/SUNWam/web-src/services/config/auth/default
XML Files	AccessManager-base/SUNWam/web-src/services/config/auth/default
JavaScript Files	AccessManager-base/SUNWam/web-src/services/js
Cascading Style Sheets	<AccessManager-base /SUNWam/web-src/services/css
Images	AccessManager-base/SUNWam/web-src/services/login_images
Localization Files	AccessManager-base/SUNWam/locale

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

Staging Area for Files to be Customized

When Access Manager is installed, a staging area exists in the following location:

AccessManager-base/SUNWam/web-src/services

This directory content is identical to the content of the services.war.

The AccessManager-base/SUNWam/web-src/services contains all the files you need to modify the authentication GUI. When you install Access Manager on Sun Java System Application Server, on Sun Java System Web Server, or on BEA WebLogic Web Server, services.war (the services web application) is automatically installed and deployed.

If you install Access Manager on other web containers, you may have to manually deploy services.war. See the documentation that comes with the web container.

Once you’ve modified the authentication GUI files in the staging area, in order to see the changes in the actual GUI, you must update and then redeploy services.war. See Updating and Redeploying services.war.

Java Server Pages

All authentication GUI pages are .jsp files with embedded JATO tags. You do not need to understand JATO to customize Access Manager GUI pages. Java server pages handle both the UI elements and the disciplines displayed through peer ViewBeans. By default, JSP pages are installed in the following directory: AccessManager-base/SUNWam/web-src/services/config/auth/default

Java server pages are looked up from the deployed location. In previous Access Manager versions, the Java server pages were looked up from the installed location.

Customizing the Login Page

The Login page is a common Login 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 required credentials. For example, the LDAP authentication module Login page dynamically displays the LDAP module header, LDAP User name, and Password fields.

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:

AccessManager-base/SUNWam/web-src/services/config/auth/default

Table 12–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 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	This is a 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/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	A customizable module page.
new_org.jsp	This page is 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	This page is 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	This page carries a link to a page that has been moved.
register.jsp	A 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	This page is 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: AccessManager-base/SUNWam/Auth_Module_Properties.dtd. Access Manager defines required credentials and callback information for each of the default authentication modules. By default, Authentication XML files are installed in the following directory:

AccessManager-base/SUNWam/web-src/services/config/auth/default The table XML Files provides descriptions of the authentication module configuration files.

XML files are looked up from the deployed location. In previous Access Manager versions, the XML files were looked up from the installed location.

Table 12–3 List of Authentication Module Configuration Files

File Name	Purpose
AD.xml	Defines a Login screen for use with Active Directory 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.
SAML.xml	Defines a Logins screen for Security Assertion Markup Language (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.

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.

Nested Elements

The following table describes nested elements for the Callbacks element.

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

The number or length of callbacks.

order

Is the 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 which 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 i18n 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: AccessManager-base/SUNWam/web-src/services/js .

The Authentication Service uses the following JavaScript files:

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.

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

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

A number of browser-based CSS files are installed with Access Manager in the following directory:

AccessManager-base/SUNWam/web-src/services/css.

The following table provides a brief description of each CSS file.

Table 12–4 Cascading Style Sheets

File Name	Purpose
css_generic.css	Configured for generic web browsers.
css_ie5win.css	Configured specifically for Microsoft® Internet Explorer v.5 for Windows®.
css_ns4sol.css	Configured specifically for NetscapeTM Communicator v. 4 for SolarisTM.
css_ns4win.css	Configured specifically for Netscape Communicator v.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:

SUNWam/web-src/services/login_images

These images can be replaced with images relevant to your company. The following table provides a brief description for each GIF image used for the default GUI.

Table 12–5 Sun Microsystems Branded GIF Images

File Name	Purpose
Identity_LogIn.gif	Sun Java System Access Manager banner across the top.
Registry_Login.gif	No longer used.
bannerTxt_registryServer.gif	No longer used.
logo_sun.gif	Sun Microsystems logo in the upper right corner.
spacer.gif	A one pixel clear image used for layout purposes.
sunOne.gif	Sun Java System logo in the lower right corner.

Localization Files

Localization files are located in the following directory: AccessManager-base/SUNWam/locale

These are i18n properties files global to the Access Manager instance. A localization properties file, also referred to as an i18n (internationalization) properties file specifies the screen text and error messages that an administrator or user will see when directed to an authentication module’s attribute configuration page. Each authentication module has its own properties file that follows the naming format amAuthmodulename.properties ; for example, amAuthLDAP.properties. They are located in AccessManager-base/SUNWam/locale/. The default character set is ISO-8859-1 so all values are in English, but Java applications can be adapted to various languages without code changes by translating the values in the localization properties file.

The following table summarizes the localization properties files configured for each module. These files can be found in AccessManager-base/SUNWam/locale.

Table 12–6 List of Localization Properties Files

File Name	Purpose
amAuth.properties	Defines the parent Core Authentication Service.
amAuthAD.properties	Defines the Active Directory Authentication Module.
amAuthAnonymous.properties	Defines the Anonymous Authentication Module.
amAuthApplication.properties	For Access Manager internal use only. Do not remove or modify this file.
amAuthCert.properties	Defines the Certificate Authentication Module.
amAuthConfig.properties	Defines the Authentication Configuration Module.
amAuthContext.properties	Defines the localized error messages for the AuthContext Java class.
amAuthContextLocal.properties	For Access Manager internal use only. Do not remove or modify this file.
amAuthHTTPBasic.properties	Defines the HTTP Basic Authentication Module.
amAuthJDBC.properties	Defines the Java Database Connectivity (JDBC) Authentication Module.
amAuthLDAP.properties	Defines the LDAP Authentication Module.
amAuthMembership.properties	Defines the Membership Authentication Module.
amAuthMSISDN.properties	Defines the Mobile Subscriber ISDN Authentication Module.
amAuthNT.properties	Defines the Windows NT Authentication Module.
amAuthRadius.properties	Defines the RADIUS Authentication Module.
amAuthSafeWord.properties	Defines the Safeword Authentication Module.
amAuthSAML.properties	Defines the Security Assertion Markup Language (SAML) Authentication Module.
amAuthSecurID.properties	Defines the SecurID Authentication Module.
amAuthUI.properties	Defines labels used in the authentication user interface.
amAuthUnix.properties	Defines the UNIX Authentication Module.