The Authentication Service provides the web-based Graphical User Interface (GUI) for all default and custom authentication modules installed in the Sun JavaTM System Access Manager 7 2005Q4 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. You can customize this user interface per client type, realm, locale, or service.
For more information about what the Authentication Service does and how it works, see Chapter 3, User Authentication, in Sun Java System Access Manager 7 2005Q4 Technical Overview and User Authentication in Sun Java System Access Manager 7 2005Q4 Technical Overview .
The following topics are covered in this chapter:
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 4–1 Authentication User Interface Files and Their Locations at Installation
File Type |
Default Location |
---|---|
AccessManager-base/SUNWam/web-src/services |
|
AccessManager-base/SUNWam/web-src/services/config/auth/default |
|
AccessManager-base/SUNWam/web-src/services/config/auth/default |
|
AccessManager-base/SUNWam/web-src/services/js |
|
<AccessManager-base /SUNWam/web-src/services/css |
|
AccessManager-base/SUNWam/web-src/services/login_images |
|
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
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.
This directory 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.
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.
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
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 4–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 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 4–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. |
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.
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. |
The following table describes attributes for the Callbacks element.
The number or length of callbacks.
Is the sequence of the group of callbacks.
Number of seconds the user has to enter credentials before the page times out. Default is 60.
Defines the UI .jsp template name to be displayed.
Defines the UI or page-level image attributes for the UI customization
Text header information to be displayed on the UI. Default is Authentication.
Indicates whether authentication framework/module needs to terminate the authentication process. If yes, then the value is true. Default is false .
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.
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 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:
Used by Login.jsp for parsing all module files to display login requirement screens.
Used by Login.jsp to detect the client type.
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 4–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. |
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 4–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 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 4–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. |
You can modify JSP templates and module configuration properties files to reflect branding or functionality specified for any of the following:
Organization of the request
SubOrganization of the request.
Locale of the request
Client Path
Client Type information of the request
Service Name (serviceName)
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
In these paths, SubOrg, Locale, Client Path, Service Name (which represents orgPath and filePath ) are optional. 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 use the lowercase value of the organization name (sunmicrosystems).
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/ customerName /paycheck
SunMicrosystems/solaris/html/ customerName /paycheck
default_en/solaris/html/ customerName/paycheck
default/solaris/html/ customerName /paycheck
Copy the default templates.
Copy all the JSP templates (*.jsp) and authentication module configuration properties XML files (*.xml) from the default directory:
AccessManager-base /SUNWam/web-src/services/config/auth/default
to the new directory:
AccessManager-base /SUNWam/web-src/services/config/ auth/CustomizedDirectoryPath
Customize the files in the new directory.
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.
Update and redeploy services.war.
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 Chapter 12, Updating and Redeploying Access Manager WAR Files for general information on updating and redeploying Access Manager .war files.
Restart both Access Manager and the web container server.
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.
Customize the Membership.xml file.
By default, the first three data fields are required in the default Membership Module configuration:
User name
User Password
Confirm User Password
You can specify which data is requested, which is required, and which is optional. The sample below 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:
top
person
organizationalPerson
inetOrgPerson
iplanet-am-user-service
inetuser
Administrators can add their own user attributes to the User Profile.
Update and redeploy services.war.
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 Chapter 12, Updating and Redeploying Access Manager WAR Files for general information on updating and redeploying Access Manager .war files.
Restart both Access Manager and the web container server.
<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> |
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 Staging Area for Files to be Customized provides background information on this file.
cd AccessManager-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 AccessManager-base/SUNWam/newfile.
rm newfile/index.html
Deletes the modified file.
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.
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 nam.e Example: name.com
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
See the deployment documentation that comes with the IBM WebSphere product:
http://www-3.ibm.com/software/webservers/studio/doc/v40/studioguide/ en/html/sdsscenario1.html
Access Manager provides a remote Authentication user interface component to enable secure, distributed authentication across two firewalls. You can install the remote authentication user interface component on any servlet-compliant web container within the non-secure layer of an Access Manager deployment. The remote component works with Authentication client APIs and authentication utility classes to authenticate web users. The remote component is customizable and uses a JATO presentation framework.
For detailed information on how Distributed Authentication works, see Distributed Authentication User Interface Component in Sun Java System Access Manager 7 2005Q4 Technical Overview and User Authentication in Sun Java System Access Manager 7 2005Q4 Technical Overview.
Once the Distributed Authentication component is installed and deployed, you can modify the JSP templates and module configuration properties files to reflect branding and specific functionality for any of the following:
This is the organization or sub-organization of the request.
Locale of the request.
Client Type information of the request.
Service name for service-based authentication.
The Distributed Authentication User Interface package must already be installed. For detailed installation instructions, see Installing and Customizing the Distributed Authentication Interface in Technical Note: Using Access Manager Distributed Authentication.
Explode the Distributed Authentication User Interface WAR.
At the command line, go to the directory where the default JSP templates are stored.
Example:
cd DistributedAuth-base/config/auth
where DistributedAuth-base is the directory where the Distributed Authentication User Interface package is exploded.
Create a new directory using the appropriate directory path based on the level of customization.
Use the following form:
org_locale/orgPath/filePath org/orgPath/filePath default_locale/orgPath/filePath default/orgPath/filePath
where:
orgPath = subOrg1/subOrg2 filePath = clientPath + serviceName clientPath = clientType/sub-clientType
The following are optional: Sub-org, Locale , Client Path , and Service Name . In the following example, orgPath and filePath are optional.
For example, given the following:
org = iplanet locale = en subOrg = solaris clientPath = html/nokia/ serviceName = paycheck
the appropriate directory paths for the above are:
iplanet_en/solaris/html/nokia/paycheck iplanet/solaris/html/nokia/paycheck default_en/solaris/html/nokia/paycheck default/solaris/html/nokia/paycheck
Copy all the JSP templates and authentication module configuration properties XML files from the default directory to the new directory.
cp DistributedAuth-base/config/auth/default/*.jsp DistributedAuth-base/config/auth/new_directory_path
cp DistributedAuth-base/config/auth/default/*.xml DistributedAuth-base/config/auth/new_directory_path
(Optional) Modify the files in the new directory to suit your needs.
For information about customizing the .jsp files, see Java Server Pages.
For information about customizing the .xml files, XML Files.
Create a new .WAR file named amauthdistui_deploy.war from DistributedAuth-base.
Deploy amauthdistui_deploy.war.
The web container administrator deploys the file in the remote web container.