Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Access Manager 6 2005Q1 Developer's Guide 

Chapter 5
Customizing the
Authentication User Interface

The authentication service provides the web-based Graphical User Interface (GUI) for all out-of-box and custom authentication modules installed in the Sun Java™ System Access Manager 6 2005Q1 deployment. This interface provides a dynamic and customizable means for gathering authentication credentials by presenting the web-based login requirement pages to a user requesting access.

The authentication service GUI is built on top of JATO (J2EE Assisted Take-Off), a Java 2 Enterprise Edition (J2EE) presentation application framework. This framework is used to help developers build complete functional Web applications.

The following topics are covered in this chapter:

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 Table 5-1 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 5-1  Authentication User Interface Files and Their Locations at Installation

File Type

Default Location

services.war File

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

The following image illustrates the first page seen for a login when all modules have been configured for authlevel 0.

Figure 5-1  Default Login Page when authlevel=0

When the authlevel = 0, the default Login Page lists all possible types of authentication.

services.war File

The services.war contains all the files you need to modify the authentication GUI. When you install Access Manager on Sun ONE Application Server, on Sun Java ES Web Server, or on WebLogic Web Server, services.war is automatically installed and deployed. Its files and directories are installed by default in the following location:

AccessManager-base/SUNWam/web-src/services

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 order to see the changes in the actual GUI, you must update and then redeploy services.war. See Updating and Redeploying services.war in this chapter for instructions. See Appendix C, "WAR Files" for general information on updating and redeploying Access Manager .war files.

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 disciplines displayed through peer ViewBeans. By default, JSP pages are installed in the following directory: AccessManager-base/SUNWam/web-src/services/config/auth/default

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

Customizing JSP Templates

Use the JSP templates to customize the look and feel of presented in the graphical user interface (GUI). See To Modify Branding and Functionality for detailed instructions. Table 5-2 contains provides descriptions of templates you can customize. The templates are located in the following directory:

IdentityServer_base/SUNWam/web-src/services/config/auth/default

Table 5-2  List of 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.

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.

invalidPCookieUserid.jsp

Informs the user that a persistent cookie user name does not exist in the persistent cookie domain.

invalidPassword.jsp

Informs the user that the password entered does not contain enough characters.

invalid_domain.jsp

Informs the user that there is no such 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.

userPasswordSame.jsp

Called if a new user is registering with a user name field and password field have the same value.

user_inactive.jsp

Informs the user that they are not active.

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. Access Manager defines an authentication module configuration file for each of the default authentication modules. By default, Authentication XML files are installed in the following directory: IdentityServer_base/SUNWam/web-src/services/config/auth/default. Table 5-3 provides descriptions of the authentication module configuration files.

Note that 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 5-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.

This following sections describe XML elements you can modify to customize the authentication UI. For a comprehensive list of authentication elements defined in the Authentication Module Properties DTD, see the Developer’s Reference.

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

*

 

Attributes

The following table describes attributes for the Callbacks element.

Attribute

Default

Description

length

 

The number or length of callbacks

order

 

Is the sequence of the group of callbacks

timeout

60

Number of seconds the user has to enter credentials before the application times out.

template

 

Defines the UI or page level attributes for the UI customization

image

 

Defines the UI or page level attributes for the UI customization

header

Authentication

the text header information to be displayed on the UI

error

false

Indicates whether authentication framework/module needs to terminate the authentication process. If yes, then the value is true.

ConfirmationCallback Element

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

Nested Elements

The following table describes nested elements for the ConfirmationCallback element.

Element

Required

Description

OptionValues

 

 

Attributes

None

Details

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

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: IdentityServer_base/SUNWam/web-src/services/js.

The JavaScript files used by the Authentication Service are summarized in Table 5-4.

Table 5-4  List of JavaScript Files 

File Name

Purpose

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

Modify the cascading style sheets (CSS) files to define the look and feel of the UI. 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; }

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

IdentityServer_base/SUNWam/web-src/ services/css.

Table 5-5 provides a brief description of each CSS file.

Table 5-5  List of 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 Netscape™ Communicator v. 4 for Solaris™.

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. Table 5-6 provides a brief description for each GIF image used for the default GUI.

Table 5-6  List of 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

Location: <install-dir>/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 IdentityServer_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.

Table 5-7 contains a listing of the localization properties files configured for each module. These files can be found in IdentityServer_base/SUNWam/locale.

Table 5-7  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.

Customizing Branding and Functionality

You can modify JSP templates and module configuration properties files to reflect branding or functionality specified for any of the following:

To Modify Branding and Functionality

  1. Go to the directory where default JSP templates are stored.

    2.      cd AccessManager-base/SUNWam/web-src/services/config/auth

  2. Create a new directory.

    3. Use the appropriate customized directory path based on the level of customization. Use the following forms:

         org_locale/orgPath/filePath

         org/orgPath/filePath

         default_locale/orgPath/filePath

         default/orgPath/filePath

    In these examples,

         orgPath represents subOrg1/subOrg2

         filePath represents clientPath + serviceName

         clientPath represents clientType/sub-clientType

    Note that Sub-org, Locale, Client Path, Service Name (which represents orgPath and filePath) are optional. Note also that the organization name you specify may match the organization attribute set in the Directory Server. For example, if the organization attribute value is SunMicrosystems, then the organization customized directory should also be SunMicrosystems. If no organization attribute exists, then the lowercase value of the organization name (sunmicrosystems) should be used.

  1. Copy the default templates.
  1. Customize the files in the new directory.
  1. Update and redeploy services.war.
  1. Restart both Access Manager and the web container server.

Customizing the Self-Registration Page

You can customize the Self-registration page which is part of Membership authentication module. The default data and interface provided with the Membership authentication module is generic and can work with any domain.You can configure it to reflect custom data and information.You can add custom user profile data or fields to register or to create a new user.

To Modify the Self-Registration Page

  1. Customize the Membership.xml file.
  1. Update and redeploy services.war.
  1. Restart both Access Manager and the web container server.

    2. Code Example 5-1  Adding a Telephone Number as Requested Data  

    <Callbacks length="9" order="16" timeout="300" header="Self Registration" template="register.jsp" >

    <NameCallback isRequired="true" attribute="uid" >

    <Prompt> User Name: </Prompt>

    </NameCallback>

    <PasswordCallback echoPassword="false" isRequired="true" attribute="userPassword" >

    <Prompt> Password: </Prompt>

    </PasswordCallback>

    <PasswordCallback echoPassword="false" isRequired="true" >

    <Prompt> Confirm Password: </Prompt>

    </PasswordCallback>

    <NameCallback isRequired="true" attribute="givenname" >

    <Prompt> First Name: </Prompt>

    </NameCallback>

    <NameCallback isRequired="true" attribute="sn" >

    <Prompt> Last Name: </Prompt>

    </NameCallback>

    <NameCallback isRequired="true" attribute="cn" >

    <Prompt> Full Name: </Prompt>

    </NameCallback>

    <NameCallback attribute="mail" >

    <Prompt> Email Address: </Prompt>

    </NameCallback>

    <NameCallback isRequired="true"attribute="telphonenumber">

    <Prompt> Tel:</Prompt>

    </NameCallback>

    <ConfirmationCallback>

    <OptionValues>

    <OptionValue>

    <Value> Register </Value>

    </OptionValue>

    <OptionValue>

    <Value> Cancel </Value>

    </OptionValue>

    </OptionValues>

    </ConfirmationCallback>

    </Callbacks>

Updating and Redeploying services.war

If Access Manager is installed on BEA WebLogic, IBM WebSphere, or Sun ONE Application Server, you must update and redeploy services.war before you can see any changes in the user interface. Once you’ve made changes to the authentication GUI files, regardless of the brand of web container you’re using, it is a good practice to update and redeploy the services.war file. When you update and redeploy services.war, you overwrite the default GUI files with your changes, and the changed files are placed in their proper locations. The section services.war File provides background information on this file.

To Update services.war

  1. cd IdentityServer_base/SUNWam

    2. This is the directory in which the WARs are kept.

  2. jar -uvf WARfilename.war <path_to_modified_file>

    3. The -uvf option replaces the old file with the newly modified file. For example:

    jar -uvf services.war newfile/index.html

    replaces the index.html file in console.war with the index.html file located in IdentityServer_base/SUNWam/newfile.

  3. rm newfile/index.html

    4. Deletes the modified file.

To Redeploy services.war

The services.war will be in the following directory:

AccessManager-base/SUNWam

Depending upon the brand of web container you are using, execute one of the following commands.

On BEA WebLogic

java weblogic.deploy -url ServerURL -component {ServerDeployURI}:
    {WL61 Server} deploy WL61AdminPassword {ServerDeployURI}

{AccessManager-base}/{SUNWam}/services.war

In this example,

ServerURL uses the form protocol://host:port
Example: http://abc.com:58080

ServerDeployURI represents the server Universal Resource Identifier
Example: amserver

WL61 Server represents the Weblogic Server name
Example: name.com

On Sun ONE Application Server

asadmin deploy -u IAS7Admin -w IAS7AdminPassword -H HostName -p IAS7AdminPort --type web SECURE_FLAG --contextroot

ServerDeployURI --name amserver --instance IAS7Instance {AccessManager-base}/{SUNWam}/services.war

On IBM WebSphere

See the deployment documentation that comes with the IBM WebSphere product. websphere:

http://www-3.ibm.com/software/webservers/studio/doc/v40/studioguide/
    en/html/sdsscenario1.html



Previous      Contents      Index      Next     

Part No: 817-7649.   Copyright 2005 Sun Microsystems, Inc. All rights reserved.