Sun Java System Access Manager 6 2005Q1 Developer's Guide |
Chapter 5
Customizing the
Authentication User InterfaceThe 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 ModifyThe 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.
To access the default Login page, use the following URL: <server_protocol>://<server_host>.<server_domain>:<server_port>/
<service_deploy_uri>/UI/LoginTo access the default Logout page, use the following URL:
<server_protocol>://<server_host>.<server_domain>:<server_port>/
<service_deploy_uri>/UI/LogoutThe 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
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
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.
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.
Attributes
The following table describes attributes for the Callbacks element.
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.
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.
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.
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.
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.
Customizing Branding and FunctionalityYou 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
- Go to the directory where default JSP templates are stored.
cd AccessManager-base/SUNWam/web-src/services/config/auth
- Create a new directory.
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.
For example, for the following attributes:
org = SunMicrosystems
locale = en
subOrg = solaris
clientPath = html/customerName/
serviceName = paycheck
customized directory paths would be:
SunMicrosystems_en/solaris/html/ustomerName/paycheck
SunMicrosystems/solaris/html/ustomerName/paycheck
default_en/solaris/html/ustomerName/paycheck
default/solaris/html/ustomerName/paycheck
The files in the new directory can be customized if necessary, but not this is not required. See Customizing the Login Page and Customizing JSP Templates for information on what you can modify.
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.
Customizing the Self-Registration PageYou 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
By default, the first three data fields are required in the default Membership Module configuration:
You can specify which data is requested, which is required, and which is optional. Code Example 5-1 illustrates how to add a telephone number as requested data.
You can specify or add data which should be requested from a user as part of the User Profile. By default you can specify or add any attributes from the following objectClasses:
Administrators can add their own user attributes to the User Profile.
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.
- Restart both Access Manager and the web container server.
Updating and Redeploying services.warIf 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
- cd IdentityServer_base/SUNWam
This is the directory in which the WARs are kept.
- jar -uvf WARfilename.war <path_to_modified_file>
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.
- rm newfile/index.html
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:58080ServerDeployURI represents the server Universal Resource Identifier
Example: amserverWL61 Server represents the Weblogic Server name
Example: name.comOn 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