Sun ONE logo      Previous      Contents      Index      Next     

Sun ONE Identity Server Customization and API Guide

Chapter 3
Authentication Service

The Authentication Service is the point of entry for Sun ONE Identity Server. A user or client application must pass an authentication process before being allowed access to the console or any resource that is secured by it. This chapter explains the authentication process, custom authentication modules and clients, and other related features. It contains the following sections:


Overview

Identity Server provides secure access to web-based (or non-web-based) applications and the data that they store. When a user or application attempts to access a protected resource, it is directed to submit credentials to one (or more) authentication modules; for instance, the LDAP module requires authentication against a Sun ONE Directory Server while the SecurID� module requires authentication against RSA ACE/Server� software. Gaining access to any of these resources requires that the requesting entity be given permission based on the submitted credentials. The Authentication Service is the authority, granting or denying access upon completion of the required authentication process. After a successful authentication, the requestor would be directed to the requested resource or the Identity Server console.

The Authentication Service may be accessed in one of the following ways:

Authentication Via A Web Browser

A user with a web browser can authenticate to Identity Server using the Authentication Service User Interface. This interface is accessed by entering the Authentication Service User Interface login URL in the browser’s location bar. After entering the URL, the user is prompted to submit verifying credentials based on the invoked authentication module(s). Once the credentials have been passed back to Identity Server (assuming successful authentication), the user can gain access based on their privileges:

Authentication Via The Java API

External Java applications can authenticate to Identity Server using the Authentication API For Java Applications. This API provides interfaces to initiate the authentication process and communicate authentication credentials to the Authentication Service; the Identity Server API are based on the Java Authentication and Authorization Service (JAAS) specification. JAAS are Java packages that enable services to authenticate and enforce access controls upon users. They implement a version of the standard Pluggable Authentication Module (PAM) framework, and support user-based authorization.


Note

The JAAS packages, starting with javax.security.auth, can be found in the Javadocs for Java 2 Platform, Standard Edition (J2SE), version 1.4.2.


Developers can incorporate the API classes and methods into their Java applications to allow communication with the Authentication Service. The external application’s Java request is converted to an XML message format and passed to Identity Server over HTTP(S). Once received, the XML message is converted back into a Java request which can be interpreted by the Authentication Service.


Note

All request and subsequent return messages are passed in the XML format. The messages are structured according to the remote-auth.dtd discussed in "The remote-auth.dtd Structure".


The Authentication Service returns login requirement screens based on the authentication module being accessed. The user returns authentication credentials and is allowed or denied access based on these credentials. The Java API package is discussed further in "Authentication API For Java Applications".

Authentication Via The C API

Identity Server also includes an Authentication API for C applications to authenticate to the Identity Server. This API provides functions to initiate the authentication process and communicate authentication credentials to the Authentication Service. After passing the authentication process, a validated session token is sent back to the C application. The C API are discussed further in "Authentication API For C Applications".

Redirection URLs

Upon a successful or failed authentication, Identity Server looks for information on where to redirect the user. There is an order of precedence in which the application will look for this information based on the authentication method and whether the authentication has been successful or has failed. Because these redirection URLs are based on the method of authentication, this order (and related information) is detailed in "Authentication Methods".


Authentication Service Modules

Identity Server is installed with a set of default authentication services. The following sections describe the installed modules and, where applicable, provide an image of the module’s login requirement screen. (The login requirement screens are discussed in more detail in "Authentication Service User Interface".)


Note

See the Sun ONE Identity Server Administration Guide for more information on how to register the authentication services and modules using the Identity Server console.


Authentication Configuration Service

The Authentication Configuration Service allows for the configuration of authentication modules based on roles or organizations. It is also the service where the Login Succes URL and the Login Failed URL attributes are defined. This is not a module to which a user can login. More information on this service can be found in the Authentication Configuration Service Attributes chapter of the Sun ONE Identity Server Administration Guide.

Core Authentication Service

The Core Authentication Service is the configuration base for all authentication modules. It must be registered as a service to an organization before any user can log in using the other authentication modules. It allows the Identity Server administrator to define default values for an organization’s authentication parameters. These values can then be picked up if no overriding value is defined in the chosen authentication module. The default values for the Core Authentication Service are defined in the amAuth.xml file and stored in Directory Server after installation. This is not a module to which a user can login. More information on this service can be found in Core Authentication Service Attributes chapter of the Sun ONE Identity Server Administration Guide.

Anonymous Authentication Module

This module allows a user to log in without specifying a user name and/or password. Additionally, an Anonymous user can be created. Logging in as Anonymous is then possible without a password. Anonymous connections are generally customized by the Identity Server administrator to have limited access to the server. More information on this module can be found in the Anonymous Authentication Attributes chapter of the Sun ONE Identity Server Administration Guide.

Figure 3-1  Anonymous Authentication Login Requirement Screen

Anonymous Authentication Login Requirement Screen

Certificate Authentication Module

This module allows a user to log in through a personal digital certificate (PDC) that could optionally use the Online Certificate Status Protocol (OCSP) to determine the state of a certificate. More information on this module can be found in the Certificate Authentication Attributes chapter of the Sun ONE Identity Server Administration Guide.

Figure 3-2  Certificate-based Authentication Login Requirement Screen

Certificate-based Authentication Login Requirement Screen

HTTP Basic Authentication Module

This module allows login using the HTTP’s basic authentication with no data encryption. A user name and password are requested via the web browser. Credentials are validated internally using the LDAP authentication module. More information on this module can be found in the HTTP Basic Authentication Attributes chapter of the Sun ONE Identity Server Administration Guide.

Figure 3-3  HTTP Basic Authentication Login Requirement Screen

HTTP Basic Authentication Login Requirement Screen

LDAP Authentication Module

This module allows for authentication using LDAP bind, an operation which associates a user ID password with a particular LDAP entry. The authentication module enabled after Identity Server is installed is LDAP. More information on this module can be found in the LDAP Authentication Attributes chapter of the Sun ONE Identity Server Administration Guide.


Note

An administrator can define different multiple LDAP configurations for an organization. More information on this can be found in "Multi-LDAP Authentication Module Configuration".


Figure 3-4  LDAP Authentication Login Requirement Screen

LDAP Authentication Login Requirement Screen

Membership Authentication Module

Membership authentication is implemented similarly to personalized sites such as my.site.com, or mysun.sun.com. When this service is enabled, a user can create an account, personalize it without the aid of an administrator, and access it as a registered user. More information on this module can be found in the Membership Authentication Attributes chapter of the Sun ONE Identity Server Administration Guide.


Note

The Membership Authentication Module is used in "Configuring The Authentication Module" as a sample module.


Figure 3-5  Membership Authentication Login Requirement Screen

Membership Authentication Login Requirement Screen

NT Authentication Module

This module allows for authentication against a Microsoft Windows� NT server. More information on this module can be found in the NT Authentication Attributes chapter of the Sun ONE Identity Server Administration Guide.


Note

In order to actualize the NT authentication module, Samba 2.2.2 must be downloaded and installed. Samba is a file and print server for blending Windows and UNIX� machines together without requiring a separate Windows NT/2000 Server. More information, and the download itself, can be accessed at http://wwws.sun.com/software/download/products/3e3af224.html.


Figure 3-6  NT Authentication Login Requirement Screen

NT Authentication Login Requirement Screen

RADIUS Authentication Module

This module allows for authentication using an external Remote Authentication Dial-In User Service (RADIUS) server. More information on this module can be found in the RADIUS Authentication Attributes chapter of the Sun ONE Identity Server Administration Guide.

Figure 3-7  RADIUS Authentication Login Requirement Screen

RADIUS Authentication Login Requirement Screen

SafeWord Authentication Module

This module allows for authentication using Secure Computing’s SafeWord� PremierAccess™ server software and SafeWord tokens. More information on this module can be found in the SafeWord Authentication Attributes chapter of the Sun ONE Identity Server Administration Guide.

Figure 3-8  SafeWord Authentication Login Requirement Screen

SafeWord Authentication Login Requirement Screen

SecurID Authentication Module

This module allows for authentication using RSA ACE/Server software and RSA SecurID authenticators. More information on this module can be found in the SecurID Authentication Attributes chapter of the Sun ONE Identity Server Administration Guide.

Figure 3-9  SecurID Authentication Login Requirement Screen

SecurID Authentication Login Requirement Screen

UNIX� Authentication Module

This Solaris only module allows for authentication using a user’s UNIX identification and password. More information on this module can be found in the Unix Authentication Attributes chapter of the Sun ONE Identity Server Administration Guide.

Figure 3-10  UNIX Authentication Login Requirement Screen

UNIX Authentication Login Requirement Screen


Authentication Service User Interface

The Authentication Service provides a web-based user interface for all out-of-the-box authentication modules installed in the Identity Server deployment. This interface provides a dynamic and customizable means for gathering authentication credentials by displaying the login requirement screens (based on the invoked authentication module) to a user requesting access. The interface is built using Sun ONE Application Framework (sometimes referred to as JATO), a Java 2 Enterprise Edition (J2EE) presentation framework used to help developers build functional web applications.


Note

Information on Sun ONE Application Framework 2.0 can be found at http://docs.sun.com/coll/S1_appframe20_en.


The User Interface Login URL

The Authentication Service user interface is accessed by entering a login URL into the Location Bar of a web browser. This URL is:

http://identity_server_host.domain_name:port/service_deploy_uri/UI/Login


Note

During installation, the service_deploy_uri is configured as amserver. This default service deployment URI will be used throughout this document.


The user interface login URL can also be appended with Login URL Parameters to define specific authentication methods or successful/failed authentication redirection URLs. Additional information on redirection URLs can be found in "Authentication Methods".

Login URL Parameters

A URL parameter is a name/value pair appended to the end of a URL. The parameter starts with a question mark (?) and takes the form name=value. A number of parameters can be combined in one login URL as in http://server_name.domain_name:port/amserver/UI/Login?module=LDAP&locale=ja&goto=http://www.sun.com. If more than one parameter exists, they are separated by an ampersand (&). The combinations though must adhere to the following guidelines:

The following sections describe parameters that, when appended to the The User Interface Login URL and typed in the Location bar of a web browser, achieve various authentication functionalities.


Tip

To simplify an authentication URL and parameters for distribution throughout an organization, an administrator might configure an HTML page with a simple URL that possesses links to the more complicated login URLs for all configured authentication methods.


goto Parameter

A goto=successful_authentication_URL parameter overrides the value defined in the Login Success URL of the Authentication Configuration Service. It will link to the specified URL when a successful authentication has been achieved. A goto=logout_URL parameter can also be used to link to a specified URL when the user is logging out. An example goto on a successful authentication URL might be http://server_name.domain_name:port/amserver/UI/Login?goto=http://www.sun.com/homepage.html. An example goto logout URL might be http://server_name.domain_name:port/amserver/UI/Logout?goto=http://www.sun.com/logout.html.


Note

There is an order of precedence in which Identity Server looks for successful authentication redirection URLs. Because these redirection URLs and their order are based on the method of authentication, this order (and related information) is detailed in "Authentication Methods".


gotoOnFail Parameter

A gotoOnFail=failed_authentication_URL parameter overrides the value defined in the Login Failed URL of the Authentication Configuration Service. It will link to the specified URL if a user has failed authentication. An example gotoOnFail URL might be http://server_name.domain_name:port/amserver/UI/Login?gotoOnFail=http://www.sun.com/auth_fail.html.


Note

There is an order of precedence in which Identity Server looks for failed authentication redirection URLs. Because these redirection URLs and their order are based on the method of authentication, this order (and related information) is detailed in "Authentication Methods".


org Parameter

The org=orgName parameter allows a user to authenticate as a user in the specified organization.


Tip

A user who is not already a member of the specified organization will receive an error message when they attempt to authenticate with the org parameter. A user profile, though, can be dynamically created in the Directory Server if all of the following are TRUE:

  • The User Profile attribute in the Core Authentication Service must be set to Dynamically Created.
  • The user must successfully authenticate to the required module.
  • The user does not already have a profile in Directory Server.

From this parameter, the correct login page (based on the organization and its locale setting) will be displayed. If this parameter is not set, the default is the top-level organization. An example org URL might be http://server_name.domain_name:port/amserver/UI/Login?org=sun.


Note

See the Sun ONE Identity Server Administration Guide for information on how to configure authentication for an organization.


user Parameter

The user=userName parameter forces authentication based on the module configured in User Authentication Configuration attribute of the user’s profile. For example, one user’s profile can be configured to authenticate using the Certification module while another user might be configured to authenticate using the LDAP module. Adding this parameter sends the user to their configured authentication process rather than the method configured for their organization. An example user URL might be http://server_name.domain_name:port/amserver/UI/Login?user=jsmith.


Note

See the Sun ONE Identity Server Administration Guide for information on how to configure authentication for a user.


role Parameter

A role=roleName parameter sends the user to the authentication process configured for the specified role. A user who is not already a member of the specified role will receive an error message when they attempt to authenticate with this parameter. An example role URL might be http://server_name.domain_name:port/amserver/UI/Login?role=manager.


Note

See the Sun ONE Identity Server Administration Guide for information on how to configure authentication for a role.


locale Parameter

Identity Server has the capability to display localized screens (translated into languages other than English) for the authentication process as well as for the console itself. The locale=localeName parameter allows the specified locale to take precedence over any other defined locales. The login locale is displayed by the client after searching for the configuration in the following places, order-specific:

  1. Value of locale parameter in Login URL
  2. The value of the locale=localeName parameter takes precedence over all other defined locales.

  3. Locale defined in user’s profile
  4. If there is no URL parameter, the locale is displayed based on the value set in the User Preferred Language attribute of the user profile.

  5. Locale defined in the HTTP header
  6. This locale is set by the web browser.

  7. Locale defined in Core Authentication Service
  8. This is the value of the Default Auth Locale attribute in the Core Authentication Service. More information can be found in the Sun ONE Identity Server Administration Guide..

  9. Locale defined in Platform Service
  10. This is the value of the Platform Locale attribute in the Platform Service. More information can be found in the Sun ONE Identity Server Administration Guide.

  11. Operating system locale

The locale derived from this pecking order is stored in the user’s session token and Identity Server uses it for loading the localized authentication module only. After successful authentication, the locale defined in the User Preferred Language attribute of the user’s profile is used. If none is set, the locale used for authentication will be carried over. An example module URL might be http://server_name.domain_name:port/amserver/UI/Login?locale=ja.


Note

Information on how to localize the screen text and error messages can be found in "Configuring Authentication Localization Properties" and "Configuring Console Localization Properties" of Chapter 6, "Service Management" in this manual.


module Parameter

The module=moduleName parameter allows authentication via the specified authentication module. Any of the modules listed in "Authentication Service Modules" can be specified although they must first be registered under the organization to which the user belongs and selected as one of that organization’s authentication modules in the Core Authentication Service. An example module URL might be http://server_name.domain_name:port/amserver/UI/Login?module=Unix.


Note

The authentication module names are case-sensitive when used in a URL parameter.


service Parameter

The service=serviceName parameter allows a user to authenticate via a service’s configured authentication scheme. Different authentication schemes can be configured for different services using the Authentication Configuration Service. For example, an online paycheck application might require authentication using the more secure Certificate Authentication Module while an organization’s employee directory application might require only the LDAP Authentication Module. An authentication scheme can be configured, and named, for each of these services. An example service URL might be http://server_name.domain_name:port/amserver/UI/Login?service=sv1.


Note

The Authentication Configuration Service is used to define a scheme for service-based authentication. More information on this module can be found in the Authentication Configuration Service Attributes chapter of the Sun ONE Identity Server Administration Guide.


arg Parameter

The arg=newsession parameter is used to end a user’s current session and begin a new one. The Authentication Service will destroy a user’s existing session token and perform a new login in one request. This option is typically used in the Anonymous Authentication module. The user first authenticates with an anonymous session, and then hits the register or login link. An example arg URL might be http://server_name.domain_name:port/amserver/UI/Login?arg=newsession.

authlevel Parameter

An authlevel=value parameter tells the Authentication Service to call a module with an authentication level equal to or greater than the specified authentication level value. Each authentication module is defined with a fixed integer authentication level. An example authlevel URL might be http://server_name.domain_name:port/amserver/UI/Login?authlevel=1.


Note

The Authentication Level is set in each module’s specific profile. More information on this module can be found in the Sun ONE Identity Server Administration Guide.


domain Parameter

This parameter allows a user to login to an organization identified as the specified domain. The specified domain must match the value defined in the Domain Name attribute of the organization’s profile. An example domain URL might be http://server_name.domain_name:port/amserver/UI/Login?domain=sun.com.


Tip

A user who is not already a member of the specified domain/organization will receive an error message when they attempt to authenticate with the org parameter. A user profile, though, can be dynamically created in the Directory Server if all of the following points are TRUE:

  • The User Profile attribute in the Core Authentication Service must be set to Dynamically Created.
  • The user must successfully authenticate to the required module.
  • The user does not already have a profile in Directory Server.

iPSPCookie Parameter

The iPSPCookie=yes parameter allows a user to login with a persistent cookie. A persistent cookie is one that continues to exist after the browser window is closed. In order to use this parameter, the organization to which the user is logging in must have Persistent Cookies enabled in their Core Authentication Service. Once the user authenticates and the browser is closed, the user can login with a new browser session and will be directed to console without having to reauthenticate. This will work until the value of the Persistent Cookie Max Time attribute specified in the Core Service elapses. An example iPSPCookie URL might be http://server_name.domain_name:port/amserver/UI/Login?org=example&iPSPCookie=yes.

IDTokenN Parameters

Identity Server has included this parameter option to enable a user to pass authentication credentials using a URL or HTML forms. With the IDTokenN=value parameters, a user can be authenticated without accessing the Authentication Service User Interface. This process is called Zero Page Login. Zero page login works only for authentication modules that use one login page. The values of IDToken0, IDToken1, ..., IDTokenN map to the fields on the authentication module’s login page. For example, the LDAP authentication module might use IDToken1 for the userID information, and IDToken2 for password information. In this case, the LDAP module IDTokenN URL would be: http://server_name.domain_name:port/amserver/UI/Login?module=LDAP&IDToken1=userID&IDToken2=password. (module=LDAP can be omitted if LDAP is the default authentication module.) For Anomymous authentication, the login URL parameter might be http://server_name.domain_name:port/amserver/UI/Login?module=Anonymous&IDToken1=anonymousUserID.


Note

The token names Login.Token0, Login.Token1, ..., Login.TokenN (from previous releases) are still supported but will be deprecated in a future release. It is recommended to use the new IDTokenN parameters.


File Types Of The User Interface

The Authentication Service User Interface uses JavaServer Pages™, XML for Authentication Module Configuration Files, JavaScript Files, Cascading Style Sheets, Image Files, and Localization Properties Files to convey graphical-based representations of the login requirement screens, logout screens, and error messages for each authentication module. Table 3-1 lists these file types, how they are used and in what directory they can be found.

Table 3-1  Authentication Service User Interface File Types

File Extension

Description

Location

.jsp

JavaServer Pages are HTML files with JATO tags that define Login and error message pages.

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

.xml

Authentication Module Configuration Files define login requirements.

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

.js

JavaScript Files contains server-side code for parsing.

IdentityServer_base/SUNWam/web-apps/services/js

.css

Cascading Style Sheets maintain consistency in color and text.

IdentityServer_base/SUNWam/web-apps/services/css

.gif/.jpg

Image Files to convey the look and feel of the interface.

IdentityServer_base/SUNWam/web-apps/services/login_images

.properties

Localization Properties Files for internationalization.

IdentityServer_base/SUNWam/locale

JavaServer Pages

All Authentication Service user interface screens are JavaServer Pages (JSP). Simply put, JSP are HTML files that contain additional code to generate dynamic content. More specifically, they contain HTML code to display static text and graphics, as well as application code to generate information. When the page is displayed in a web browser, it will contain both the static HTML content and dynamic content retrieved via the application code. There is one login page common to all the authentication modules in Identity Server; it is called Login.jsp.


Note

Notwithstanding the above, the Membership authentication module and the Self-registration authentication module each have their own login pages, membership.jsp and register.jsp, respectively.


The common login page dynamically displays the invoked authentication module’s required elements at run time. For example, when a user invokes the LDAP authentication module, the LDAP module header, user name field and password field are displayed.


Caution

When modifying JSP pages, all <, & and > characters must be escaped.


JSP Files

Identity Server includes a number of JSP for use by the Authentication Service user interface. Table 3-2 contains a list of them. They are located in IdentityServer_base/SUNWam/web-apps/services/config/auth/default.

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

authException.jsp

Informs the user that an error has occurred during authentication.

configuration.jsp

Informs the user that there has been a configuration error.

disclaimer.jsp

This is a sample, 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 chosen authentication module has been denied.

module_template.jsp

A customizable module page.

new_org.jsp

This page is displayed when a user witha valid session in one organization wants to login to another organization.

noConfig.jsp

Informs the user that no configuration has been defined/found for them.

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.

Authentication Module Configuration Files

The authentication module configuration file is an XML file that defines the requirements that each module seeks from a user for authentication. In other words, this file defines the login registration screens that a user might see when directed to authenticate (i.e. user name/password screen, change password screen, etc.). Each authentication module has its own configuration file located in the same directory as the JavaServer Pages, IdentityServer_base/SUNWam/web-apps/services/config/auth/default. Modifying elements in this file will automatically customize the authentication module’s interface. The file name follows the format modulename.xml; for example, SafeWord.xml or LDAP.xml where modulename is the name of the class without the package name. The syntax of the file itself follows the DTD format described in "Auth_Module_Properties.dtd".


Note

More information on the authentication module configuration file can be found in "Configuring The Authentication Module".


XML Files

Identity Server defines an authentication module configuration file for each of the default Authentication Service Modules. The included XML files, located in IdentityServer_base/SUNWam/web-apps/services/config/auth/default, are:

Table 3-3  List of Authentication Module Configuration Files 

File Name

Purpose

Anonymous.xml

For anonymous authentication although there are no specific credentials required to authenticate.

Application.xml

For Identity Server internal use only. Do not remove or modify this file.

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.

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.

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.

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.

JavaScript Files

Identity Server includes JavaScript files which are parsed within the Login.jsp. They can be found in IdentityServer_base/SUNWam/web-apps/services/js. Other, more customer-specific JavaScript files can be coded and accessed from this location.

JS Files

The JavaScript files used by the Authentication Service are detailed in Table 3-4. They can be found in IdentityServer_base/SUNWam/web-apps/services/js.

Table 3-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

Identity Server uses cascading style sheets (CSS) to define the look and feel of the user interface. Characteristics like fonts and font weights, background colors and link colors are specified in the CSS. They are located in IdentityServer_base/SUNWam/ web-apps/services/css.


Note

All JSP background colors, page layouts, and fonts are configurable using the style sheets located in IdentityServer_base/web-apps/services/css.


CSS Files

There are a number of browser-based CSS included with Identity Server. These CSS, detailed in Table 3-5, can be found in IdentityServer_base/SUNWam/web-apps/ services/css.

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

Image Files

The default user interface is branded with Sun Microsystems, Inc. logos and images. Identity Server has included these GIF files in IdentityServer_base/ SUNWam/web-apps/services/login_images. These images can be replaced with images relevant to other organizations. (JPG files can also be used.)

GIF Files

Table 3-6 contains a listing of the GIF images used for the user interface. These files can be found in IdentityServer_base/SUNWam/web-apps/services/css.

Table 3-6  List of Sun Microsystems Branded GIF Images

File Name

Purpose

Identity_LogIn.gif

Sun ONE Identity Server 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 ONE logo in the lower right corner.

Localization Properties Files

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.

PROPERTIES Files

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

Table 3-7  List of Localization Properties Files

File Name

Purpose

amAuth.properties

Defines the parent Core Authentication Service.

amAuthAnonymous.properties

Defines the Anonymous Authentication Module.

amAuthApplication.properties

For Identity Server internal use only. Do not remove or modify this file.

amAuthCert.properties

Defines the Certificate Authentication Module.

amAuthConfig.properties

Defines the Authentication Configuration Service.

amAuthContext.properties

Defines the localized error messages for the AuthContext Java class. For more information, see Authentication API For Java Applications.

amAuthContextLocal.properties

For Identity Server internal use only. Do not remove or modify this file.

amAuthHTTPBasic.properties

Defines the HTTP Basic Authentication Module.

amAuthLDAP.properties

Defines the LDAP Authentication Module.

amAuthMembership.properties

Defines the Membership Authentication Module.

amAuthNT.properties

Defines the NT Authentication Module.

amAuthRadius.properties

Defines the RADIUS Authentication Module.

amAuthSafeWord.properties

Defines the SafeWord Authentication Module.

amAuthSecurID.properties

Defines the SecurID Authentication Module.

amAuthUI.properties

Defines labels used in the authentication user inteface.

amAuthUnix.properties

Defines the UNIX� Authentication Module.

Customizing The Authentication User Interface

Many of the File Types Of The User Interface can be modified to bring a custom look and feel to the Authentication Service. The changes can be made on a number of levels, for example, to reflect authentication to different organizations via branding or to reflect different types of client applications. More specifically, one organization might customize their files to reflect their own logo and corporate colors while another might configure their service applications to have different authentication methods for security reasons. The JSP and properties files can be customized at the following levels:

The following sections contain the procedure for modifying JSP and properties files to create a customized Authentication Service user interface.


Note

Anytime one of the File Types Of The User Interface are modified, the web application archive (WAR) services.war needs to be redeployed. The first step is to manually jar the services directory, then undeploy the old WAR and redeploy the new WAR based on the deployed web container. For information on how to do this, see Appendix C, "WAR Files."


To Create New Directories For Custom Console Files

All custom JSP and XML properties files should be stored in directories based on their level of customization. The JSP and XML properties files stored in IdentityServer_base/SUNWam/web-apps/services/config/auth/default define the Authentication Service user interface for the top-level organization configured during installation. Modifying these files would change the interface that, for example, amadmin, the top level administrator user, would see when logged in.


Note

The directory that contains the Authentication Service user interface files for the top-level organization is configured during installation as default. This directory name can be changed to the actual name of the top-level organization for purposes of consistency with the Identity Server console.


The path to all directories containing customized user interface files begins from IdentityServer_base/SUNWam/web-apps/services/config/auth/default/.... Assuming this, the generic directory path, depending on the level of customization, is:

...organization_name OR organization_name_locale/any_sub_organization_directories OR any_sub_organization_directories_locale/any_client_type_directories/any_service_directories

Table 3-8 lists some levels of customization with the corresponding path to the directory where the modified files would be found.

Table 3-8  Directory Paths Based On Customization Level 

Level

Custom Directory Path Where Modified Files Live

Top-level Organization Customization

JSPs and XML files stored in default

Top-level Organization Customization Locale

JSPs and XML files stored in newly created default_locale

Sub-level Organization Customization

...2nd_level_organization_name1 OR 2nd_level_organization_name_locale1/sub_organization_name2 OR sub_organization_name_locale2/...

Service Customization

...2nd_level_organization_name1 OR 2nd_level_organization_name_locale1/sub_organization_name2 OR sub_organization_name_locale2/service_name

Client Type (HTML, WML, etc.) Customization

...2nd_level_organization_name1 OR 2nd_level_organization_name_locale1/sub_organization_name2 OR sub_organization_name_locale2/client_type

Table 3-8 defines directory paths based on a simple configuration (customize an organization’s branding or add WML files for multiple client types). Often, though, customization projects are not that straightforward. In the case that an organization wants to customize authentication for itself, a sub-organization and maybe a service, there is a specific path that these directories must follow. For example, let’s assume the following:

As there are two locales to be configured for Sun, modified files will reside in the directory based on their respective locale:

  1. IdentityServer_base/SUNWam/web-apps/services/config/auth/default/Sun_en/...
  2. IdentityServer_base/SUNWam/web-apps/services/config/auth/default/Sun_ja/...

Each of the two defined localized directories will contain the following three sub-directories storing English and Japanese files for the client types and service:

...sunONE/html/paycheck

...sunONE/wml/nokia/paycheck

...sunONE/wml/motorola/paycheck


Note

Customization of the authentication screens are only supported at the organization, sub-organization, client type and service levels. In a search for the correct module configuration properties files, Identity Server first searches for an org_name_locale_clienttype directory, an org_name_locale directory, and an org_name directory, followed by the default_locale_clienttype, default_locale and the default directories.


To Create A Custom Login Interface

All of the files in the IdentityServer_base/SUNWam/web-apps/services/config/auth/default directory need to be copied into the new directory(s) created in the prior section, "To Create New Directories For Custom Console Files." Customizing these files pertains to the actual interface for the organization as opposed to customizing the directories which pertains to the custom files storage directory. The authentication module configuration files are XML files based on the Auth_Module_Properties.dtd; the syntax of this DTD should be followed when customizing these files. Modifying elements in these files customize the authentication interface. More information on modifying this file can be found in "Configuring The Authentication Module". See Table 3-2 for a list of the available JSP templates.

Customizing The Default Login Page

Login.jsp and the authentication module configuration files contain certain elements that can be modified. Strong HTML skills and an understanding of web servers are a prerequisite for modifying these files.


Note

Although the JSP contain embedded JATO tags, it is not necessary to understand the Sun ONE Application Framework in order to customize them. For those who might be interested, though, an overview of the Application Framework can be found at http://docs.sun.com/source/817-0447-10/s1afovew.html.


They are located in IdentityServer_base/SUNWam/web-apps/services/config/auth/default/. Login.jsp is the common login page for all authentication modules, except Membership (membership.jsp) and self-registration (register.jsp), which dynamically displays the required user interface elements from the invoked authentication module’s credentials file at run time. For example, if the authentication method is LDAP, the appropriate module header, user name field and password field will be displayed.


Note

The processing logic is defined in the JATO ViewBean, com.sun.identity.authentication.UI.LoginViewBean.


styles.css    

The module header text and prompts used in the Authentication Service User Interface are formatted based on styles defined in styles.css (copied in Code Example 3-1). loginText defines the font formatting for Login.jsp. The style of these text fields can be changed by modifying styles.css.

Code Example 3-1  styles.css Style Sheet 

a:hover { text-decoration: underline}

footerText { font-family: Helvetica, Arial, Geneva, sans-serif; font-size: 9pt;

color: #333333}

loginText { font-family: Helvetica, Arial, Geneva, sans-serif}

mastheadLinks { font-family: Helvetica, Arial, Geneva, sans-serif; font-size: 9pt;

color: #4D59AB; text-decoration: none}

mastheadUsername { font-family: Helvetica, Arial, Geneva, sans-serif; font-size:

10pt; color: #333333; font-weight: bold}

input.buttonblue{ cursor: hand; font-family: verdana; background: #594fbf; color:

#ffffff; font-weight: bold; font-size: 10pt; padding: 1px 1px; margin: 0px 0px;

border: 0px}

doubleArrow { font-family: Arial, Helvetica, sans-serif; font-size: 10pt;

font-weight: bold; color: #594FBF}

mastheadSeparators { font-family: Helvetica, Arial, Geneva, sans-serif; color:

#A2A2A2; text-decoration: none; font-size: 12pt}

Module Header Text    

Each authentication module contains header text that displays the name of the module on the interface. In Figure 3-10, the module header text reads This server uses Unix Authentication. This field is defined as the StaticTextHeader in Login.jsp.

Code Example 3-2  Module Header Text Definition in Login.jsp

<!-- display authentication scheme -->

  <tr>

  <td colspan="2" width="140">&nbsp;</td>

  <td>

  <jato:content name="ContentStaticTextHeader">

   <jato:getDisplayFieldValue name='StaticTextHeader'

    defaultValue='Authentication' fireDisplayEvents='true'

    escape='false'/>

  </jato:content>

  </td>

  </tr>

The JATO ViewBean picks up the value for StaticTextHeader from the Authentication Module Configuration Files. If there is no value defined in this file, the defaultValue defined in Login.jsp (Authentication) is picked up.

Code Example 3-3 is the authentication module configuration file for Unix Authentication, Unix.xml. The value of header, defined in the Callbacks Element, is the module header text picked up by the JATO ViewBean. This field can be customized per module.

Code Example 3-3  Unix.xml Authentication Module Configuration File

<!DOCTYPE ModuleProperties PUBLIC "=//iPlanet//Authentication Module Properties XML

Interface 1.0 DTD//EN"

"jar://com/sun/identity/authentication/Auth_Module_Properties.dtd">

<ModuleProperties moduleName="Unix" version="1.0" >

<Callbacks length="2" order="1" timeout="60" header="This

server uses Unix Authentication" >

<NameCallback>

<Prompt> User Name: </Prompt>

</NameCallback>

<PasswordCallback echoPassword="false" >

<Prompt> Password: </Prompt>

</PasswordCallback>

</Callbacks>

<Callbacks length="0" order="2" timeout="120" header=" Your password has expired.

Please contact service desk to reset your password" error="true" />

</ModuleProperties>

Name Prompt and Input Field    

Each authentication module contains text to display next to the first credential input field, generally a prompt for the user’s name. In the Unix authentication interface (Figure 3-10), the name prompt text reads User Name. The name prompt field is defined by the txtPrompt in the first table data (td) tag (under <!---- text box display ----->) in Login.jsp as detailed in Code Example 3-4. The input field itself is defined by the second table data (td) tag.

Code Example 3-4  Name Prompt And Field Definition in Login.jsp 

<jato:content name="textBox">

  <!---- text box display ----->

  <tr>

  <form name="frm<jato:text name="txtIndex" />" action="blank"

   onSubmit="defaultSubmit(); return false;">

  <td class="loginText" width="120">

<label for="IDToken<jato:text name="txtIndex" />">

<jato:text name="txtPrompt" defaultValue="User name:" escape="false" />

<jato:content name="isRequired">

<font color="#0000ff">*</font>

</jato:content>

</label>

  </td>

  

  <td class="loginText" width="20">&nbsp;</td>

  <td class="loginText">

   <input type="text" name="IDToken<jato:text name="txtIndex" />"

id="IDToken<jato:text name="txtIndex" />"

    value="" size="20">

  </td>

  </form>

  </tr>

  <tr><td colspan="3">&nbsp;</td></tr>

  <!---- end of textBox ---->

  </jato:content>

The JATO ViewBean picks up the actual value for txtPrompt, not from Login.jsp but, from the Authentication Module Configuration Files. If there is no value defined in this file, the defaultValue defined in Login.jsp (User name:) is picked up.

Code Example 3-3 is the authentication module configuration file for Unix Authentication, Unix.xml. The value of prompt, defined in the NameCallback Element, is the text picked up by the JATO ViewBean to define the input field. In this case, the name prompts are defined similarly: User name: in Login.jsp and User Name: in Unix.xml. This field can be customized per module.

Password Prompt and Input Field    

Each authentication module contains text to display next to the second credential field, generally a prompt for the user’s password. In the Unix authentication interface (Figure 3-10), the password prompt text reads Password. The password prompt field is defined by the txtPrompt in the first table data (td) tag (under <!---- password display ----->) in Login.jsp as detailed in Code Example 3-5. The input field itself is defined by the second table data (td) tag.

Code Example 3-5  Password Prompt And Field Definition in Login.jsp 

<jato:content name="password">

  <!---- password display ---->

  <tr>

  <form name="frm<jato:text name="txtIndex" />" action="blank"

   onSubmit="defaultSubmit(); return false;">

  <td class="loginText" width="120">

<label for="IDToken<jato:text name="txtIndex" />">

<jato:text name="txtPrompt" defaultValue="Password:" escape="false" />

<jato:content name="isRequired">

<font color="#0000ff">*</font>

</jato:content>

</label>

  </td>

  <td class="loginText" width="20">&nbsp;</td>

  <td class="loginText">

   <input type="password" name="IDToken<jato:text name="txtIndex" />"

id="IDToken<jato:text name="txtIndex" />"

    value="" size="20">

  </td>

  </form>

  </tr>

  <tr><td colspan="3">&nbsp;</td></tr>

  <!---- end of password ---->

  </jato:content>

The JATO ViewBean picks up the value for txtPrompt from the Authentication Module Configuration Files. If there is no value defined in this file, the defaultValue defined in Login.jsp (Password:) is picked up.

Code Example 3-3 is the authentication module configuration file for Unix Authentication, Unix.xml. The value of prompt, defined in the PasswordCallback Element, is the prompt text picked up by the JATO ViewBean. In this case, the name prompts are the same: Password: in Login.jsp and Password: in Unix.xml. This field can be customized per module.

Choice Prompt and Value Fields    

Figure 3-11 pictures an interface where multiple authentication modules are displayed and the user is prompted to choose one. There are a number of reasons that choices are displayed; for example, the Membership authentication module defines choices when a user is self-registering with a user name that already exists. They are then offered a sample list of other user names from which to choose or given the option to create a new one. The choice prompt field for Membership authentication is defined by the txtPrompt in the first table data (td) tag (under <!---- choice value display ----->) in membership.jsp as detailed in Code Example 3-6. The input field type is defined by the second table data (td) tag as radio buttons. This option can be changed to a check box by switching the input type value of “radio” (in both the selectedChoice and unselectedChoice tags) with the value “checkbox”.

Code Example 3-6  Choice Prompt And Value Fields Definition in membership.jsp 

<!-- choice value display -->

<tr>

<form name="frm<jato:text name="txtIndex" />" action="blank"

onSubmit="defaultSubmit(); return false;">

<td class="loginText">

<label for="IDToken<jato:text name="txtIndex" />">

<jato:text name="txtPrompt" defaultValue="RadioButton:" escape="false" />

<jato:content name="isRequired">

<font color ="#0000ff">*</font>

</jato:content>

</label>

</td>

<td class="loginText" width="20">&nbsp;</td>

<td class="loginText">

<jato:tiledView name="tiledChoices"

type="com.sun.identity.authentication.UI.CallBackChoiceTiledView">

<jato:content name="selectedChoice">

<input type="radio"

name="IDToken<jato:text name="txtParentIndex" />"

id="IDToken<jato:text name="txtParentIndex" />"

value="<jato:text name="txtIndex" />"

checked><jato:text name="txtChoice" /><br>

</jato:content>

<jato:content name="unselectedChoice">

<input type="radio"

name="IDToken<jato:text name="txtParentIndex" />"

id="IDToken<jato:text name="txtParentIndex" />"

value="<jato:text name="txtIndex" />"

><jato:text name="txtChoice" /><br>

</jato:content>

</jato:tiledView>

</td>

</form>

</tr>

<tr><td colspan="3">&nbsp;</td></tr>

<!-- end of choice -->

The JATO ViewBean picks up the value for txtPrompt from the Authentication Module Configuration Files. If there is no value defined in this file, the defaultValue defined in membership.jsp (RadioButton:) is picked up.


Caution

If changing the radio buttons to checkboxes, remember to change the value of txtPrompt in membership.jsp also.


Code Example 3-7 is an extract of the authentication module configuration file for Membership Authentication, Membership.xml. The value of prompt, defined in the ChoiceCallback Element, is the prompt text picked up by the JATO ViewBean. In this case, the name prompts are different: RadioButton: in membership.jsp and A user already exists with the user name you entered. Please choose one of the following user names, or create your own: in Membership.xml. This field can be customized per module.

Code Example 3-7  Membership.xml Configuration File Extract 

...

<Callbacks length="2" order="17" timeout="120" header="Self Registration" >

<ChoiceCallback attribute="uid" >

<Prompt>A user already exists with the user name you entered. &lt;BR&gt;Please choose one of the following user names, or create your own:</Prompt>

<ChoiceValues>

<ChoiceValue>

<Value>Create My Own</Value>

</ChoiceValue>

</ChoiceValues>

</ChoiceCallback>

<ConfirmationCallback>

<OptionValues>

<OptionValue>

<Value> Submit </Value>

</OptionValue>

</OptionValues>

</ConfirmationCallback>

</Callbacks>

...

Logos And Branding Images    

Custom images can be used for corporate logos and branding. Any new GIF or JPG images must be placed in IdentityServer_base/SUNWam/web-apps/services/login_images. To access this new image, edit the appropriate section of the authentication module configuration file. There are a number of places where this can be changed. Code Example 3-8 contains the image source attributes from Membership.xml, the Membership authentication module configuration file. In this code, logo_sun.gif and Identity_LogIn.gif would be replaced with a custom logo and title, respectively. The spacer.gif tags can be deleted or modified as needed. The default Sun Microsystems logo in the upper left corner and the default Sun ONE Identity Server title across the top of the interface are pictured in Figure 3-4.

Code Example 3-8  Image Source Attributes in Membership.xml Extract 

...

<!-- branding -->

<tr>

<td width="110"><img src="<%= ServiceURI %>/login_images/logo_sun.gif" width="110"

height="82" alt="Sun Microsystems Logo"></td>

<td><img src="<%= ServiceURI %>/login_images/spacer.gif" width="9" height="1"

alt=""></td>

<td valign="bottom" bgcolor="#ACACAC" width="100%"><img

src="<%= ServiceURI %>/login_images/Identity_LogIn.gif" width="300"

height="30" alt="Sun ONE Identity Server"></td>

</tr>

<tr>

<td colspan="3"><img src="<%= ServiceURI %>/login_images/spacer.gif" width="1"

height="39" alt=""></td>

</tr>

...

The final image attribute is in Login.jsp. Code Example 3-9 can be moved around the JSP and the image will be displayed wherever in the code it is placed.

Code Example 3-9  Image Source Attribute in Login.jsp

<jato:content name="ContentImage">

<!-- customized image defined in properties file -->

<p><img name="IDImage"

src="<jato:getDisplayFieldValue name='Image'/>" alt=""></p>

</jato:content>

Code Example 3-9 refers to an image file defined in the authentication module configuration file. The XML code for this image would be written as:

<Callbacks length="3" order="1" timeout="120" header="Sample Module" image="MyCustomImage.gif">.

Password Reset Link    

It is possible put add a link on the LDAP Authentication module login page to the Password Reset Service. This allows a user to reset their password prior to authentication. The following line can be placed below the Submit Button Code in Code Example 3-10.

<a “href=<console_proto>://console_host.console_domain:console_port/password_reset_URI >Forgot your password?</a>

Code Example 3-10  Submit Button Code From Login.jsp 

<jato:content name="ContentButtonLogin">

  <!-- Submit button -->

  <jato:content name="hasButton">

  <script language="javascript">

   defaultBtn = '<jato:text name="defaultBtn" />';

  </script>

  <tr>

  <td colspan="2">&nbsp;</td>

  <td align="right">

   <table border="0" cellpadding="2" cellspacing="0">

   <tr>

   <jato:tiledView name="tiledButtons"

    type="com.sun.identity.authentication.UI.ButtonTiledView">

   <td>

    <script language="javascript">

     markupButton(

      '<jato:text name="txtButton" />',

      "javascript:LoginSubmit('<jato:text name="txtButton" />')");

    </script>

   </td>

   </jato:tiledView>

   </tr>

   </table>

  </td>

  </tr>

  <!---- end of hasButton ---->

  </jato:content>

  <jato:content name="hasNoButton">

  <tr>

  <td colspan="2">&nbsp;</td>

  <td align="right">

   <script language="javascript">

    markupButton(

     '<jato:text name="lblSubmit" />',

       "javascript:LoginSubmit('<jato:text name="lblSubmit" />')");

   </script>

  </td>

  </tr>

  <!---- end of hasNoButton ---->

  </jato:content>

  <!---- end of ContentButtonLogin ---->

  </jato:content>

Log In Button    

The following modifications can be made to the default Log In button displayed on each authentication interface screen. The button color and/or background can be customized in any of the following stylesheets located in IdentityServer_base/SUNWam/web-apps/services/css.

Code Example 3-11 is extracted from css_ns4sol.css. To change the background color, in the appropriate style sheet, change the color values for .button-content-enabled { background-color: #CCC; } and for a.button-link:link, a.button-link:visited { color: #000; background-color: #CCC; text-decoration: none; }.

Code Example 3-11  css_ns4sol.css Extraction 

/* BUTTONS */

/* Regular Button - Enabled */

.button-frame-enabled { background-color: #000; }

.button-content-enabled { background-color: #CCC; }

.button-link-enabled-text { color: #000; margin: 4px 0px; font-weight: bold; }

a.button-link:link, a.button-link:visited { color: #000; background-color: #CCC;

text-decoration: none; }

a.button-link:active { color: #000; background-color: #999; text-decoration: none;}

/* Regular Button - Disabled */

.button-frame-disabled { background-color: #999; }

.button-content-disabled { background-color: #CCC; }

.button-link-disabled-text { color: #999; margin: 4px 0px; font-weight: bold; }

By default, the login button reads Log In. To change this text on a global level, the amAuthUI.properties file, the authentication service’s console localization properties file, would be modified.


Note

amAuthUI.properties is defined in "Configuring Authentication Localization Properties". More information can be found in "Configuring Console Localization Properties" of Chapter 6, "Service Management," in this manual.


Code Example 3-12 is an extraction from amAuthUI.properties. Notice the default value is LogIn=Log In. For an example, the value Log In can be changed to Submit.

Code Example 3-12  amAuthUI.properties Extract

...

Submit=Submit

LogIn=Log In

NewUser=New User

Reset=Reset Form

Cancel=Cancel

Agree=Agree

Disagree=Disagree

Yes=Yes

No=No

Continue=Continue

...

The button text can also be changed per module. If each authentication module needs to display different text, each authentication module configuration file needs to be modified with a ConfirmationCallback Element. The value for the Callbacks length can be increased, if necessary. Code Example 3-17 is the authentication module configuration file for Membership, Membership.xml. It contains an example of the Confirmation Callback.


Authentication Methods

The Authentication Service provides different ways in which authentication can be applied. These different authentication methods can be accessed by specifying Login URL Parameters, or through the Authentication Programming Interfaces. Access using parameters and a URL is discussed in "The User Interface Login URL". Access via the API is discussed in "Authentication Programming Interfaces".


Note

Specific information on how to assign an authentication method using the Identity Server console can be found in the Sun ONE Identity Server Administration Guide.


The following sections detail the different authentication methods with configured login URLs and redirection URL order of precedence for each. The authentication methods are:

For each of these methods, the user can either pass or fail the authentication. Once the determination has been made, each method follows this procedure. Step 1 through Step 3 follows a successful authentication; Step 4 follows both successful and failed authentication.

  1. Identity Server confirms whether the authenticated user(s) is defined in the Directory Server data store and whether the profile is active.
  2. The User Profile attribute in the Core Authentication Service can be defined as Required, Dynamically Configured or Ignored. Following a succesful authentication, Identity Server confirms whether the authenticated user(s) is defined in the Directory Server data store and, if the User Profile value is Required, confirms that the profile is active. (This is the default case.) If the User Profile is Dynamically Configured, the Authentication Service will create the user profile in the Directory Server data store. If the User Profile is set to Ignore, the user validation will not be done.

  3. Execution of the Authentication Post Processing SPI is accomplished.
  4. The Core Authentication Service contains an Authentication PostProcessing Class attribute which may contain the authentication post-processing class name as its value. AMPostAuthProcessInterface is the post-processing interface. It can be executed on either successful or failed authentication or on logout. More information on this interface can be found in "Implementing Authentication Post Processing".

  5. The following properties are added to, or updated in, the session token and the user’s session is activated.
    • Organization—This is the DN of the organization to which the user belongs.
    • Principal—This is the DN of the user.
    • Principals—This is a list of names to which the user has authenticated. (This property may have more then one value defined as a pipe separated list.)
    • UserId—This is the user’s DN as returned by the module, or in the case of modules other than LDAP or Membership, the user name. (All Principals must map to the same user. The UserID is the user DN to which they map.)
    • UserToken—This is a user name. (All Principals must map to the same user. The UserToken is the user name to which they map.)
    • Host—This is the host name or IP address for the client.
    • authLevel—This is the highest level to which the user has authenticated.
    • AuthType—This is a pipe separated list of authentication modules to which the user has authenticated (i.e.: module1|module2|module3).
    • clientType—This is the device type of the client browser.
    • Locale—This is the locale of the client.
    • CharSet—This is the determined character set for the client.
    • Role—Applicable for role-based authentication only, this is the role to which the user belongs.
    • Service—Applicable for service-based authentication only, this is the service to which the user belongs.
    • loginURL—This is the client’s login URL.
  6. Identity Server looks for information on where to redirect the user after either a successful or failed authentication.
  7. URL redirection can be to either an Identity Server page or a URL. The redirection is based on an order of precedence in which Identity Server looks for redirection based on the authentication method and whether the authentication has been successful or has failed. This order is detailed in the URL redirection portions of the following authentication methods sections.


    Tip

    One more authentication method is a functionality of the Policy Service. "Policy-Based Resource Management" of Chapter 7, "Policy Service" in this manual contains information on resource-based authentication.


Organization-based Authentication

This method of authentication allows a user to authenticate to an organization or sub-organization. It is the default method of authentication for Identity Server. The authentication method for an organization is set by registering the Core Authentication Service to the organization and defining the Organization Authentication Configuration attribute. More information on how this is done can be found in the Authentication Options chapter of the Sun ONE Identity Server Administration Guide.

Organization-based Authentication Login URLs

The organization for authentication can be specified in the The User Interface Login URL by defining the org Parameter or the domain Parameter. The organization of a request for authentication is determined from the following, in order of precedence:

  1. The domain parameter.
  2. The org parameter.
  3. The value of the DNS Alias Names (Organization alias names) attribute in the Administration Service.

After calling the correct organization, the authentication module(s) to which the user will authenticate are retrieved from the Organization Authentication Configuration attribute in the Core Authentication Service. The login URLs used to specify and initiate organization-based authentication are:

If there is no defined parameter, the organization will be determined from the server host and domain specified in the login URL. More information on these parameters can be found in "Login URL Parameters".

Organization-based Authentication Redirection URLs

Upon a successful or failed organization-based authentication, Identity Server looks for information on where to redirect the user. Following is the order of precedence in which the application will look for this information.

Successful Organization-based Authentication Redirection URLs

The redirection URL for successful organization-based authentication is detemined by checking the following places in order of precedence:

  1. A URL set by the authentication module.
  2. A URL set by a goto Login URL parameter.
  3. A URL set in the clientType custom files for the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
  4. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s role entry.
  5. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s organization entry.
  6. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute as a global default.
  7. A URL set in the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
  8. A URL set in the iplanet-am-auth-login-success-url attribute of the user’s role entry.
  9. A URL set in the iplanet-am-auth-login-success-url attribute of the user’s organization entry.
  10. A URL set in the iplanet-am-auth-login-success-url attribute as a global default.
Failed Organization-based Authentication Redirection URLs

The redirection URL for failed organization-based authentication is detemined by checking the following places in the following order:

  1. A URL set by the authentication module.
  2. A URL set by a gotoOnFail Login URL parameter.
  3. A URL set in the clientType custom files for the iplanet-am-user-failure-url attribute of the user’s entry (amUser.xml).
  4. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
  5. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s organization entry.
  6. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute as a global default.
  7. A URL set for the iplanet-am-user-failure-url attribute in the user’s entry (amUser.xml).
  8. A URL set for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
  9. A URL set for the iplanet-am-auth-login-failure-url attribute of the user’s organization entry.
  10. A URL set for the iplanet-am-auth-login-failure-url attribute as the global default.

Role-based Authentication

This method of authentication allows a user to authenticate to a role (either static or filtered) within an organization or sub-organization.


Note

The Authentication Configuration Service must first be registered to the organization before it can be registered as an instance to the role. More information on how this is done can be found in the Authentication Configuration section of Chapter 7 in the Sun ONE Identity Server Administration Guide.


For authentication to be successful, the user must belong to the role and they must authenticate to each module defined in the Authentication Configuration Service instance configured for that role. For each instance of role-based authentication, the following attributes can be specified:

Role-based Authentication Login URLs

Role-based authentication can be specified in the The User Interface Login URL by defining a role Parameter. After calling the correct role, the authentication module(s) to which the user will authenticate are retrieved from the Authentication Configuration Service instance defined for the role.

The login URLs used to specify and initiate this role-based authentication are:

If there is no configured org Parameter, the organization to which the role belongs will be determined from the server host and domain specified in the login URL itself. More information on these parameters can be found in "Login URL Parameters".

Role-based Authentication Redirection URLs

Upon a successful or failed role-based authentication, Identity Server looks for information on where to redirect the user. Following is the order of precedence in which the application will look for this information.

Successful Role-based Authentication Redirection URLs

The redirection URL for successful role-based authentication is detemined by checking the following places in the following order:

  1. A URL set by the authentication module.
  2. A URL set by a goto Login URL parameter.
  3. A URL set in the clientType custom files for the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
  4. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the role to which the user has authenticated.
  5. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of another role entry of the authenticated user. (This option is a fallback if the previous redirection URL fails.)
  6. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s organization entry.
  7. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute as a global default.
  8. A URL set in the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
  9. A URL set in the iplanet-am-auth-login-success-url attribute of the role to which the user has authenticated.
  10. A URL set in the iplanet-am-auth-login-success-url attribute of another role entry of the authenticated user. (This option is a fallback if the previous redirection URL fails.)
  11. A URL set in the iplanet-am-auth-login-success-url attribute of the user’s organization entry.
  12. A URL set in the iplanet-am-auth-login-success-url attribute as a global default.
Failed Role-based Authentication Redirection URLs

The redirection URL for failed role-based authentication is detemined by checking the following places in the following order:

  1. A URL set by the authentication module.
  2. A URL set by a goto Login URL parameter.
  3. A URL set in the clientType custom files for the iplanet-am-user-failure-url attribute of the user’s profile (amUser.xml).
  4. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the role to which the user has authenticated.
  5. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of another role entry of the authenticated user. (This option is a fallback if the previous redirection URL fails.)
  6. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s organization entry.
  7. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute as a global default.
  8. A URL set in the iplanet-am-user-failure-url attribute of the user’s profile (amUser.xml).
  9. A URL set in the iplanet-am-auth-login-failure-url attribute of the role to which the user has authenticated.
  10. A URL set in the iplanet-am-auth-login-failure-url attribute of another role entry of the authenticated user. (This option is a fallback if the previous redirection URL fails.)
  11. A URL set in the iplanet-am-auth-login-failure-url attribute of the user’s organization entry.
  12. A URL set in the iplanet-am-auth-login-failure-url attribute as a global default.

Service-based Authentication

This method of authentication allows a user to authenticate to a specific service or application registered to an organization or sub-organization. The service is configured as a Service Instance within the Authentication Configuration Service and is associated with an Instance Name. For authentication to be successful, the user must authenticate to each module defined in the Authentication Configuration Service instance configured for the service. For each instance of service-based authentication, the following attributes can be specified:

Service-based Authentication Login URLs

Service-based authentication can be specified in the The User Interface Login URL by defining a service Parameter. After calling the service, the authentication module(s) to which the user will authenticate are retrieved from the Authentication Configuration Service instance defined for the service.

The login URLs used to specify and initiate this service-based authentication are:

If there is no configured org parameter, the organization will be determined from the server host and domain specified in the login URL itself. More information on these parameters can be found in "Login URL Parameters".

Service-based Authentication Redirection URLs

Upon a successful or failed service-based authentication, Identity Server looks for information on where to redirect the user. Following is the order of precedence in which the application will look for this information.

Successful Service-based Authentication Redirection URLs

The redirection URL for successful service-based authentication is detemined by checking the following places in the following order:

  1. A URL set by the authentication module.
  2. A URL set by a goto Login URL parameter.
  3. A URL set in the clientType custom files for the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
  4. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the service to which the user has authenticated.
  5. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s role entry.
  6. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s organization entry.
  7. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute as a global default.
  8. A URL set in the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
  9. A URL set in the iplanet-am-auth-login-success-url attribute of the service to which the user has authenticated.
  10. A URL set in the iplanet-am-auth-login-success-url attribute of the user’s role entry.
  11. A URL set in the iplanet-am-auth-login-success-url attribute of the user’s organization entry.
  12. A URL set in the iplanet-am-auth-login-success-url attribute as a global default.
Failed Service-based Authentication Redirection URLs

The redirection URL for failed service-based authentication is detemined by checking the following places in the following order:

  1. A URL set by the authentication module.
  2. A URL set by a goto Login URL parameter.
  3. A URL set in the clientType custom files for the iplanet-am-user-failure-url attribute of the user’s profile (amUser.xml).
  4. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the service to which the user has authenticated.
  5. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
  6. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s organization entry.
  7. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute as a global default.
  8. A URL set in the iplanet-am-user-failure-url attribute of the user’s profile (amUser.xml).
  9. A URL set in the iplanet-am-auth-login-failure-url attribute of the service to which the user has authenticated.
  10. A URL set in the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
  11. A URL set in the iplanet-am-auth-login-failure-url attribute of the user’s organization entry.
  12. A URL set in the iplanet-am-auth-login-failure-url attribute as a global default.

User-based Authentication

This method of authentication allows a user to authenticate to an authentication process configured specifically for them. The process is configured as a value of the User Authentication Configuration attribute in the user’s profile. For authentication to be successful, the user must authenticate to each module defined.

User-based Authentication Login URLs

User-based authentication can be specified in the The User Interface Login URL by defining a user Parameter. After calling the correct user, the authentication module(s) to which the user will authenticate are retrieved from the User Authentication Configuration instance defined for them.

The login URLs used to specify and initiate this role-based authentication are:

If there is no configured org Parameter, the organization to which the role belongs will be determined from the server host and domain specified in the login URL itself. More information on these parameters can be found in "Login URL Parameters".

User Alias List Attribute

On receiving a request for user-based authentication, the Authentication Service first verifies that the user is a valid user and then retrieves the Authentication Configuration data for them. In the case where there is more then one valid user profile associated with the value of the user Login URL parameter, all profiles must map to the specified user. The User Alias Attribute (iplanet-am-user-alias-list) in the User profile is where other profiles belonging to the user can be defined. If mapping fails, the user is denied a valid session. The exception would be if one of the users is a Super Admin whereby the user mapping validation is not done and the user is given Super Admin rights.

User-based Authentication Redirection URLs

Upon a successful or failed user-based authentication, Identity Server looks for information on where to redirect the user. Following is the order of precedence in which the application will look for this information.

Successful User-based Authentication Redirection URLs

The redirection URL for successful user-based authentication is detemined by checking the following places in order of precedence:

  1. A URL set by the authentication module.
  2. A URL set by a goto Login URL parameter.
  3. A URL set in the clientType custom files for the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
  4. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s role entry.
  5. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s organization entry.
  6. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute as a global default.
  7. A URL set in the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
  8. A URL set in the iplanet-am-auth-login-success-url attribute of the user’s role entry.
  9. A URL set in the iplanet-am-auth-login-success-url attribute of the user’s organization entry.
  10. A URL set in the iplanet-am-auth-login-success-url attribute as a global default.
Failed User-based Authentication Redirection URLs

The redirection URL for failed user-based authentication is detemined by checking the following places in the following order:

  1. A URL set by the authentication module.
  2. A URL set by a gotoOnFail Login URL parameter.
  3. A URL set in the clientType custom files for the iplanet-am-user-failure-url attribute of the user’s entry (amUser.xml).
  4. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
  5. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s organization entry.
  6. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute as a global default.
  7. A URL set for the iplanet-am-user-failure-url attribute in the user’s entry (amUser.xml).
  8. A URL set for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
  9. A URL set for the iplanet-am-auth-login-failure-url attribute of the user’s organization entry.
  10. A URL set for the iplanet-am-auth-login-failure-url attribute as the global default.

Authentication Level-based Authentication

This method of authentication allows an administrator to specify the security level of the modules to which identities can authenticate. Each authentication module has a separate Authentication Level attribute and the value of this attribute can be defined as any valid integer. With Authentication Level-based authentication, the Authentication Service displays a module login page with a menu containing the authentication modules that have authentication levels equal to or greater then the value specified in the Login URL parameter. Users can select a module from the presented list. Figure 3-11 illustrates this list of modules based on authentication level. Once the user selects a module, the remaining process is based on Module-based Authentication as discussed on .

Figure 3-11  Authentication Level-based Authentication Login Screen

Authentication Level-based Authentication Login Screen

Authentication Level-based Authentication Login URLs

Authentication level-based authentication can be specified in The User Interface Login URL by defining a authlevel Parameter. After calling the login screen with the relevant list of modules, the user must choose one with which to authenticate. The login URLs used to specify and initiate authentication level-based authentication are:

If there is no configured org parameter, the organization to which the user belongs will be determined from the server host and domain specified in the login URL itself. More information on these parameters can be found in "Login URL Parameters".

Authentication Level-based Authentication Redirection URLs

Upon a successful or failed authentication level-based authentication, Identity Server looks for information on where to redirect the user. Following is the order of precedence in which the application will look for this information.

Successful Authentication Level-based Authentication Redirection URLs

The redirection URL for successful authentication level-based authentication is detemined by checking the following places in order of precedence:

  1. A URL set by the authentication module.
  2. A URL set by a goto Login URL parameter.
  3. A URL set in the clientType custom files for the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
  4. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s role entry.
  5. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s organization entry.
  6. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute as a global default.
  7. A URL set in the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
  8. A URL set in the iplanet-am-auth-login-success-url attribute of the user’s role entry.
  9. A URL set in the iplanet-am-auth-login-success-url attribute of the user’s organization entry.
  10. A URL set in the iplanet-am-auth-login-success-url attribute as a global default.
Failed Authentication Level-based Authentication Redirection URLs

The redirection URL for failed authentication level-based authentication is detemined by checking the following places in the following order:

  1. A URL set by the authentication module.
  2. A URL set by a gotoOnFail Login URL parameter.
  3. A URL set in the clientType custom files for the iplanet-am-user-failure-url attribute of the user’s entry (amUser.xml).
  4. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
  5. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s organization entry.
  6. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute as a global default.
  7. A URL set for the iplanet-am-user-failure-url attribute in the user’s entry (amUser.xml).
  8. A URL set for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
  9. A URL set for the iplanet-am-auth-login-failure-url attribute of the user’s organization entry.
  10. A URL set for the iplanet-am-auth-login-failure-url attribute as the global default.

Module-based Authentication

This method of authentication allows a user to specify the module to which they will authenticate. The specified module must be registered to the organization or sub-organization that the user is accessing. This is configured in the Organization Authentication Modules attribute of the organization’s Core Authentication Service. On receiving this request for module-based authentication, the Authentication Service verifies that the module is correctly configured as noted, and if the module is not defined, the user is denied access.


Note

See the Sun ONE Identity Server Administration Guide for more information on how to register the authentication services and modules using the Identity Server console.


Module-based Authentication Login URLs

Module-based authentication can be specified in The User Interface Login URL by defining a module Parameter. The login URLs used to specify and initiate module-based authentication are:

If there is no configured org paramter, the organization to which the user belongs will be determined from the server host and domain specified in the login URL itself. More information on these parameters can be found in "Login URL Parameters".

Module-based Authentication Redirection URLs

Upon a successful or failed module-based authentication, Identity Server looks for information on where to redirect the user. Following is the order of precedence in which the application will look for this information.

Successful Module-based Authentication Redirection URLs

The redirection URL for successful module-based authentication is detemined by checking the following places in order of precedence:

  1. A URL set by the authentication module.
  2. A URL set by a goto Login URL parameter.
  3. A URL set in the clientType custom files for the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
  4. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s role entry.
  5. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s organization entry.
  6. A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute as a global default.
  7. A URL set in the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
  8. A URL set in the iplanet-am-auth-login-success-url attribute of the user’s role entry.
  9. A URL set in the iplanet-am-auth-login-success-url attribute of the user’s organization entry.
  10. A URL set in the iplanet-am-auth-login-success-url attribute as a global default.
Failed Module-based Authentication Redirection URLs

The redirection URL for failed module-based authentication is detemined by checking the following places in the following order:

  1. A URL set by the authentication module.
  2. A URL set by a gotoOnFail Login URL parameter.
  3. A URL set in the clientType custom files for the iplanet-am-user-failure-url attribute of the user’s entry (amUser.xml).
  4. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
  5. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s organization entry.
  6. A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute as a global default.
  7. A URL set for the iplanet-am-user-failure-url attribute in the user’s entry (amUser.xml).
  8. A URL set for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
  9. A URL set for the iplanet-am-auth-login-failure-url attribute of the user’s organization entry.
  10. A URL set for the iplanet-am-auth-login-failure-url attribute as the global default.


Authentication Features

This section defines a number of features that can be enabled and/or configured. They include the following:

Account Locking

The Authentication Service provides a feature where a user will be locked out from authenticating after n failures. This feature is turned off by default, but can be enabled using the Identity Server console.


Note

Only modules that throw an Invalid Password Exception can leverage the Account Locking feature.


The Core Authentication Service contains attributes for enabling and customizing this feature including (but not limited to):

Email notifications are sent to administrators regarding any account lockouts. (Account locking activities are also logged.) For more information on the account locking attributes, see theSun ONE Identity Server Administration Guide.


Note

For special instructions when using this feature on a Microsoft� Windows 2000 operating system, see "Simple Mail Transfer Protocol (SMTP)" in Appendix A, "AMConfig.properties File," in this manual.


Identity Server supports two types of account locking are supported: Physical Locking and Memory Locking. These are defined in the next sections.

Physical Locking

This is the default locking behavior for Identity Server. The locking is initiated by changing the status of a LDAP attribute in the user’s profile to inactive. The Lockout Attribute Name attribute defines the LDAP attribute used for locking purposes. See the Sun ONE Identity Server Administration Guide for more information on configuring physical locking.


Note

An aliased user is one that is mapped to an existing LDAP user profile by configuring the User Alias List Attribute (iplanet-am-user-alias-list in amUser.xml) in the LDAP profile. Aliased users can be verified by adding iplanet-am-user-alias-list to the Alias Search Attribute Name field in the Core Authentication Service. That said, if an aliased user is locked out, the actual LDAP profile to which the user is aliased will be locked. This pertains only to physical lockout with authentication modules other than LDAP and Membership.


Memory Locking

Memory locking is enabled by changing the Login Failure Lockout Duration attribute to a value greater then 0. The user’s account is then locked in memory for the number of minutes specified. The account will be unlocked after the time period has passed. Following are some special considerations when using the memory locking feature:

Authentication Module Chaining

One or more authentication modules can be configured so a user must pass authentication credentials to all of them. This is referred to as authentication chaining. Authentication chaining in Identity Server is achieved using the JAAS framework integrated in the Authentication Service. Module chaining is configured under the Authentication Configuration Service. Each registered module is assigned one of the following four values:

Once authentication to all modules in the chain is successful, control is returned to the Authentication Service (from the JAAS framework) which validates all the user IDs used to authenticate and maps them to one user. The mapping is achieved by configuring the User Alias List attribute in the user’s profile. A valid session token is issued to the user if all the maps are correct; if not, the user is denied a valid session token. The following properties would represent the single authenticated user to which the other users are aliased:

Fully Qualified Domain Name Mapping

Fully Qualified Domain Name (FQDN) mapping enables the Authentication Service to take corrective action in the case where a user may have typed in an incorrect URL (such as specifying a partial host name or IP address to access protected resources). FQDN mapping is enabled by modifying the com.sun.identity.server.fqdnMap attribute in the AMConfig.properties file. The format for specifying this property is:

com.sun.identity.server.fqdnMap[invalid-name]=valid-name

The value invalid-name would be a possible invalid FQDN host name that may be typed by the user, and valid-name would be the actual host name to which the filter will redirect the user. Any number of mappings can be specified (as illustrated in Code Example 3-13) as long as they conform to the stated requirements. If this property is not set, the user would be sent to the default server name configured in the com.iplanet.am.server.host=server_name property also found in the AMConfig.properties file.

:

Code Example 3-13  FQDN Mapping Attribute In AMConfig.properties

com.sun.identity.server.fqdnMap[isserver]=isserver.mydomain.com

com.sun.identity.server.fqdnMap[isserver.mydomain]=isserver.mydomain.com

com.sun.identity.server.fqdnMap[IP address]=isserver.mydomain.com

Possible Uses For FQDN Mapping

This property can be used for creating a mapping for more than one host name which may be the case if applications hosted on a server are accessible by more than one host name. This property can also be used to configure Identity Server to not take corrective action for certain URLs. For example, if no redirect is required for users who access applications by using an IP address, this feature can be implemented by specifying a map entry such as:

com.sun.identity.server.fqdnMap[IP address]=IP address.


Caution

If more than one mapping is defined, ensure that there are no overlapping values in the invalid FQDN name. Failing to do so may result in the application becoming inaccessible.


Persistent Cookie

A persistent cookie is one that continues to exist after the web browser is closed, allowing a user to login with a new browser session without having to reauthenticate. The name of the cookie is defined by the com.iplanet.am.pcookie.name property in AMConfig.properties; the default value is DProPCookie. The cookie value is a 3DES-encrypted string containing the userDN, organization name, authentication module name, maximum session time, idle time, and cache time. To enable persistent cookies:

  1. Turn on the Persistent Cookie Mode in the Core Authentication Service.
  2. Configure a time value for the Persistent Cookie Maximum Time attribute in the Core Authentication Service.
  3. Append the iPSPCookie Parameter with a value of yes to The User Interface Login URL.
  4. Once the user authenticates using this URL, if the browser is closed, they can open a new browser window and will be redirected to the console without reauthentication. This will work until the time defined in Step 2 elapses.

Persistent Cookie Mode can be turned on using the Authentication SPI method:

AMLoginModule.setPersistentCookieOn().

Multi-LDAP Authentication Module Configuration

As a form of failover or to configure multiple values for an attribute when the Identity Server console only provides one value field, an administrator can define multiple LDAP authentication module configurations under one organization. Although these additional configurations are not visible from the console, they work in conjunction with the primary configuration if an initial search for the requesting user’s authorization is not found. For example, one organization can define a search through LDAP servers for authentication in two different domains or it can configure multiple user naming attributes in one domain. For the latter, which has only one text field in the console, if a user is not found using the primary search criteria, the LDAP module will then search using the second scope. Following are the steps to configure additional LDAP configurations.

To Add An Additional LDAP Configuration

  1. Write an XML file including the complete set of attributes and new values needed for second(or third) LDAP authentication configuration.
  2. The available attributes can be referenced by viewing the amAuthLDAP.xml located in etc/opt/SUNWam/config/xml. This XML file created in this step though, unlike the amAuthLDAP.xml, is based on the structure of the amadmin.dtd as defined in Chapter 6, "Service Management," in this manual. Any or all attributes can be defined for this file. Code Example 3-14 is an example of a subconfiguration file that includes values for all attributes available to the LDAP authentication configuation.

    Code Example 3-14  Sample XML File To Add An LDAP SubConfiguration 

    <?xml version="1.0" encoding="ISO-8859-1"?>

    <!--

    Copyright (c) 2002 Sun Microsystems, Inc. All rights reserved.

    Use is subject to license terms.

    -->

    <!DOCTYPE Requests

    PUBLIC "-//iPlanet//Sun ONE Identity Server 6.0 Admin CLI DTD//EN"

    "jar://com/iplanet/am/admin/cli/amAdmin.dtd"

    >

    <!--

    Before adding subConfiguration load the schema with

    GlobalConfiguration defined and replace corresponding

    serviceName and subConfigID in this sample file OR load

    serviceConfigurationRequests.xml before loading this sample

    -->

    <Requests>

    <OrganizationRequests DN="dc=iplanet,dc=com">

    <AddSubConfiguration subConfigName = "ssc"

    subConfigId = "serverconfig"

    priority = "0" serviceName="iPlanetAMAuthLDAPService">

    <AttributeValuePair>

    <Attribute name="iplanet-am-auth-ldap-server"/>

    <Value>newvalue</Value>

    </AttributeValuePair>

    <AttributeValuePair>

    <Attribute name="iplanet-am-auth-ldap-server"/>

    <Value>vbrao.red.iplanet.com:389</Value>

    </AttributeValuePair>

    <AttributeValuePair>

    <Attribute name="iplanet-am-auth-ldap-base-dn"/>

    <Value>dc=iplanet,dc=com</Value>

    </AttributeValuePair>

    <AttributeValuePair>

    <Attribute name="planet-am-auth-ldap-bind-dn"/>

    <Value>cn=amldapuser,ou=DSAME Users,dc=iplanet,dc=com</Value>

    </AttributeValuePair>

    <AttributeValuePair>

    <Attribute name="iplanet-am-auth-ldap-bind-passwd"/>

    <Value>copy encrypted password</Value>

    </AttributeValuePair>

    <AttributeValuePair>

    <Attribute name="iplanet-am-auth-ldap-user-naming-attribute"/>

    <Value>uid</Value>

    </AttributeValuePair>

    <AttributeValuePair>

    <Attribute name="iplanet-am-auth-ldap-user-search-attributes"/>

    <Value>uid</Value>

    </AttributeValuePair>

    <AttributeValuePair>

    <Attribute name="iplanet-am-auth-ldap-search-scope"/>

    <Value>SUBTREE</Value>

    </AttributeValuePair>

    <AttributeValuePair>

    <Attribute name="iplanet-am-auth-ldap-ssl-enabled"/>

    <Value>false</Value>

    </AttributeValuePair>

    <AttributeValuePair>

    <Attribute name="iplanet-am-auth-ldap-return-user-dn"/>

    <Value>true</Value>

    </AttributeValuePair>

    <AttributeValuePair>

    <Attribute name="iplanet-am-auth-ldap-auth-level"/>

    <Value>0</Value>

    </AttributeValuePair>

    <AttributeValuePair>

    <Attribute name="iplanet-am-auth-ldap-server-check"/>

    <Value>15</Value>

    </AttributeValuePair>

    </AddSubConfiguration>

    </OrganizationRequests>

    </Requests>

  3. Get an encrypted value for the amadmin password using the ampassword utility shipped with Identity Server.
  4. ampassword -e administrator_password

    More information on this utility can be found in the Sun ONE Identity Server Administration Guide.

  5. Copy the encrypted password as the value for the iplanet-am-auth-ldap-bind-passwd in the XML file created in Step 1.
  6. The value of this attribute is formatted in bold in Code Example 3-14.

  7. Load the XML file using the amadmin command line tool.
  8. ./amadmin -u amadmin -w administrator_password -v -t name_of_XML_file.

Be aware that this second LDAP configuration can not be seen or modified using the Identity Server console.


Tip

There is a sample available for multi-LDAP configuration. See the serviceAddMultipleLDAPConfigurationRequests.xml command line template in /IdentityServer_base/SUNWam/samples/admin/cli/bulk-ops/. Instructions can be found in Readme.html at /IdentityServer_base/SUNWam/samples/admin/cli/.


Session Upgrade

The Authentication Service allows for the upgrading of a valid session token based on a second, successful authentication performed by the same user to one organization. If a user with a valid session token attempts to authenticate to a resource secured by his current organization and this second authentication request is successful, the session is updated with the new properties based on the new authentication. If the authentication fails, the user’s current session is returned without an upgrade. If the user with a valid session attempts to authenticate to a resource secured by a different organization, the user will receive a message asking whether they would like to authenticate to the new organization. The user can, at this point, maintain the current session or attempt to authenticate to the new organization. Successful authentication will result in the old session being destroyed and a new one being created.

During session upgrade, if a login page times out, redirection to the original success URL will occur. Timeout values are determined based on:

The values of com.iplanet.am.invalidMaxSessionTimeout and iplanet-am-max-session-time should be greater than the page timeout value, or the valid session information during session upgrade will be lost and URL redirection to the previous successful URL will fail.

Validation Plug-in Interface

An Administrator can write username or password validation logic suitable to their organization, and plug this into the Authentication Service. (This functionality is supported only by the LDAP and Membership authentication modules.) Before authenticating the user or changing the password, Identity Server will invoke this plugin. If the validation is successful, authentication continues; if it fails, an authentication failed page will be thrown. The plugin extends the com.iplanet.am.sdk.AMUserPasswordValidation class which is part of the Service Management SDK. Information on this SDK can be found in the com.iplanet.am.sdk package in the Identity Server Javadocs and in Chapter 6, "Service Management," in this manual. The steps below document how to write and configure a validation plugin for Identity Server.

  1. The new plugin class will extend the com.iplanet.am.sdk.AMUserPasswordValidation class and implement the validateUserID() and validatePassword() methods. AMException should be thrown if validation fails.
  2. Compile the plugin class and place the .class file in the desired location. Update the classpath so that it is accessible by the Identity Server during runtime.
  3. Login to the Identity Server console as top-level administrator. Click on the Service Management tab, and get to the attributes for the Administration Service. Type the name of the plugin class (including the package name) in the UserID & Password Validation Plugin Class field.
  4. Logout and login.


Authentication DTD Files

The Authentication Service uses document type definition (DTD) files to define the structure for the XML files it uses. The DTDs are located in IdentityServer_base/SUNWam/dtd and, for use within the Authentication Service, include:

Auth_Module_Properties.dtd

The Auth_Module_Properties.dtd defines the structure for the XML-based "Authentication Module Configuration Files." It provides definitions to initiate, construct and send the required authentication interface to the user. The DTD is located in IdentityServer_base/SUNWam/dtd. An explanation of the elements defined by the Auth_Module_Properties.dtd follows. Each element includes required and/or optional XML attributes.

ModuleProperties Element

ModuleProperties is the root element of the authentication module configuration file. It must contain at least one Callbacks sub-element. The required XML attributes of ModuleProperties are moduleName which takes a value equal to the name of the module and version which takes a value equal to the version number of the authentication module configuration file itself. Code Example 3-15 below is the LDAP.xml file that defines the screens for the LDAP authentication module. Note the ModuleProperties element on the first line of code.

Code Example 3-15  LDAP.xml  

...

<ModuleProperties moduleName="LDAP" version="1.0" >

<Callbacks length="2" order="1" timeout="120"

header="LDAP Authentication" >

<NameCallback>

<Prompt> User Name: </Prompt>

</NameCallback>

<PasswordCallback echoPassword="false" >

<Prompt> Password: </Prompt>

</PasswordCallback>

</Callbacks>

<Callbacks length="4" order="2" timeout="120"

header="Change Password" >

<PasswordCallback echoPassword="false" >

<Prompt>#REPLACE#&lt;BR&gt; Old Password </Prompt>

</PasswordCallback>

<PasswordCallback echoPassword="false" >

<Prompt> New Password </Prompt>

</PasswordCallback>

<PasswordCallback echoPassword="false" >

<Prompt> Confirm Password </Prompt>

</PasswordCallback>

<ConfirmationCallback>

<OptionValues>

<OptionValue>

<Value> Submit </Value>

</OptionValue>

<OptionValue>

<Value> Cancel </Value>

</OptionValue>

</OptionValues>

</ConfirmationCallback>

</Callbacks>

<Callbacks length="0" order="3" timeout="120"

header="Your password has expired."

error="true" >

</Callbacks>

</ModuleProperties>

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. It can contain one or more of four sub-elements: NameCallback, PasswordCallback, ChoiceCallback or ConfirmationCallback. The required XML attributes of Callbacks are:

The optional XML attributes are:

Code Example 3-15 defines three screen callback elements that can be called by the LDAP Authentication module. The first asks the requestor for a name and password. The second is an optional screen that allows the requestor to change their password. The final screen sends a message informing the user that it is time to reset their password.


Note

The Callbacks element can also be used for error handling. An error message can be sent to the user interface using the header and error attributes and formatting the element as:

<Callbacks length="0" order="n" timeout="120" header="Your password has expired. Please contact the service desk to reset your password." error="true" />

Or one of the pre-defined error JSPs, located in IdentityServer_base/SUNWam/ web-apps/services/config/auth/default, can be sent by formatting the element as:

<Callbacks length="0" order="n" timeout="120" template="jsp_name" />


NameCallback Element

The NameCallback element is used to request data from the user; for example, a user identification. It can contain one sub-element, Prompt, which defines the text that precedes the input field. The optional XML attributes are isRequired and attribute. isRequired takes a value of true or false and defines whether the element is required information. (A value of true displays an asterisk next to the text defined in Prompt.) attribute takes a character value of the corresponding LDAP attribute of this value.

PasswordCallback Element

The PasswordCallback element is used to request password data to be entered by the user. It can contain one sub-element, Prompt, which defines the text that precedes the input field. The XML attributes are echoPassword, isRequired and attribute. echoPassword is required, takes a value of true or false and defines whether the password should be displayed on the screen. isRequired is optional, takes a value of true or false and defines whether the element is required information. (A value of true displays an asterisk next to the text defined in Prompt.) attribute is also optional and takes a character value of the corresponding LDAP attribute of this value.

ChoiceCallback Element

The ChoiceCallback element is used when the application user must choose from multiple values. It can contain two sub-elements: Prompt or ChoiceValues. Prompt defines the text that precedes the input field. ChoiceValues defines the values from which the user may choose. The XML attributes are multipleSelectionsAllowed, isRequired and attribute. multipleSelectionsAllowed is a required attribute and takes a value of true or false. It defines whether the user can choose a number of values or only one from the available choices. isRequired is optional and takes a value of true or false. (A value of true displays an asterisk next to the text defined in Prompt.) attribute is also optional and takes a character value of the corresponding LDAP attribute of this value.

ConfirmationCallback Element

The ConfirmationCallback element is used to send button information to the authentication interface (such as text which needs to be rendered on the module’s screen) as well as receive the button information (such as which button is clicked by the user). In future versions of Identity Server, this element will support additional features. It can contain one sub-element, OptionValues, which provides a list of text information. There are no XML attributes.


Note

When a custom authentication module XML service file is configured without the ConfirmationCallback, button properties are picked up from the global i18n authentication properties file, amAuthUI.properties.


Prompt Element

The Prompt element is used to set the text that will display beside a text input field on the browser screen. It has no sub-elements or XML attributes.

ChoiceValues and ChoiceValue Element

The ChoiceValues element provides a list of choices from which the user can select. It must contain at least one sub-element of the type ChoiceValue which defines one choice. ChoiceValue must contain the sub-element Value. ChoiceValues has no XML attributes but ChoiceValue can contain the XML attribute isDefault. isDefault specifies if the defined value is selected when the choices are displayed; it takes a value of true or false.

OptionValues and OptionValue Element

The OptionValues element provides a list of text information for buttons that need to be rendered on the login screen. It must contain at least one sub-element of the type OptionValue which defines one button text value. OptionValue must contain the sub-element Value. OptionValues has no XML attributes but OptionValue can contain the XML attribute isDefault. isDefault specifies if the defined value is selected when the choices are displayed; it takes a value of true or false.

Value Element

The Value element is used by the client to return a value provided by the requestor back to the Identity Server. It has no sub-elements or XML attributes.

The remote-auth.dtd Structure

Authentication requests and responses are sent to and received by the Authentication Java API or non-Java applications using an XML structure. The structure of these messages is defined in the remote-auth.dtd. The Identity Server console receives these XML-based messages which provide definitions to initiate the collection of credentials and perform authentication. It is located in the IdentityServer_base/SUNWam/dtd directory. An explanation of the elements defined by the remote-auth.dtd follows. More information can be found in the file itself.

AuthContext Element

AuthContext is the root element of the XML-based message. It must contain a Request or Response sub-element. The required XML attributes of AuthContext are version which takes a value equal to the version number of the DTD.

Request Element

The Request element is used by the client to initialize and pass user credentials to the Authentication Service. It may contain one or more of the following sub-elements: NewAuthContext, QueryInformation, Login, SubmitRequirements, Logout or Abort. The required XML attribute of Request is authIdentifier which takes a value equal to a unique random number set by the Authentication Service that is used to keep track of the authentication session. Table 3-9 shows the Request sub-elements and the possible Responses for each.

Table 3-9  Request Sub-Elements And Possible Responses

Request

Possible Responses

NewAuthContext

LoginStatus or Exception

QueryInformation

QueryResult or Exception

Login

GetRequirements, LoginStatus or Exception

SubmitRequirements

GetRequirements, LoginStatus or Exception

Logout

LoginStatus or Exception

Abort

LoginStatus or Exception

NewAuthContext Element

The NewAuthContext element initiates the authentication process by initializing the Authentication Service and creating a session token for each request. It contains no sub-elements. The required XML attribute of NewAuthContext is orgName which takes a value equal to the name of the organization or sub-organization for which the process is being defined.

QueryInformation Element

The QueryInformation element is used by the remote client to get information about the authentication modules supported by the Identity Server or the organization. It contains no sub-elements. The required XML attribute of QueryInformation is requestedInformation which takes a value equal to the defined authentication module plug-ins configured for the organization or sub-organization.

Login Element

The Login element is used to initialize the authentication session. It will have an Empty sub-element, or can have an IndexTypeNamePair. The IndexTypeNamePair element can be used to specify the defined authentication type and value. It has no required XML attributes.

SubmitRequirements Element

The SubmitRequirements element is used by the remote client to submit the identity’s authentication credentials to the Identity Server. It has a Callbacks sub-element and no required XML attributes.

Logout Element

The Logout element is used by the remote client to indicate that user wants to logout. It has an Empty sub-element and no required XML attributes.

Abort Element

The Abort element is used by the remote client to indicate that the user wants to end the login process. It has an Empty sub-element and no XML attributes.

Response Element

The Response element is used by the Authentication Service to ask the remote client to gather user credentials or to inform the remote client on the success or failure of the login as well as any errors that might have occurred. It may contain one or more of the following sub-elements: QueryResult, GetRequirements, LoginStatus or Exception. The required XML attribute of Response is authIdentifier which takes a value equal to a unique random number set by the Authentication Service and used to keep track of the authentication session.

QueryResult Element

The QueryResult element is used by Identity Server to send query information requested by the remote client. It must contain a Value sub-element. The required XML attribute of QueryResult is requestedInformation which takes a value equal to the authentication module plug-ins configured for an organization or sub-organization.

GetRequirements Element

The GetRequirements element is used by the Identity Server to request authentication credentials from the client. It has a Callbacks sub-element and no required XML attributes.

LoginStatus Element

The LoginStatus element is used by the Identity Server to indicate the status of the authentication process. It will have an Empty sub-element if a Subject or Exception sub-element is not defined. The XML attributes are status, ssoToken, successURL or failureURL; the latter three are optional. If the LoginStatus is successful, the sub-element Subject will be returned with the authenticated user names. The attribute ssoToken will have the session token status set to inprogress when a new AuthContext is created, to success when a login has been successful, to failed when a login has not been successful and completed when the user logs out. The successURL attribute represents the URL that the identity will be redirected to upon successful authentication and failureURL represents the URL that the identity will be redirected to upon failed authentication.

Exception Element

The Exception element is used by the Identity Server to inform the client about an exception that occurred during the login process. It has an Empty sub-element and four optional XML attributes: message which takes a value equal to that of the exception message, tokenId which takes a value equal to that of the user ID of the failed authentication, errorCode which takes a value equal to that of the error message code and templateName which takes a value equal to the name of the JSP template which will be used for this particular exception.

IndexTypeNamePair Element

The IndexTypeNamePair element identifies the defined authentication method that will be used to validate the client. It has the IndexName sub-element. The required XML attribute is IndexType which takes a value equal to that of the generic level at which the authentication method has been defined: authLevel, role, user, moduleInstance and service. See "Authentication Methods" for more information.

IndexName Element

The IndexName element identifies the specific name of the value specified by the IndexType attribute in the IndexTypeNamePair Element. The authentication method can be defined at the organization level, the role level, the user level, the authentication-level level or the service level, or the module level. The IndexType attribute defines authLevel, role, user, moduleInstance and service. The IndexName element takes a value equal to that of the name of the level at which the authentication method has been defined. For example, if IndexType is user or role then, IndexName might be joe or administrator, respectively. IndexName has no sub-elements and no XML attributes.

Subject Element

The Subject element identifies a collection of one or more identities. It has no sub-elements and no XML attributes.

Callbacks Element

The Callbacks element is used to request and transfer user credentials between the remote client and Identity Server. Identity Server constructs callback objects for information gathering. The client program collects the credentials by prompting the user and returns the callback objects with the required data. The Callbacks element may contain one or more of the following sub-elements: NameCallback, PasswordCallback, ChoiceCallback, ConfirmationCallback, TextInputCallback, TextOutputCallback, LanguageCallback, PagePropertiesCallback and CustomCallback. The required XML attribute is length which takes a value equal to that of a token.

NameCallback Element

The NameCallback element is used to obtain the name of the user (or service) that is requesting authentication. It may contain one or more of the following sub-elements: Prompt or Value. It has no required XML attributes.

PasswordCallback Element

The PasswordCallback element is used to obtain the password of the user (or service) that is requesting authentication. It may contain one or more of the following sub-elements: Prompt or Value. The required XML attribute is echoPassword which takes a value of true or false. The default value of false indicates that there will be no password confirmation.

ChoiceCallback Element

The ChoiceCallback element is used when the user must choose from a selection of values. It may contain one or more of the following sub-elements: Prompt, ChoiceValue or SelectedValues. The required XML attribute is multipleSelectionsAllowed which takes a value of true or false. The default value of false indicates that the user can not choose more than one from the selection.

ConfirmationCallback Element

The ConfirmationCallback element is used by the Identity Server to request a confirmation from the user. It may contain one or more of the following sub-elements: Prompt, OptionValues, SelectedValue, and DefaultOptionValue. The required XML attributes are messageType (which defines the type of message, either information, warning or the default, error), and optionType which specifies the type of confirmation (ok_cancel, yes_no_cancel, unspecified or the default, yes_no).

TextInputCallback Element

The TextInputCallback element is used to get text information from the user. It may contain one or more of the following sub-elements: Prompt or Value. There are no required XML attributes.

TextOutputCallback Element

The TextOutputCallback element is used when the user must choose from a selection of values. It may contain the sub-element Value. The required XML attribute is messageType which defines the type of message, either information, warning or the default, error.

LanguageCallback Element

The LanguageCallback element is used by the Identity Server to obtain the user’s locale information. It must contain the Locale sub-element. There are no required XML attributes.

PagePropertiesCallback Element

The PagePropertiesCallback element contains all GUI-related information. It may contain any of the following sub-elements: ModuleName, HeaderValue, ImageName, PageTimeOutValue, or TemplateName. The required XML attribute is isErrorState which takes a value of true or false. The default value is false which indicates that this page is not an error page.

CustomCallback Element

The CustomCallback element is used to define user-defined callbacks. It may contain the AttributeValuePair sub-element. The required XML attribute is the className which takes a value equal to that of the Callback name.

ModuleName Element

The ModuleName element is takes a value equal to the name of the authentication module. It contains no sub-elements and no XML attributes.

HeaderValue Element

The HeaderValue element is takes a value equal to the header that will be displayed. It contains no sub-elements and no XML attributes.

ImageName Element

The ImageName element is takes a value equal to the name of the image to be displayed. It contains no sub-elements and no XML attributes.

PageTimeOutValue Element

The PageTimeOutValue element is the page time-out value in seconds. It contains no sub-elements and no XML attributes.

TemplateName Element

The TemplateName element is takes a value equal to the name of the template to be rendered. It contains no sub-elements and no XML attributes.

AttributeValuePair Element

The AttributeValuePair element contains the attribute and values for a Callback. It must contain the Attribute sub-element and it can contain the Value sub-element. There are no required XML attributes.

Attribute Element

The Attribute element defines the Callback parameter. It contains no sub-elements. The required XML attribute is name which takes a value equal to the name of the Callback parameter.

Value Element

The Value element is used by the remote client to return a value, provided by the user (or service), back to the Identity Server. It must contain at least one Value sub-element. There are no required XML attributes.

Prompt Element

The Prompt element is used by Identity Server to request the remote client to display the prompt. It contains no sub-elements and there are no required XML attributes.

Locale Element

The Locale element contains the value of the locale that will be used for authentication. It contains no sub-elements. The optional XML attributes are language (which represents the language code), country (which represents the country code) and variant (which represents the variant code).

ChoiceValues Element

The ChoiceValues element provides a list of choices. It must contain at least one the ChoiceValue sub-element. There are no required XML attributes.

ChoiceValue Element

The ChoiceValues element provides a single choice. It must contain at least one Value sub-element. The required XML attribute is isDefault which takes a value of yes or no. The default value of no specifies if the value has to be selected by default when displayed.

SelectedValues Element

The SelectedValues element provides a list of values selected by the user. It must contain at least one Value sub-element. There are no required XML attributes.

SelectedValue Element

The SelectedValue element provides a value selected by the user. It must contain at least one Value sub-element. There are no required XML attributes.

OptionValue Element

The SelectedValues element provides a single user-defined option value. It must contain at least one Value sub-element. There are no required XML attributes.

DefaultOptionValue Element

The DefaultOptionValue element is the default option value. The default value depends on whether user-defined values or predefined values are used in the callback. If user-defined values are used, the default value will be an index in the OptionValues element; if predefined, it will be one of the predefined option values. It must contain at least one Value sub-element. There are no required XML attributes.


Custom Authentication Modules

The Authentication Service allows an organization to write and plug-in custom modules for authentication providers not currently implemented by Identity Server. The first step is to code the module in Java using the Service Programming Interfaces. Instructions on how to do this and which classes to use can be found in "Implementing A Custom Authentication Module".


Note

To write a custom authentication module, knowledge of the JAAS API is necessary, especially for defining the module’s configuration properties. For more information, see the Java Authentication And Authorization Service Developer’s Guide at http://java.sun.com/security/ jaas/doc/api.html. Additional information can be found at http://java.sun.com/products/jaas/.


Integrating A Custom Authentication Module

The following steps describe the procedure to integrate a custom authentication module into the Identity Server deployment. In detailing this procedure, it also explains what files are needed in order to make the integration work. For information on how to implement a custom module, see "Service Programming Interfaces".

  1. Create an authentication module configuration file.
  2. An authentication module configuration file specifies, at a minimum, the information required from an identity (user, service, or application) for authentication. It is located in IdentityServer_base/SUNWam/web-apps/services/config/auth/default. The required credentials might include, but are not limited to, user name and password. Based on this file, the Authentication Service will dynamically generate the login screens. Additional information on the file itself can be found in "Authentication Module Configuration Files". Information on how to create it can be found in "Configuring The Authentication Module".


    Tip

    Creating the authentication module configuration file first allows time to plan the module requirements as each Callbacks Element defined corresponds to a login state. When an authentication process is invoked, a Callback() is generated from the module for each state. For more information, see "Auth_Module_Properties.dtd" and "Implement The LoginModule Interface".


  3. Create a localization properties file for the new module.
  4. The localization properties file defines language-specific screen text for the attribute names of the module. It is located in the directory IdentityServer_base/ SUNWam/locale/. Information on this file can be found in "Configuring Authentication Localization Properties". Additional information on how to modify its contents can be found in "Configuring Console Localization Properties" of Chapter 6, "Service Management," in this manual.

  5. Create an XML service file for the new authentication module and import it into Identity Server.
  6. The XML service file is written and imported to allow the management of the authentication module’s parameters using the console. The name of the XML service file follows the format amAuthmodulename.xml (for example, amAuthSafeWord.xml or amAuthLDAP.xml). The file is located in /etc/opt/ SUNWam/config/xml. Information on the steps to create and import an XML service file can be found in Chapter 6, "Service Management," in this manual.

  7. Modify attributes in the Core Authentication Service.
  8. The new module needs to be recognized by the Identity Server framework. Information on how this is done can be found in "Modifying The Core Authentication Service". Additional information on these attributes can be found in the Core Authentication Attributes chapter of the Sun ONE Identity Server Administration Guide.

  9. Restart Identity Server.

Configuring The Authentication Module

The authentication module configuration file is an XML file that defines the requirements that each module seeks for authentication. In other words, this file defines the screens that a user might see when directed to authenticate (i.e.: user name screen, password screen, change password screen, etc.). Modifying elements in this file will automatically and dynamically customize the authentication interface. The name of this file follows the format modulename.xml; for example, SafeWord.xml or LDAP.xml. (modulename is the same name as the class without the package.) Each authentication module has its own configuration file, located in IdentityServer_base/SUNWam/web-apps/services/config/auth/default.


Note

An authentication module configuration file needs to be created and stored for each custom module, as discussed, even if the module itself has no requirements for authentication.


If there is more than one organization in the Identity Server deployment, each organization should have its own authentication directory named IdentityServer_base/SUNWam/web-apps/services/config/auth/default/org_name. If an organization has more than one locale, the files are stored separately, in directories appended with a locale, as in IdentityServer_base/SUNWam/web-apps/ services/config/auth/default/org_name_locale. Additionally, with service authentication, there might be an authentication directory under the organization’s tree that corresponds to the service. More information on this directory hierarchy can be found in "To Create New Directories For Custom Console Files".


Note

Customization of the authentication screens are only supported at the organization, sub-organization and service levels. In a search for the correct module configuration properties files, Identity Server first searches the org_name_locale directory, followed by the org_name, the default_locale and the default directories.


Elements Of The Authentication Module Configuration File

Each login page in the authentication module is defined by a Callback element which is generally a request for authentication information.


Note

To understand more on how these authentication module configuration files are defined and constructed, refer to "Auth_Module_Properties.dtd".


Code Example 3-16 defines two login pages: the first asks for a first and last name while the second asks for a password. The order in which the pages are displayed to the user are defined in the order attribute of the Callbacks element. All login requests begin with the Callback defined as 1. From that point, the module takes control of the login process and decides on the next page for display based on user interaction.

Code Example 3-16  Sample Authentication Module Configuration File 

<ModuleProperties moduleName="LoginModuleSample" version="1.0" >

<Callbacks length="2" order="1" timeout="60"

header="This is a sample login page" >

<NameCallback>

<Prompt> User Name </Prompt>

</NameCallback>

<NameCallback>

<Prompt> Last Name </Prompt>

</NameCallback>

</Callbacks>

<Callbacks length="1" order="2" timeout="60"

header="You made it to page 2" >

<PasswordCallback echoPassword="false" >

<Prompt> Enter any password </Prompt>

</PasswordCallback>

</Callbacks>

</ModuleProperties>

In the sample module configuration shown above, page one has two requests for information, the first is for User Name and the second is for Last Name. When the user responds, the information is sent back to the module, where the module writer validates it and returns the next page. Page two has one request for a user password. When the user responds, the password is returned. If the module writer throws an exception, an Authentication failed. page is sent to the user. If no exception is thrown, the user will be redirected to their default page based on the information on redirection URLs in "Authentication Methods".

Customizing Membership.xml

The Membership Authentication Module contains a self-registration functionality. Membership authentication is implemented for users to configure personalized portals. The user can create an account, personalize it without the aid of an administrator, and access it as a registered user. Code Example 3-17 contains Membership.xml, the authentication module configuration file for the Membership Authentication module. Modifying this file allows an administrator to add customer-specific user profile data fields onto the self-registration page. In Membership.xml, Callbacks 1 through 15 pertain to the Membership portion of the module; users who have already registered for personalized site profiles can login with a user name and password. Callback 16 and up refer to the Self-Registration portion; users can register and a profile will be created. The customization example begun after Code Example 3-17 refers to Callback 16 and customizing the self-registration functionality.

Code Example 3-17  Membership.xml Configuration File 

<ModuleProperties moduleName="Membership" version="1.0" >

<Callbacks length="3" order="1" timeout="120" header="Self Registration Module" template="membership.jsp" >

<NameCallback>

<Prompt> User Name: </Prompt>

</NameCallback>

<PasswordCallback echoPassword="false" >

<Prompt> Password: </Prompt>

</PasswordCallback>

<ConfirmationCallback>

<OptionValues>

<OptionValue>

<Value> Log In </Value>

</OptionValue>

<OptionValue>

<Value> New User </Value>

</OptionValue>

</OptionValues>

</ConfirmationCallback>

</Callbacks>

<Callbacks length="4" order="2" timeout="240" header="Password Expiring Please Change&lt;BR/&gt;#REPLACE#&lt;BR/&gt;" >

<PasswordCallback echoPassword="false" >

<Prompt> Current Password: </Prompt>

</PasswordCallback>

<PasswordCallback echoPassword="false" >

<Prompt> New Password: </Prompt>

</PasswordCallback>

<PasswordCallback echoPassword="false" >

<Prompt> Confirm New Password: </Prompt>

</PasswordCallback>

<ConfirmationCallback>

<OptionValues>

<OptionValue>

<Value> Submit </Value>

</OptionValue>

<OptionValue>

<Value> Cancel </Value>

</OptionValue>

</OptionValues>

</ConfirmationCallback>

</Callbacks>

<Callbacks length="0" order="3" timeout="120" template="wrongPassword.jsp" />

<Callbacks length="0" order="4" timeout="120" template="noUserProfile.jsp" />

<Callbacks length="0" order="5" timeout="120" template="noUserName.jsp" />

<Callbacks length="0" order="6" timeout="120" template="noPassword.jsp" />

<Callbacks length="0" order="7" timeout="120" template="noConfirmation.jsp" />

<Callbacks length="0" order="8" timeout="120" template="passwordMismatch.jsp" />

<Callbacks length="0" order="9" timeout="120" template="configuration.jsp" />

<Callbacks length="0" order="10" timeout="120" template="userExists.jsp" />

<Callbacks length="0" order="11" timeout="120" template="profileException.jsp" />

<Callbacks length="0" order="12" timeout="120" template="missingReqField.jsp" />

<Callbacks length="0" order="13" timeout="120" template="userPasswordSame.jsp" />

<Callbacks length="0" order="14" timeout="120" template="invalidPassword.jsp" />

<Callbacks length="0" order="15" timeout="120" header="Your password has expired. Please contact service desk to reset your password" error="true" />

<Callbacks length="8" 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>

<ConfirmationCallback>

<OptionValues>

<OptionValue>

<Value> Register </Value>

</OptionValue>

<OptionValue>

<Value> Cancel </Value>

</OptionValue>

</OptionValues>

</ConfirmationCallback>

</Callbacks>

<Callbacks length="2" order="17" timeout="120" header="Self Registration" >

<ChoiceCallback attribute="uid" >

<Prompt>A user already exists with the user name you entered. &lt;BR&gt;Please choose one of the following user names, or create your own:</Prompt>

<ChoiceValues>

<ChoiceValue>

<Value>Create My Own</Value>

</ChoiceValue>

</ChoiceValues>

</ChoiceCallback>

<ConfirmationCallback>

<OptionValues>

<OptionValue>

<Value> Submit </Value>

</OptionValue>

</OptionValues>

</ConfirmationCallback>

</Callbacks>

<Callbacks length="1" order="18" timeout="120" template="disclaimer.jsp" >

<ConfirmationCallback>

<OptionValues>

<OptionValue>

<Value> Agree </Value>

</OptionValue>

<OptionValue>

<Value> Disagree </Value>

</OptionValue>

</OptionValues>

</ConfirmationCallback>

</Callbacks>

</ModuleProperties>

The first Prompts (all defined in Callbacks 16) are required fields in the Self-Registration module. They are User Name, Password, Confirm Password, First Name, Last Name, and Full Name. Each Callback contains the attribute/value pair, isRequired="true". E-mail Address is, by default, not a field the user is required to fill in but that can be changed by adding isRequired="true" as an attribute of that particular Name Callback. To add a field for the user to fill in a telephone number, Membership.xml should be modifed with the Name Callback defined in Code Example 3-18.

Code Example 3-18  Telephone Number Name Callback

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

<Prompt> Tel:</Prompt>

</NameCallback>

Add user data fields which are normally requested as part of a user profile. By default, attributes from the following LDAP objectClasses can be easily added: top, person, organizationalPerson, inetOrgPerson, iplanet-am-user-service, inetuser. Figure 3-12 is the Self-Registration Login Requirement Screen after the telephone number field has been added to Membership.xml. Identity Server and the deployment container should be restarted after modifying Membership.xml.

Figure 3-12  Self-Registration Login Requirement Screen

Self Registration Login Requirement Screen

Configuring Authentication Localization Properties

A localization properties file specifies the screen text and messages that an administrator or user will see when directed to an authentication module’s service attribute configuration page. Each authentication module has its own localization 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 (English). Following are some concepts behind the configuration of this file.

For reference, Code Example 3-19 is a portion of the file amAuthLDAP.properties.

Code Example 3-19  Portion of amAuthLDAP.properties 

...

PInvalid=Current Password Entered Is Invalid

PasswdSame=Password should not be same

PasswdMinChars=Password should be at least 8 characters

a1=Primary LDAP Server and Port

a2=Secondary LDAP Server and Port

a3=DN to Start User Search

a4=DN for Root User bind

a5=Password for Root User Bind

a6=User Naming Attribute

a7=User Entry Search Attribute

...

Additional information on this file and how to modify its contents can be found in "Configuring Console Localization Properties" of Chapter 6, "Service Management," in this manual.

Modifying The Core Authentication Service

Some attributes in the Core Authentication Service need to be extended in order for the Authentication Service to recognize any newly created authentication module.


Note

amAuth.xml, located in /etc/opt/SUNWam/config/xml, defines the Core Authentication Service. When making these changes directly to the XML file, the old file has to be removed and the newly modified one reloaded using the amadmin command line tool. More information on the command line tool can be found in the Sun ONE Identity Server Administration Guide.


Pluggable Auth Module Classes Attribute

This global attribute specifies the Java classes of the authentication modules available within the Identity Server deployment. By default, this includes the modules listed in "Authentication Service Modules". To define a new authentication module, this field takes a value equal to the full class name (including package) of the new module. This modification can also be made in the iplanet-am-auth-authenticators attribute of amAuth.xml. Code Example 3-20 illustrates the default values for this attribute.

Code Example 3-20  iplanet-am-auth-authenticators Attribute 

...

<AttributeSchema name="iplanet-am-auth-authenticators"

type="list"

syntax="string"

i18nKey="a117">

<DefaultValues>

<Value>com.sun.identity.authentication.modules.radius.RADIUS</Value>

<Value>com.sun.identity.authentication.modules.ldap.LDAP</Value>

<Value>com.sun.identity.authentication.modules.membership.Membership</Value >

<Value>com.sun.identity.authentication.modules.unix.Unix</Value>

<Value>com.sun.identity.authentication.modules.anonymous.Anonymous</Value>

<Value>com.sun.identity.authentication.modules.cert.Cert</Value>

<Value>com.sun.identity.authentication.modules.application.Application</Val ue>

<Value>com.sun.identity.authentication.modules.safeword.SafeWord</Value>

<Value>com.sun.identity.authentication.modules.securid.SecurID</Value>

<Value>com.sun.identity.authentication.modules.httpbasic.HTTPBasic</Value>

<Value>com.sun.identity.authentication.modules.nt.NT</Value>

</DefaultValues>

</AttributeSchema>

...

Organization Authentication Modules Attribute

This organization-type attribute lists the authentication modules available to the organizations. An administrator can choose the authentication method for their organization from this list. The default authentication method is LDAP. This modification can also be made in the iplanet-am-auth-allowed-modules attribute of amAuth.xml. Code Example 3-21 illustrates the default values for this attribute.

Code Example 3-21  iplanet-am-auth-allowed-modules Attribute 

<AttributeSchema name="iplanet-am-auth-allowed-modules"

type="multiple_choice"

syntax="string"

i18nKey="a101">

<ChoiceValues>

<ChoiceValue i18nKey="LDAP">LDAP</ChoiceValue>

<ChoiceValue i18nKey="RADIUS">RADIUS</ChoiceValue>

<ChoiceValue i18nKey="Membership">Membership</ChoiceValue>

<ChoiceValue i18nKey="Unix">Unix</ChoiceValue>

<ChoiceValue i18nKey="Anonymous">Anonymous</ChoiceValue>

<ChoiceValue i18nKey="Cert">Cert</ChoiceValue>

<ChoiceValue i18nKey="SafeWord">SafeWord</ChoiceValue>

<ChoiceValue i18nKey="SecurID">SecurID</ChoiceValue>

<ChoiceValue i18nKey="NT">NT</ChoiceValue>

<ChoiceValue i18nKey="HTTPBasic">HTTPBasic</ChoiceValue>

</ChoiceValues>

<DefaultValues>

<Value>LDAP</Value>

</DefaultValues>

</AttributeSchema>


Authentication Programming Interfaces

Identity Server provides programming interfaces to extend the functionality of the Authentication Service in two ways. The Authentication Programming Interfaces provides interfaces that can be used remotely by either Java or C applications to utilize the authentication features of Identity Server. The Service Programming Interfaces can be used to plug new authentication modules, written in Java, into the Identity Server authentication framework.

Exception Handling    

When using either the Authentication SPI (AMLoginModule class) or Authentication API (AuthContext class), AuthLoginException should be used for exception handling instead of LoginException. AuthLoginException has the capability for handling localized message information and exception chaining. See the JavaDocs for more details.

Application Programming Interfaces

Identity Server provides both a Java Authentication API and a C Authentication API for writing authentication clients that remote applications can use to gain access to the Authenticate Service for authentication purposes. This communication between the API and the Authentication Service occurs by sending XML messages over HTTP(S). The remote-auth.dtd is the template used in formatting the XML request messages sent to Identity Server and for parsing the XML return messages received by the external application. "The remote-auth.dtd Structure" details the document data for informational purposes; it can also be accessed in from IdentityServer_base/SUNWam/dtd.


Note

If contacting the Authentication Service directly through its URL (http://identity_server_host.domain_name:port/service_deploy_uri/authservice) without the API, a detailed understanding of remote-auth.dtd will be needed for generating and interpreting the messages passed between the client and server. Sample response and return XML messages can be found in "XML Messages".


Authentication API For Java Applications

As briefly mentioned in "Authentication Via The Java API", external Java applications can authenticate users with the Identity Server Authentication Service by using the Authentication API for Java. The API are organized in a package called com.sun.identity.authentication and can be executed locally or remotely. The classes and methods defined in this package may be incorporated into a Java application to allow communication with the Authentication Service. They are used to initiate the authentication process and communicate authentication credentials to the specific modules within the Authentication Service.

Using The Authentication API For Java

The first step necessary for an external Java application to authenticate to Identity Server is to create a new AuthContext object (com.sun.identity.authentication.AuthContext). The AuthContext class is defined for each authentication request as it initiates the authentication process. Since Identity Server can handle multiple organizations, AuthContext is initialized, at the least, with the name of the organization to which the requestor is authenticating. Once an AuthContext object has been created, the login() method is called indicating to the server what method of authentication is desired. One of the following two methods can be used. Code Example 3-22 can be used specifically for Organization-based Authentication.

Code Example 3-22  Method For Organization-based Authentication

public void login()

throws AuthLoginException

Code Example 3-23 can be used to define any type of authentication method.

Code Example 3-23  Method For Defining Authentication Method 

public void login(IndexType type, String indexName)

throws AuthLoginException

IndexName is the value of the authentication method. IndexType can have any of the following values:

The getRequirements() method then calls the objects that will be populated by the user. Depending on the parameters passed with the instantiated AuthContext object and the two method calls, Identity Server responds to the client request with the correct login requirement screens. For example, if the requested user is authenticating to an organization configured for LDAP authentication only, the server will respond with the LDAP login requirement screen to supply a user name and a password. The client must then loop by calling the hasMoreRequirements() method until the required credentials have been entered. Once entered, the credentials are submitted back to the server with the method call submitRequirements(). The final step is for the client to make a getStatus() method call to determine if the authentication was successful. If successful, the caller obtains a session token for the user; if not, a LoginException is thrown.


Note

Because the Authentication Service is built on the JAAS framework, the Authentication API can also invoke any authentication modules written purely with the JAAS API.


Java Authentication API Samples

Identity Server provides two sample programs to demonstrate how to use the Authentication API for Java. They can be found in IdentityServer_base/SUNWam/samples/authentication/.

Certificate Authentication Sample    

The IdentityServer_base/SUNWam/samples/authentication/Cert directory provides a sample source code file, CertLogin.java, and a readme.html file that illustrates a Java application which utilizes digital certificates for authentication.

LDAP Authentication Sample    

The IdentityServer_base/SUNWam/samples/authentication/LDAP directory provides a sample source code file, LDAPLogin.java, and a readme.html file that illustrates a Java application which authenticates to the LDAP module. This sample can be easily modified to authenticate to other existing or customized authentication modules.

Authentication API For C Applications

As briefly mentioned in "Authentication Via The C API", C applications can authenticate users with the Identity Server Authentication Service by using the Authentication API for C. C applications authenticate to Identity Server using these interfaces in much the same way as the "Authentication API For Java Applications." The C application contacts the Authentication Service to initiate the authentication process, and the Authentication Service responds with a set of requirements. The client application submits authentication credentials back to the Authentication Service and receives further authentication requirements back until there are no more to fulfill. After all requirements have been sent, the client makes one final call to determine if authentication has been successful or has failed. The C API can be found in /IdentityServer_base/SUNWam/agents. This directory also includes a C API samples directory.


Caution

Previous releases of Identity Server contained C libraries in IdentityServer_base/lib/capi. The capi directory is being deprectated, and is curently available for backward compatability. It will be removed in the next release, and therefore it is highly recommended that existing application paths to this directory are changed and new applications do not access it. Paths include RPATH, LD_LIBRARY_PATH, PATH, compiler options, etc.)


Using The Authentication API For C

The sequence of calls necessary to authenticate to Identity Server begins with the function call am_auth_create_auth_context. This call will return an AuthContext structure used for the rest of the authentication calls. Once an AuthContext structure has been initialized, the am_auth_login function is called. This indicates to the Authentication Service that an authentication is desired. Depending on the parameters passed when creating the AuthContext structure and making the am_auth_login function call, the Authentication Service will determine the login requirements with which to respond. For example, if the requested authentication is to an organization configured for LDAP authentication (and no authentication module chaining is involved), the server will respond with the requirements to supply a user name (which corresponds to the NameCallback element in The remote-auth.dtd Structure) and a password (which corresponds to the PasswordCallback element in The remote-auth.dtd Structure). The client loops on function call am_auth_has_more_requirements, and in this specific case there will be two, and fills in the needed information and submits this back to the server with function call am_auth_submit_requirements. The final step is to make function call am_auth_get_status to determine if the authentication was successful or not.

C Authentication API Sample

Identity Server provides a sample program to demonstrate how an external C application can use the API to authenticate a user via Identity Server. The sample can be found in IdentityServer_base/SUNWam/agents/samples/common/. By default, the C Authentication sample looks in IdentityServer_base/SUNWam/agents/config for a properties file named AMAgent.properties.

C Authentication Sample Properties    

Code Example 3-24 lists the properties that are needed by the C Authentication API; some of these are defined in AMAgent.properties and some are not. Those that are not can be added to the file so they needn’t be identified for each function call. For example, com.sun.am.auth.orgName, which identifies the organization from which authentication is desired, can be added to AMAgent.properties.

Code Example 3-24  AMAgent.properties File 

# SOME PROPERTIES LISTED ARE NOT PRE-EXISTING IN THE PROPERTIES FILE

# the identity server naming service url

com.sun.am.namingURL=http://serverexample.domain.com:58080/amserver/namings ervice

# the directory to use for logging

com.sun.am.logFile=/home/uid/logs/auth-log

# the logging level, all:5 being the highest and all:3 being medium

com.sun.am.logLevels=all:5

# the directory containing the certificate and key databases

com.sun.am.sslCertDir=/home/level/certdir

# the prefix of the cert7.db and key3.db files, if any

com.sun.am.certDbPrefix=

# the password to the key3.db file

com.sun.am.certDBPassword=11111111

# true to trust SSL certificates not in the client cert7.db

com.sun.am.trustServerCerts=true

# the nick name of the client certificate in the cert7.db

com.sun.am.auth.certificateAlias=Cert-Nickname

# the identity server organization desired for authentication

com.sun.am.auth.orgName=dc=sun,dc=com

C Authentication API Header File    

The C Authentication API header file, am_auth.h, can be found in IdentityServer_base/SUNWam/agents/include. It contains the function prototypes for the function calls available in the C Authentication API. It has been reproduced in Code Example 3-25 for informational purposes.

Code Example 3-25  am_auth.h C Authentication API Header File 

/* -*- Mode: C -*- */

/*

...

*/

#ifndef __AM_AUTH_H__

#define __AM_AUTH_H__

#include <stdlib.h>

#include <am.h>

#include <am_properties.h>

#include <am_string_set.h>

AM_BEGIN_EXTERN_C

typedef struct am_auth_context *am_auth_context_t;

/*

* Different types of authentication parameters.

*/

typedef enum am_auth_idx {

AM_AUTH_INDEX_AUTH_LEVEL = 0,

AM_AUTH_INDEX_ROLE,

AM_AUTH_INDEX_USER,

AM_AUTH_INDEX_MODULE_INSTANCE,

AM_AUTH_INDEX_SERVICE

} am_auth_index_t;

/*

* Enumeration of authentication statuses.

*/

typedef enum am_auth_status {

AM_AUTH_STATUS_SUCCESS = 0,

AM_AUTH_STATUS_FAILED,

AM_AUTH_STATUS_NOT_STARTED,

AM_AUTH_STATUS_IN_PROGRESS,

AM_AUTH_STATUS_COMPLETED

} am_auth_status_t;

/*

* Language locale structure.

*/

typedef struct am_auth_locale {

const char *language;

const char *country;

const char *variant;

} am_auth_locale_t;

/*

* Enumeration of types of callbacks.

*/

typedef enum am_auth_callback_type {

ChoiceCallback = 0,

ConfirmationCallback,

LanguageCallback,

NameCallback,

PasswordCallback,

TextInputCallback,

TextOutputCallback

} am_auth_callback_type_t;

/*

* Choice callback structure.

*/

typedef struct am_auth_choice_callback {

const char *prompt;

boolean_t allow_multiple_selections;

const char **choices;

size_t choices_size;

size_t default_choice;

const char **response; /* selected indexes */

size_t response_size;

} am_auth_choice_callback_t;

/*

* Confirmation callback structure.

*/

typedef struct am_auth_confirmation_callback_info {

const char *prompt;

const char *message_type;

const char *option_type;

const char **options;

size_t options_size;

const char *default_option;

const char *response; /* selected index */

} am_auth_confirmation_callback_t;

/*

* Language callback structure.

*/

typedef struct am_auth_language_callback_info {

am_auth_locale_t *locale;

am_auth_locale_t *response; /* locale */

} am_auth_language_callback_t;

/*

* Name callback structure.

*/

typedef struct am_auth_name_callback_info {

const char *prompt;

const char *default_name;

const char *response; /* name */

} am_auth_name_callback_t;

/*

* Password callback structure.

*/

typedef struct am_auth_password_callback_info {

const char *prompt;

boolean_t echo_on;

const char *response; /* password */

} am_auth_password_callback_t;

/*

* Text Input callback structure.

*/

typedef struct am_auth_text_input_callback_info {

const char *prompt;

const char *default_text;

const char *response; /* text */

} am_auth_text_input_callback_t;

/*

* Text Output callback structure.

*/

typedef struct am_auth_text_output_callback_info {

const char *message;

const char *message_type;

} am_auth_text_output_callback_t;

/*

* Primary callback structure. The callback_type field

* represents which type of callback this instance of callback

* is representing. Based on the type, the user must use the

* appropriate member of the union.

*/

typedef struct am_auth_callback {

am_auth_callback_type_t callback_type;

union am_auth_callback_info {

am_auth_choice_callback_t choice_callback;

am_auth_confirmation_callback_t confirmation_callback;

am_auth_language_callback_t language_callback;

am_auth_name_callback_t name_callback;

am_auth_password_callback_t password_callback;

am_auth_text_input_callback_t text_input_callback;

am_auth_text_output_callback_t text_output_callback;

} callback_info;

} am_auth_callback_t;

/*

* Initialize the authentication modules.

*

* Parameters:

* auth_init_params The property handle to the property file

* which contains the properties to initialize the

* authentication library.

*

* Returns:

* AM_SUCCESS

* If the initialization of the library is successful.

*

* AM_NO_MEMORY

* If unable to allocate memory during initialization.

*

* AM_INVALID_ARGUMENT

* If auth_init_params is NULL.

*

* Others (Please refer to am_types.h)

* If the error was due to other causes.

*/

AM_EXPORT am_status_t

am_auth_init(const am_properties_t auth_init_params);

/*

* Create a new auth context and returns the handle.

*

* Parameters:

* auth_ctx Pointer to the handle of the auth context.

*

* org_name Organization name to authenticate to.

* May be NULL to use value in property file.

*

* cert_nick_name

* The alias of the certificate to be used if

* the client is connecting securely. May be

* NULL in case of non-secure connection.

*

* url Service URL, for example:

* "http://pride.red.iplanet.com:58080/amserver".

* May be NULL, in which case the naming service

* URL property is used.

*

* Returns:

* AM_SUCCESS

* If auth context was successfully created.

*

* AM_NO_MEMORY

* If unable to allocate memory for the handle.

*

* AM_INVALID_ARGUMENT

* If the auth_ctx parameter is NULL.

*

* AM_AUTH_CTX_INIT_FAILURE

* If the authentication initialization failed.

*/

AM_EXPORT am_status_t

am_auth_create_auth_context(am_auth_context_t *auth_ctx,

const char *org_name,

const char *cert_nick_name,

const char *url);

/*

* Destroys the given auth context handle.

*

* Parameters:

* auth_ctx Handle of the auth context to be destroyed.

*

* Returns:

* AM_SUCCESS

* If the auth context was successfully destroyed.

*

* AM_INVALID_ARGUMENT

* If the auth_ctx parameter is NULL.

*

*/

AM_EXPORT am_status_t

am_auth_destroy_auth_context(am_auth_context_t auth_ctx);

/*

* Starts the login process given the index type and its value.

*

* Parameters:

* auth_ctx Handle of the auth context.

*

* auth_idx Index type to be used to initiate the login process.

*

* value Value corresponding to the index type.

*

* Returns:

* AM_SUCCESS

* If the login process was successfully completed.

*

* AM_INVALID_ARGUMENT

* If the auth_ctx or value parameter is NULL.

*

* AM_FEATURE_UNSUPPORTED

* If the auth_idx parameter is invalid.

*

*/

AM_EXPORT am_status_t

am_auth_login(am_auth_context_t auth_ctx, am_auth_index_t auth_idx,

const char *value);

/*

* Logout the user.

*

* Parameters:

* auth_ctx Handle of the auth context.

*

* Returns:

* AM_SUCCESS

* If the logout process was successfully completed.

*

* AM_INVALID_ARGUMENT

* If the auth_ctx parameter is NULL.

*

*/

AM_EXPORT am_status_t

am_auth_logout(am_auth_context_t auth_ctx);

/*

* Abort the authentication process.

*

* Parameters:

* auth_ctx Handle of the auth context.

*

* Returns:

* AM_SUCCESS

* If the abort process was successfully completed.

*

* AM_INVALID_ARGUMENT

* If the auth_ctx parameter is NULL.

*

*/

AM_EXPORT am_status_t

am_auth_abort(am_auth_context_t auth_ctx);

/*

* Checks to see if there are requirements to be supplied to

* complete the login process. This call is invoked after

* invoking the login() call. If there are requirements to

* be supplied, then the caller can retrieve and submit the

* requirements in the form of callbacks.

*

* The number of callbacks may be retrieved with a call to

* am_auth_num_callbacks() and each callback may be retrieved

* with a call to am_auth_get_callback(). Once the requirements

* for each callback are set, am_auth_submit_requirements() is

* called.

*

* Repeat until done.

*

* Parameters:

* auth_ctx Handle of the auth context.

*

* Returns:

* B_TRUE

* If there are more requirements.

* B_FALSE

* If there are no more requirements.

*

*/

AM_EXPORT boolean_t

am_auth_has_more_requirements(am_auth_context_t auth_ctx);

/*

* Gets the number of callbacks.

*

* Parameters:

* auth_ctx Handle of the auth context.

*

* Returns:

* Number of callbacks.

*

*/

AM_EXPORT size_t

am_auth_num_callbacks(am_auth_context_t auth_ctx);

/*

* Gets the n-th callback structure.

*

* Parameters:

* auth_ctx Handle of the auth context.

*

* index The index into the callback array.

*

* Returns:

* Returns a pointer to the am_auth_callback_t structure

* which the caller needs to populate.

*

*/

AM_EXPORT am_auth_callback_t *

am_auth_get_callback(am_auth_context_t auth_ctx, size_t index);

/*

* Submits the responses populated in the callbacks to the server.

*

* Parameters:

* auth_ctx Handle of the auth context.

*

* Returns:

* AM_SUCCESS

* If the submitted requirements were processed

* successfully.

*

* AM_AUTH_FAILURE

* If the authentication process failed.

*

* AM_INVALID_ARGUMENT

* If the auth_ctx parameter is NULL.

*

*/

AM_EXPORT am_status_t

am_auth_submit_requirements(am_auth_context_t auth_ctx);

/*

*

* Get the status of the authentication process.

*

* Parameters:

* auth_ctx Handle of the auth context.

*

* Returns:

*

* AM_AUTH_STATUS_FAILED

* The login process has failed.

*

* AM_AUTH_STATUS_NOT_STARTED,

* The login process has not started.

*

* AM_AUTH_STATUS_IN_PROGRESS,

* The login is in progress.

*

* AM_AUTH_STATUS_COMPLETED,

* The user has been logged out.

*

* AM_AUTH_STATUS_SUCCESS

* The user has logged in.

*

*/

AM_EXPORT am_auth_status_t

am_auth_get_status(am_auth_context_t auth_ctx);

/*

* Get the sso token id of the authenticated user.

*

* Parameters:

* auth_ctx Handle of the auth context.

*

* Returns:

* A zero terminated string representing the sso token,

* NULL if there was an error or the user has not

* successfully logged in.

*

*/

AM_EXPORT const char *

am_auth_get_sso_token_id(am_auth_context_t auth_ctx);

/*

* Gets the organization to which the user is authenticated.

*

* Parameters:

* auth_ctx Handle of the auth context.

*

* Returns:

* A zero terminated string representing the organization,

* NULL if there was an error or the user has not

* successfully logged in.

*

*/

AM_EXPORT const char *

am_auth_get_organization_name(am_auth_context_t auth_ctx);

/*

* Gets the authentication module/s instances (or plugins)

* configured for an organization, or sub-organization name that

* was set during the creation of the auth context.

* Supply the address of a pointer to a structure

* of type am_string_set_t. Module instance names are

* returned in am_string_set_t. Free the memory

* allocated for this set by calling am_string_set_destroy().

*

* Returns NULL if the number of modules configured is zero.

*

* Parameters:

* auth_ctx Handle of the auth context.

* module_inst_names_ptr Address of a pointer to am_string_set_t.

*

* Returns:

* AM_SUCCESS

* If the submitted requirements were processed

* successfully.

*

* AM_AUTH_FAILURE

* If the authentication process failed.

*

* AM_INVALID_ARGUMENT

* If the auth_ctx parameter is NULL.

*

* AM_SERVICE_NOT_INITIALIZED

* If the auth service is not initialized.

*

*/

AM_EXPORT am_status_t

am_auth_get_module_instance_names(am_auth_context_t auth_ctx,

am_string_set_t** module_inst_names_ptr);

AM_END_EXTERN_C

#endif

Authentication Option For Other Applications

Applications written in a language other than Java or C can exchange authentication information with Identity Server using the XML/HTTP(s) interface. Using the URL http://server_name.domain_name:port/service_deploy_uri/authservice, an application can open a connection using the HTTP POST method and exchange XML messages with the Authentication Service. The structure of the XML messages is defined by "The remote-auth.dtd Structure". In order to access the Authentication Service in this manner, the client application must contain the following:

XML Messages

The following code examples illustrate how customers might configure the XML messages posted to the Authentication Service.


Note

Although the client application need only write XML based on the remote-auth.dtd, when these messages are sent they include additional XML code produced by the Authentication API. This additional XML code is not illustrated in the following examples.


Code Example 3-26 illustrates the initial XML message sent to the Identity Server. It opens a connection and asks for authentication requirements regarding the exampleorg organization to which the user will login.

Code Example 3-26  Initial AuthContext XML Message

<?xml version="1.0" encoding="UTF-8"?>

<AuthContext version="1.0">

<Request authIdentifier="0">

<NewAuthContext orgName="dc=exampleorg,dc=com">

</NewAuthContext>

</Request>

</AuthContext>

Code Example 3-27 illustrates the successful response from Identity Server that contains the authIdentifier, the session identifier for the initial request.

Code Example 3-27  AuthIdentifier XML Message Response  

<?xml version="1.0" encoding="UTF-8"?>

<AuthContext version="1.0">

<Response authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">

<LoginStatus status="in_progress">

</LoginStatus>

</Response>

</AuthContext>

Code Example 3-28 illustrates the client response message back to Identity Server. It specifies the type of authentication module needed by the user to log in.

Code Example 3-28  Second Request Message With Authentication Module Specified

<?xml version="1.0" encoding="UTF-8"?>

<AuthContext version="1.0">

<Request authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">

<Login>

<IndexTypeNamePair indexType="moduleInstance">

<IndexName>LDAP</IndexName>

</IndexTypeNamePair>

</Login>

</Request>

</AuthContext>

Code Example 3-29 illustrates the return message from Identity Server which specifies the authentication module’s login requirements. In this case, the LDAP requirements include a user name and password. Note the page time out value of 120 seconds.

Code Example 3-29  Return XML Message With Login Callbacks 

<?xml version="1.0" encoding="UTF-8"?>

<AuthContext version="1.0">

<Response authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">

<GetRequirements>

<Callbacks length="3">

<PagePropertiesCallback isErrorState="false">

<ModuleName>LDAP</ModuleName>

<HeaderValue>This server uses LDAP Authentication</HeaderValue>

<ImageName></ImageName>

<PageTimeOut>120</PageTimeOut>

<TemplateName></TemplateName>

<PageState>1</PageState>

</PagePropertiesCallback>

<NameCallback>

<Prompt>User Name: </Prompt>

</NameCallback>

<PasswordCallback echoPassword="false">

<Prompt> Password: </Prompt>

</PasswordCallback>

</Callbacks>

</GetRequirements>

</Response>

</AuthContext>

Code Example 3-30 illustrates the client responses to the call for login requirements. They specify amadmin as the user and 11111111 for the password.

Code Example 3-30  Response Message With Callback Values

<?xml version="1.0" encoding="UTF-8"?>

<AuthContext version="1.0">

<Request authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">

<SubmitRequirements>

<Callbacks length="3">

<NameCallback>

<Prompt>User Name:</Prompt>

<Value>amadmin</Value>

</NameCallback>

<PasswordCallback echoPassword="false">

<Prompt>Password:</Prompt>

<Value>11111111</Value>

</PasswordCallback>

</Callbacks>

</SubmitRequirements>

</Request>

</AuthContext>

Code Example 3-31 illustrates that a successful authentication has occurred. As the value of <Subject> uses the Java serialization, it can not be used by non-Java client applications. It’s value is retreived by all applications from the session token.

Code Example 3-31  Successful Authentication XML Message

<?xml version="1.0" encoding="UTF-8"?>

<AuthContext version="1.0">

<Response authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">

<LoginStatus status="success" ssoToken="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=" successURL="http://torpedo.red.iplanet.com:/amconsole">

<Subject>AQICweczOhuelZ5TqD9kKOtiAepxqGP23q4oTnNMuJY//lI2S4KD1/gEN84uLwDGHl llyFSthxoKLM7NDH h2vwAvrDmpsomJvUnbqnJJ90DS+28njGiDv+lv8FqIVhhbxrctbiIUEOHYK0FzXnXjPYizdCmiW XJ+9DJ8T2HbYIDxn9U6eVNAMPq3uVb/RFuErEm5MuPu7PnWeCic12SZre4ZEcw8TI45NKNjd/NZ ZD97bcqL5gEV7SVHspFldZKmo9vA86aEkvMs9P53RiJtrusHN1FKt9+4JqSrdcVLKMzJVAr3z5E ohwHh9/hzd7hgucO661gz7IqkT7WEpve/E8R4em0mg3HgHg7Bg7i3AkyX6YSkoAncdVXMdmWnb7 OV5cBgUjO8zs8Pp5/3dA1XlwACmOqjxshk6Y6Ld6TAQ90qRFwymC1RdLGGCRnrt33kmYVyB1lJy JxT8utPKyDOEKFRHh57NlKTbFhBKc1IGcdQ2crHifpXawx6YouQgQSWGdsqW9IahY4+lqbBTPnG DyZkKz9yy2ZKVjDR05Hwku8elvEwBE40XTJ3gF/mbwCGbh3cyprahLqRXboy8eoEQf3ubQmR2My +bh+NrsRfzfFV5oCcpJE6DtvYE/4zO+uKk3FbG+/NUJzAAor920V/0prtYeS58ZPW8C7qwXINaW 0xdMQV+pgE3NZvMlp5GeZlSIMmSCtXD49n4tqopSlsoK+eiwPODKxp992+6/uJhhVHH5I0Ozuy6 CDM dCJDGvnMENVCUZvki3+tb92fqQbVWixM4Ca6Nnz3jTIKk2uhm559jq9hra8gHHOfnnu4e5jZjzf RdkO3GodiTMOHDnQATHtvT1PBXgorTfUwUa4ZjptvzFulHSi4eQaqs4Z8FAX2OAr8XGHRkhBwox rhjYiCDBpkNmpEiFNhWnTT3bwkAUFhtoDg6836kwHfxeLXKAz3T6qyNQzT+larSXUxrt/TIjwDP R3vg4GF4RzbHlWA1WQtUS/9Qe/N3aegEEEvxPvo9fWq</Subject>

</LoginStatus>

</Response>

</AuthContext>

Service Programming Interfaces

Identity Server provides the capability to plug new, Java-based authentication modules into its framework allowing proprietary authentication providers to be managed using the Identity Server console. Custom authentication modules must first be created using Java and, once created, can be added to the list of available authentication modules.


Note

For instructions on other files needed to plug-in a custom authentication module, see "Integrating A Custom Authentication Module".


New authentication modules are added by using the com.iplanet.authentication.spi package. The SPI implements the JAAS LoginModule, and provides additional methods to access the Authentication Service and module configuration properties files. Because of this architecture, any custom JAAS authentication module will work within the Authentication Service.


Note

This guide does not document the JAAS. For more information on these APIs, see the Java Authentication And Authorization Service Developer’s Guide. Additional information can be found at http://java.sun.com/products/jaas/.


Implementing A Custom Authentication Module

Custom authentication modules extend the com.sun.identity.authentication.spi.AMLoginModule class. The class must also implement the init(), process() and getPrincipal() methods in order to communicate with the authentication module configuration files. The callbacks are then dynamically generated based on this file. Other methods that can be defined include setLoginFailureURL and setLoginSuccessURL which defines URLs to send the user to based on a failed or successful authentication, respectively.


Note

To make use of the account locking feature with custom authentication modules, the InvalidPasswordException exception should be thrown when the password is invalid. For more information on account lockout, see "Account Locking".


Identity Server contains a sample exercise for integrating a custom authentication module with files that have already been created. This sample documents the procedure to integrate an authentication module into the Identity Server deployment. All the files needed to compile, deploy and run the sample authentication module can be found in the IdentityServer_base/SUNWam/samples/authentication/providers directory. The instruction file is the Readme.html file in the same directory. The following sections will use files from this sample as example code.

Implement The Principal Class

After following the procedures in "Configuring The Authentication Module", the next step is to write a Principal class which implements java.security.Principal; in the sample, the constructor takes the username as an argument and represents the authenticated user. If authentication is successful, the module will return this principal to the Authentication Service which extracts information for inclusion into the session token. Code Example 3-32 illustrates this implementation with the SamplePrincipal.java code.

Code Example 3-32  SamplePrincipal.java Code 

package com.iplanet.am.samples.authentication.providers;

import java.io.IOException;

import javax.security.auth.*;

import javax.security.auth.login.*;

import javax.security.auth.callback.*;

import java.security.Principal;

public class SamplePrincipal implements Principal, java.io.Serializable {

/**

* @serial

*/

private String name;

public SamplePrincipal(String name) {

if (name == null)

throw new NullPointerException("illegal null input");

this.name = name;

}

/**

* Return the LDAP username for this <code>SamplePrincipal</code>.

*

* <p>

*

* @return the LDAP username for this <code>SamplePrincipal</code>

*/

public String getName() {

return name;

}

/**

* Return a string representation of this

*<code>SamplePrincipal</code>.

* <p>

*

* @return a string representation of this

* <code>SamplePrincipal</code>.

*/

public String toString() {

return("SamplePrincipal: " + name);

}

/**

* Compares the specified Object with this

* <code>SamplePrincipal</code> for equality. Returns true if

* the given object is also a <code>SamplePrincipal</code>

* and the two SamplePrincipals have the same username.

*

* <p>

*

* @param o Object to be compared for equality with this

* <code>SamplePrincipal</code>.

*

* @return true if the specified Object is equal equal to this

* <code>SamplePrincipal</code>.

*/

public boolean equals(Object o) {

if (o == null)

return false;

if (this == o)

return true;

if (!(o instanceof SamplePrincipal))

return false;

SamplePrincipal that = (SamplePrincipal)o;

if (this.getName().equals(that.getName()))

return true;

return false;

}

/**

* Return a hash code for this <code>SamplePrincipal</code>.

*

* <p>

*

* @return a hash code for this <code>SamplePrincipal</code>.

*/

public int hashCode() {

return name.hashCode();

}

}

Implement The LoginModule Interface

Following the implementation of the Principal Class, com.sun.identity.authentication.spi.AMLoginModule must be subclassed and the init(), process(), and getPrincipal() methods called. AMLoginModule is an abstract class that provides the methods to access Sun ONE Identity Server services and the authentication module configuration file. (AMLoginModule implements the JAAS LoginModule.)

public void init(Subject subject, Map sharedState, Map options);    

init() is an abstract method used to initialize the LoginModule with the relevant information. If the LoginModule does not understand some of the data stored in the sharedState or options parameters, it will be ignored. This method is called by AMLoginModule after the module has been instantiated, and prior to any calls to its other public methods. The method implementation should store away the provided arguments for future use. The init() method may peruse the provided sharedState to determine what additional authentication states were provided by other LoginModules; it may also traverse through the provided options to determine what configurations were defined to affect the LoginModule’s behavior. It may save option values in variables for future use.

public int process(javax.security.auth.callback.Callback[] callbacks, int state)    

The process() method is called to authenticate a Subject. This method implementation performs the actual authentication. For example, it may prompt for a user name and password, and attempt to verify the password against a database. If the LoginModule requires some form of user interaction (retrieving a user name and password, for example), it should be accomplished here. (LoginModules should remain independent of the different types of user interaction.) The process() method should invoke the handle method of the javax.security.auth.callback to perform the user interaction and set the appropriate results (user name, password, etc.). The AMLoginModule will then internally pass an array of appropriate Callbacks (a NameCallback for the user name, a PasswordCallback for the password, et. al.) to the Authentication User Interface which will perform the requested user interaction and set the appropriate values in the Callbacks. Consider the following steps when writing the process() method.

  1. Perform the authentication.
  2. If the authentication is successful, save the principal data.
  3. Return -1 if the authentication succeeds.
  4. Throw a LoginException (such as AuthLoginException) or return the relevant state specified in the authentication module configuration file if the authentication fails.
  5. If multiple states are available to the user, the Callback array from a previous state may be retrieved by using the getCallback(int state) method. The underlying login module keeps the Callback[] from the previous states until the login process is completed.
  6. If a module writer needs to substitute dynamic text in the next state, the writer could use the getCallback() method to get the Callback[] for the next state and modify the output text or prompt. Calling replaceCallback() will update the Callback array. This allows a module writer to dynamically generate challenges, passwords or user IDs.

  7. Note

    Each authentication session creates a new instance of the LoginModule class. The reference to the class will be released once the authentication session has either succeeded or failed. It is important to note that any static data or reference to any static data in LoginModule must be thread-safe.


public Principal getPrincipal();    

This method should be called only once at the end of a successful authentication session. A login session is deemed successful when all pages in the authentication module’s credentials file have been sent and the module has not thrown an exception. This method retrieves the authenticated token string that the user will be known by in the Identity Server environment.

Code Example 3-33 illustrates the LoginModuleSample.java code.

Code Example 3-33  LoginModuleSample.java Code 

package com.iplanet.am.samples.authentication.providers;

import java.util.Map;

import javax.security.auth.Subject;

import javax.security.auth.callback.Callback;

import javax.security.auth.callback.NameCallback;

import javax.security.auth.callback.PasswordCallback;

import javax.security.auth.login.LoginException;

import com.sun.identity.authentication.spi.AMLoginModule;

import com.sun.identity.authentication.spi.AuthLoginException;

public class LoginModuleSample extends AMLoginModule {

private String userTokenId;

private String userName;

private String lastName;

private java.security.Principal userPrincipal = null;

public LoginModuleSample() throws LoginException{

System.out.println("LoginModuleSample()");

}

public void init(Subject subject, Map sharedState, Map options) {

System.out.println("LoginModuleSample initialization");

}

public int process(Callback[] callbacks, int state) throws AuthLoginException {

int currentState = state;

if (currentState == 1) {

userName = ((NameCallback) callbacks[0]).getName();

lastName = ((NameCallback) callbacks[1]).getName();

if (userName.equals("") || lastName.equals("")) {

throw new AuthLoginException("names must not be empty");

}

return 2;

} else if (currentState == 2) {

System.out.println("Replace TExt first: " + userName +

" last: " + lastName);

// set #REPLACE# text in next state

Callback[] callbacks2 = getCallback(3);

String msg = ((NameCallback)callbacks2[0]).getPrompt();

int i = msg.indexOf("#REPLACE#");

String newMsg = msg.substring(0, i) + userName +

msg.substring(i+9);

replaceCallback(3, 0, new NameCallback(newMsg));

// set #REPLACE# in password callback

msg = ((PasswordCallback)callbacks2[1]).getPrompt();

i = msg.indexOf("#REPLACE#");

newMsg = msg.substring(0, i) + lastName + msg.substring(i+9);

replaceCallback(3, 1, new PasswordCallback(newMsg, false));

return 3;

} else if (currentState == 3) {

int len = callbacks.length;

for (int i=0; i<len; i++) {

if (callbacks[i] instanceof NameCallback) {

System.out.println("Callback Prompt-> " +

((NameCallback) callbacks[i]).getPrompt());

} else if (callbacks[i] instanceof PasswordCallback) {

System.out.println("Callback Prompt-> " +

((PasswordCallback) callbacks[i]).getPrompt());

}

}

return 4;

} else if (currentState == 4) {

int len = callbacks.length;

for (int i=0; i<len; i++) {

if (callbacks[i] instanceof NameCallback) {

System.out.println("Callback Value-> " +

((NameCallback) callbacks[i]).getName());

} else if (callbacks[i] instanceof PasswordCallback) {

System.out.println("Callback Value-> " +

((PasswordCallback) callbacks[i]).getPassword());

}

}

userTokenId = userName;

// return -1 for login successful

return -1;

}

throw new AuthLoginException("Invalid state : " + currentState);

}

public java.security.Principal getPrincipal() {

if (userPrincipal != null) {

return userPrincipal;

} else if (userTokenId != null) {

userPrincipal = new SamplePrincipal(userTokenId);

return userPrincipal;

} else {

return null;

}

}

}

Implementing A Pure JAAS Module

Identity Server supports pure JAAS pluggable authentication modules. Pure JAAS modules extend the JAAS LoginModule rather than AMLoginModule. Details on how to write a JAAS module can be found in the LoginModule Developer’s Guide. A pure JAAS module is plugged in to the Authentication framework using the Authentication API as detailed in "Implementing A Custom Authentication Module". Code Example 3-34 is a sample of how the code can be written.

Code Example 3-34  JAAS LoginModule Sample Code 

package com.sun.identity.authentication.modules.sample;

import java.util.*;

import java.io.IOException;

import javax.security.auth.*;

import javax.security.auth.callback.*;

import javax.security.auth.login.*;

import javax.security.auth.spi.*;

import com.iplanet.am.util.*;

/**

* <p> This sample LoginModule authenticates users with password.

* <p> This LoginModule only recognizes one user: testUser

* <p> testUser's password is: testPassword

* <p> If testUser successfully authenticates itself,

* a <code>SamplePrincipal</code> with the testUser's user name

* is added to the Subject.

* <p> This LoginModule recognizes the debug option.

* If set to true in the login Configuration,

* debug messages will be output to the output stream, System.out.

*/

public class SampleLoginModule implements LoginModule {

// initial state

private Subject subject;

private CallbackHandler callbackHandler;

private Map sharedState;

private Map options;

private com.iplanet.am.util.Debug debug;

// configurable option

// the authentication status

private boolean succeeded = false;

private boolean commitSucceeded = false;

// username and password

private String username;

private char[] password;

// testUser's SamplePrincipal

private SamplePrincipal userPrincipal;

/**

* Initialize this <code>LoginModule</code>.

* <p>

* @param subject the <code>Subject</code> to be authenticated.

* @param callbackHandler a <code>CallbackHandler</code> for

* communicating with the end user (prompting for user names and

* passwords, for example). <p>

*

* @param sharedState shared <code>LoginModule</code> state. <p>

*

* @param options options specified in the login

* <code>Configuration</code> for this particular

* <code>LoginModule</code>.

*/

public void initialize(Subject subject, CallbackHandler callbackHandler,

Map sharedState, Map options) {

debug = com.iplanet.am.util.Debug.getInstance("SampleLoginModule");

this.subject = subject;

this.callbackHandler = callbackHandler;

this.sharedState = sharedState;

this.options = options;

// initialize any configured options

debug.message("SampleLoginModule - initialize");

}

/**

* Authenticate the user by prompting for a user name and password.

* <p>

* @return true in all cases since this <code>LoginModule</code>

* should not be ignored.

* @exception FailedLoginException if the authentication fails. <p>

* @exception LoginException if this <code>LoginModule</code>

* is unable to perform the authentication.

*/

public boolean login() throws LoginException {

// prompt for a user name and password

if (callbackHandler == null) {

throw new LoginException("Error: no CallbackHandler available " +

"to garner authentication information from the user");

}

Callback[] callbacks = new Callback[5];

callbacks[0] = new NameCallback("user name: ");

callbacks[1] = new PasswordCallback("password: ", false);

LanguageCallback ll = new LanguageCallback();

TextOutputCallback toc = new TextOutputCallback

(TextOutputCallback.INFORMATION,"This is Sample Login Module");

java.util.Locale locale = new java.util.Locale("zh","TW");

TextInputCallback tic = new TextInputCallback("Enter your name","abc");

tic.setText("fdfdfdfd");

ll.setLocale(locale);

callbacks[2] = ll;

callbacks[3] = toc;

callbacks[4] = tic;

try {

callbackHandler.handle(callbacks);

username = ((NameCallback)callbacks[0]).getName();

char[] tmpPassword = ((PasswordCallback)callbacks[1]).getPassword();

java.util.Locale l = ((LanguageCallback) callbacks[2]).getLocale();

String input = ((TextInputCallback) callbacks[4]).getPrompt();

debug.message("username is .. :" + username);

if (l != null) {

debug.message("locale is .. :" + l.toString());

}

if (input != null) {

debug.message("User has entered" + input);

}

return true;

} catch (java.io.IOException ioe) {

throw new LoginException(ioe.toString());

} catch (UnsupportedCallbackException uce) {

throw new LoginException("Error: " + uce.getCallback().toString() +

" not available to garner authentication information " +

"from the user");

} catch (Exception ex) {

ex.printStackTrace();

throw new LoginException(ex.toString());

}

}

/**

* <p> This method is called if the LoginContext's

* overall authentication succeeded

* (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL

* LoginModules succeeded).

*

* <p> If this LoginModule's own authentication attempt

* succeeded (checked by retrieving the private state saved by the

* <code>login</code> method), then this method associates a

* <code>SamplePrincipal</code>

* with the <code>Subject</code> located in the

* <code>LoginModule</code>. If this LoginModule's own

* authentication attempted failed, then this method removes

* any state that was originally saved.

*

* <p>

*

* @exception LoginException if the commit fails.

*

* @return true if this LoginModule's own login and commit

* attempts succeeded, or false otherwise.

*/

public boolean commit() throws LoginException {

SamplePrincipal principal = new SamplePrincipal("abc");

if (debug.messageEnabled()) {

debug.message("commit.... SUCCESSFULE..." + principal.toString());

}

if (principal != null &&

!subject.getPrincipals().contains(principal))

{

subject.getPrincipals().add(principal);

debug.message ("Done added user to principal");

}

return true;

}

/**

* <p> This method is called if the LoginContext's

* overall authentication failed.

* (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL

* LoginModules did not succeed).

*

* <p> If this LoginModule's own authentication attempt

* succeeded (checked by retrieving the private state saved by the

* <code>login</code> and <code>commit</code> methods),

* then this method cleans up any state that was originally saved.

*

* @exception LoginException if the abort fails.

*

* @return false if this LoginModule's own login and/or commit

* attempts failed, and true otherwise.

*/

public boolean abort() throws LoginException {

return true;

}

/**

* Logout the user.

*

* <p> This method removes the <code>SamplePrincipal</code>

* that was added by the <code>commit</code> method.

*

* @exception LoginException if the logout fails.

*

* @return true in all cases since this <code>LoginModule</code>

* should not be ignored.

*/

public boolean logout() throws LoginException {

return true;

}

}

Implementing Authentication Post Processing

The Authention SPI includes the AMPostAuthProcessInterface which can be implemented for post-processing tasks. (AMPostLoginProcessInterface from previous versions of Identity Server has been deprecated.) AMPostAuthProcessInterface can be executed on either successful or failed authentication or on logout. A post-processing task might include adding attributes to a user’s session after successful authentication, sending notification to an administrator after failed authentication, or general clean-up after logout (i.e.: clearing cookies or logging out other system components). The Core Authentication Service contains the Authentication PostProcessing Class attribute which contains the authentication post-processing class name as its value. Custom post processing interfaces can also be implemented. Code Example 3-35 is sample code that uses the post-processing interface to adding the property TEST1 and its value TESTVALUE1 to the user’s session token.

Code Example 3-35  Sample Code For Authentication Post Processing 

//package com.sun.identity.authentication.spi;

import com.sun.identity.authentication.spi.*;

import com.iplanet.sso.*;

import java.util.*;

import javax.servlet.*;

import javax.servlet.http.*;

import com.iplanet.services.util.Debug;

/**

* The <code>AMPostAuthProcessInterface</code> interface needs to

* be implemented by services and applications to do post

* authentication processing.

* The post processing can be per ORGANIZATION or SERVICE or ROLE

*/

public class SampleSetupSession implements AMPostAuthProcessInterface

{

private static Debug debug = Debug.getInstance("sampleSessionSetup");

/** Post processing on successful authentication.

* @param requestParamsMap - map contains HttpServletRequest parameters

* @param ssoToken - user's session

* @exception Authentication Exception when there is an error

*/

public void onLoginSuccess(Map requestParamsMap,

HttpServletRequest request,

HttpServletResponse response,

SSOToken ssoToken)

throws AuthenticationException

{

debug.message("SampleSetupSession:onLoginSuccess called");

try {

ssoToken.setProperty("TEST1", "TESTVALUE1");

} catch (Exception ex) {

debug.message("SampleSetupSession:onLoginSuccess exception while setting

property :"+ex);

}

}

/** Post processing on failed authentication.

* @param requestParamsMap - map contains HttpServletRequest parameters

* @exception AuthenticationException when there is an error

*/

public void onLoginFailure(Map requestParamsMap,

HttpServletRequest req,

HttpServletResponse res)

throws AuthenticationException

{

debug.message("SampleSetupSession:onLoginFailure called");

}

/** Post processing on Logout.

* @param requestParamsMap - map contains HttpServletRequest parameters

* @param HttpServletRequest - Servlet request

* @param HttpServletResponse - Servlet response

* @param ssoToken - user's session

*/

public void onLogout(HttpServletRequest req,

HttpServletResponse res,

SSOToken ssoToken)

throws AuthenticationException

{

debug.message("SampleSetupSession:onLogout called");

}

}

SPI Sample

The IdentityServer_base/SUNWam/samples/authentication/providers directory provides two sample source code files, LoginModuleSample.java and SamplePrincipal.java, that are used to illustrate how to integrate a sample login module into the Identity Server deployment. The instruction file is the Readme.html file in the same directory.


Authentication Samples

Authentication Service samples have been provided and can be found in the IdentityServer_base/SUNWam/samples/authentication directory. They include:

Certificate Authentication Sample

The IdentityServer_base/SUNWam/samples/authentication/Cert directory provides a sample source code file, CertLogin.java file that illustrates a Java application which utilizes digital certificates for authentication. The instruction file is the readme.html file in the same directory.

LDAP Authentication Sample

The IdentityServer_base/SUNWam/samples/authentication/LDAP directory provides a sample source code file, LDAPLogin.java file that illustrates a Java application which authenticates to the LDAP module. This sample can be easily modified to authenticate to other existing or customized authentication modules. The instruction file is the readme.html file in the same directory.

MSISDN (Wireless) Module

This sample details the steps to integrate a custom login module based on the Mobile Station Integrated Services Digital Network (MSISDN). This module will make it possible to perform non-interactive authentication based upon the unique ID of a particular handset. All the files needed to compile, deploy and run the module can be found in the IdentityServer_base/SUNWam/samples/authentication/msisdn directory. The instruction file is the Readme.html file in the same directory.

SPI Sample

This sample details the steps to integrate a sample login module into the Identity Server deployment. All the files needed to compile, deploy and run the sample authentication module can be found in the IdentityServer_base/SUNWam/samples/authentication/providers directory. The instruction file is the Readme.html file in the same directory.



Previous      Contents      Index      Next     


Copyright 2003 Sun Microsystems, Inc. All rights reserved.