Chapter 3
User Authentication With DSAME
If an organization's resources are protected by the iPlanet Directory Server Access Management Edition (DSAME), a user must submit credentials to the Authentication service in order to gain access to those resources. While DSAME provides several authentication modules, custom authentication modules may also be incorporated. This chapter explains the authentication process, its pluggable architecture and the authentication APIs. It contains the following sections:
The Authentication Process
Every organization has information and resources that need to be protected from unwanted eyes. DSAME provides secure access to these web-based applications and the data that it stores. Gaining access to either of these resources requires that the accessor be validated (given permission). DSAME can use one or more of several types of authentication methods to perform this validation.
An organization's method of authentication (their chosen authentication service) is defined at the root level of an organization by their administrator. When a user or application tries to access a protected resource, they are first directed to a login screen and guided through a series of one or more templates for credential gathering. Once authenticated, the user is issued an encrypted token identity and DSAME redirects them to the desired information, based on their policy set. There are two entry points which recognize that a user has not yet been validated: the DSAME console and a URL Policy Web Agent. These entry points redirect any non-validated users to the organization's authentication service.
|
Note
|
If the authentication process fails, the user is redirected to an error page and refused entry.
|
Administration Console Entry
When a user (whether an organization's administrator or an end user) attempts to access DSAME's URL-based administration console, it checks the client browser for an encrypted token identity. If none is present, the user is directed to the login page of the organization's authentication service where they submit credentials for validation. Once authenticated, the user will be redirected back to the correct screen of the console, based on the roles they are assigned in their DSAME profile.
URL Policy Agent Entry
A web agent is a plug-in that resides on a web server and protects an organization's web-based resources by enforcing a user's DSAME-administered policy. A user's URL access policy consists of three lists of URLs: those that are not subject to policy enforcement, those that the user is denied access to and those that the user is allowed to access. When a user accesses a web-based resource by providing a URL, the web agent first checks the user's not enforced list. If a match is found there, access is allowed. If no match is found, the web agent checks the browser for an encrypted token identity. If one exists, the web agent retrieves the user's URL policy using the token information and allowed or denied access to the resource based on their policy. If there is no token identity, the user is redirected to their organization's authentication service.
|
Note
|
URL Policy Web Agents are bundled for installation separately from the iPlanet DSAME. Additional information can be found in the iPlanet Policy Agent Pack documentation.
|
Client Detection
DSAME has the capability to process requests from client browsers based on a number of protocols. The client detection module determines the protocol used by the requesting client browser and retrieves the pages formatted correctly for the client type. Since any client requesting DSAME services must first be successfully authenticated, client detection is accomplished within the authentication service.
When a client's HTTP request is passed to the DSAME, it is directed to the Authentication module. Within this framework, the first step in user validation is to identify the browser type using the HTTP request. The authentication service then uses this information to retrieve the browser type's DSAME characteristics. Based on this client data, authentication pages are sent back to the client browser (for example, HTML or WML pages). Once the user is validated, the client type is added to the session token where it can be retrieved by other DSAME services.
Client Data
In order to recognize requesting client types, DSAME stores their identifying characteristics. This information is defined in the iplanet-am-client-detection-client-types property of the amClientDetection.xml file. The client data is separated by a pipe ("|"): clientType=<value>|userAgent=<value>|contentType=<value>|cookieSupport=<value>|fileIdentifier=<value>|filePath=<value>.
The fields are defined as:
ClientType—an arbitrary string which uniquely identifies the client. The default is genericHTML.
UserAgent—a search filter used to compare/match the user-agent defined in the HTTP header. The default is Mozilla/4.0.
contentType—defines the HTTP requested content type. The default is text/html.
cookieSupport—defines whether cookies are supported or not. The default is true.
fileIdentifier—defines the extension of the client type files (templates and JSP). The default is html.
filePath—defines the location of the client type files (templates and JSP files). The default is html.
|
Note
|
Currently, DSAME only defines client data for HTML client types.
|
Installed Authentication Services
DSAME installs a number of authentication services (including the base service). This allows an administrator to choose from a variety of authentication methods with which to validate their defined organization's users. The services are:
Core — The core service is the configuration base for all authentication method modules. It must be registered to an organization before any user can login using one of the installed authentication method modules. (In addition, the specific authentication service needs to be registered.) It allows the DSAME administrator to define default values for core authentication parameters. They can then be picked up if no overriding value is set in the specific authentication service chosen. The core values are defined in the amAuth.xml file.
Anonymous — This service allows for log in without specifying a user name and password. Anonymous connections have limited access to the server and are customized by the DSAME administrator.
Certificate — This service allows login through a personal digital certificate (PDC). iPlanet Certificate Management System (CMS) can be installed as a Certificate Authority. For more information on CMS, see the documentation set located at http://docs.iplanet.com/docs/manuals/cms.html
LDAP — This service allows for authentication using LDAP bind, an operation which associates a user ID password with a particular LDAP entry.
Membership (Self-Registration) — This service allows a new user to self-register for authentication with a login and password.
RADIUS — This service allows for authentication using an external Remote Authentication Dial-In User Service (RADIUS) server.
SafeWord™ — This service allows for authentication using Secure Computing's servers and tokens.
Unix — This service allows for authentication using a user's UNIX identification and password.
Custom Authentication Services
The DSAME authentication module provides a framework that allows an organization to plug-in custom authentication services by calling the authentication APIs. The following sections provide information on how to create a custom authentication service as well as the interfaces and classes that must be implemented to run it.
Creating an Authentication Service
Create an XML file for the new authentication service.
-
The service XML file is written so that the authentication service's attributes (configurable parameters) can be managed using the DSAME console. The name of this file follows the format amAuthservicename.xml; for example, amAuthLDAP.xml or amAuthSafeWord.xml. More information on writing XML files using the sms.dtd can be found in Chapter 2 "DSAME And XML."
Create a screen configuration properties file.
-
A screen configuration properties file specifies the screen text that a user will see when directed to the authentication service's login page. This might include, but is not limited to, User Name and Password. The name of this file follows the format servicename.properties; for example, LDAP.properties or SafeWord.properties. The files are located, by default, in Install_Directory/SUNWam/web-apps/services/WEB-INF/config/auth/default. The directory will be different based on locale. Information on how to create the file can be found in "Configuring Screen Properties".
Create a localization properties file.
-
The localization properties file defines language-specific screen text for the service's attribute names. The name of the file follows the format amAuthservicename.properties; for example, amAuthLDAP.properties. The files are located in Install_Directory/SUNWam/locale/. This directory contains a sub-directory for each locale. More information on this file and how to configure it can be found in "Configuring Localization Properties".
Write a Java file which implements the API com.iplanet.authentication.spi.AuthenticationModuleFactory.
-
This API contains the method that obtains an instance of the authentication module.
Write a Java file which extends the API com.iplanet.authentication.spi.AuthenticationModule.
-
This API instantiates a class of the authentication module. Certain abstract methods must be overridden.
Compile the application using the Java Development Kit (JDK).
-
Information on how to compile a Java application can be found in the JDK documentation.
Modify the amAuth.xml file.
-
Altering this file to include the new authentication service allows the pluggable architecture to recognize it.
Integrate the service within the DSAME authentication module by using the amadmin command line tool.
-
Information on using amadmin can be found in the iPlanet Directory Server Access Management Edition Administration Guide.
Authentication Service XML Files
There are two XML files that need to be created and/or modified when creating a custom authentication service. The first file, amAuthservicename.xml, specifies the attributes that the service developer wants users and administrators to be able to configure using the DSAME console. The second file, amAuth.xml, defines the core authentication service.
amAuthservicename.xml
This file must be created for the new authentication service. Each authentication service has its own service XML file, for example, amAuthLDAP.xml or amAuthSafeWord.xml. The file specifies the attributes that a service developer wants users and administrators to be able to configure via the DSAME console. When creating it, an existing authentication service XML file can be copied and altered as needed. For information on writing a new service XML file, see Chapter 2 "DSAME And XML."
amAuth.xml
The amAuth.xml file defines the Core authentication service, the "parent" authentication service. After creating a new authentication service, this file must be modified in order for the authentication module to recognize the new service. This file must live in the Install_Directory/SUNWam/config/xml directory for all authentication modules to work. For information on modifying the amAuth.xml file, see Chapter 2 "DSAME And XML."
Authentication Service Properties Files
Typically, each authentication service in DSAME has two properties files: the screen properties file and the localization properties file. The screen properties file defines the screen text for the authentication service login page and the localization properties file defines locale-specific (or translated) screen text and messages for the whole service.
Configuring Screen Properties
The screen properties file specifies the screen text that a user will see when directed to that authentication service's login page. Each service's screen properties file is named using the name of the service followed by the extension .properties; for example, Anonymous.properties or LDAP.properties. By default, the file is in Install_Directory/SUNWam/web-apps/services/WEB-INF/config/auth/default. If the file is organization-specific, it is stored in the organization's own authentication directory Install_Directory/SUNWam/web-apps/services/ WEB-INF/config/auth_orgname. If the files are organization and locale-specific, it is stored in the organization's locale directory inside its specific authentication directory at Install_Directory/SUNWam/web-apps/services/WEB-INF/ config/auth/orgname/locale. (Information on configuring files per organization can be found in "Configuring An Organization's Screens" of Chapter 8 "GUI Customization.") To illustrate the "The Screen Properties File Directives", the LDAP.properties file has been copied below.
Code Example 3-1 LDAP.properties File
TIMEOUT 120
|
TEXT LDAP Authentication
|
TOKEN Enter UserId
|
PASSWORD Enter Password
|
|
SCREEN
|
TIMEOUT 240
|
TEXT Password Expiring Please Change
|
PASSWORD <REPLACE><BR> Enter Current Password
|
PASSWORD Enter New Password
|
PASSWORD Confirm New Password
|
|
SCREEN
|
TIMEOUT 120
|
TEXT Your password has expired. Please contact service desk to
reset your password.
|
|
The Screen Properties File Directives
The directives included in the configured screen properties file will depend on the requirements of the authentication method and the extent of the customization of the screen prompts. Table 3-1 discusses the directives.
Table 3-1 The Screen Properties File Directives
|
Directive
|
Description
|
|
SCREEN
|
Each SCREEN entry corresponds to one login page. The authentication module can set which screen is next, or it can allow the DSAME's auth servlet to progress through the screens sequentially.
|
|
TIMEOUT n
|
The TIMEOUT directive is used to ensure that users respond in a timely manner. If the time between when the page is sent and the user submits his response is greater than n seconds, a time-out page is sent.
|
|
TEXT
|
The TEXT directive specifies a title for the login page. Only one TEXT directive per SCREEN entry should be specified. If more than one is provided, the last one is displayed.
|
|
TOKEN yyy
|
The TOKEN directive is used to obtain the user's identification input. Within an HTML login page, it equates to the following tag:
<P><STRONG>yyy</STRONG><BR><INPUT TYPE="TEXT" NAME=TOKEN0>
where yyy is the text the user will see on the login page and INPUT specifies the input field for the user name or ID. When multiple input fields are used (such as user ID and password fields), successive numbers are appended to the name value TOKEN as in TOKEN0, TOKEN1, TOKEN2, etc. (The use of TOKEN here has no relation to a single sign-on token.)
|
|
PASSWORD zzz
|
The PASSWORD directive is used to obtain the user's password input. Within an HTML login page, it equates to the following tag:
<P><STRONG>zzz</STRONG><BR><INPUT TYPE="PASSWORD" NAME=TOKEN1>
where zzz is the text the user will see on the login page and INPUT specifies the input field for the password. When multiple input fields are used (such as user ID and password fields), successive numbers are appended to the name value TOKEN as in TOKEN0, TOKEN1, TOKEN2, etc.
|
|
IMAGE path
|
The optional IMAGE directive allows for the display of a custom background image on the page where path equals the direct path to the displayed image.
|
|
HTML path
|
This optional HTML directive allows for the use of a custom HTML page for the authentication screens. The path attribute equals the path to the HTML file which will be displayed, overriding the HTML file dynamically generated by the authentication service's .properties file. For more information on customizing a HTML login page, see "Authentication URL Parameters".
|
|
<REPLACE>
|
The REPLACE tag allows for the substitution of dynamic text for the static text descriptions, allowing for the dynamic generation of challenges or passwords. It is used in conjunction with the setReplaceText() method.
|
Note that the screen properties file may direct a certain number of screens to be displayed although not all of them will be. Code Example 3-1, LDAP.properties has defined three screens although the last two will only be displayed under certain circumstances.
|
Note
|
The screen properties file can also be empty. In such cases there is no login page; the credentials are specified in the URL or its part of the servlet request (as in the case of Certificate authentication).
|
Configuring Localization Properties
A localization properties file specifies the locale-specific screen text and localized messages that an administrator or user will see when directed to an authentication service's attribute configuration page. As an example, a portion of amAuthLDAP.properties is copied below. (The file is in the Install_Directory/SUNWam/locale/ directory.) The data following the equal (=) sign in each key/value pair (displayed in English here) would be translated to a specific language as necessary and copied into the corresponding locale directory. The alphanumeric keys (a1, a2, etc.) map to fields defined, in this example, in the amAuthLDAP.xml service configuration file with the i18nKey attribute.
Note that the alphanumeric keys determine the order in which the fields are displayed on a service page in the DSAME console. The keys are taken in alphabetical and then numerical order (a1, a2 is followed by b1, b2 and so forth). For example, if a new attribute is added and needs to be displayed at the top of the service page, the alphanumeric key should have a value of a1. The second attribute should then have a value of either a2 or b1, and so forth. Please note that a10 comes before a2.
Code Example 3-2 Portion of amAuthLDAP.properties
PasswdSame=Password should not be same
|
PasswdMinChars=Password should be atleast 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
|
...
|
|
Authentication URL Parameters
A custom HTML file can be written as an organization's login screen. This HTML file can then be dynamically generated from a value defined in the authentication service's properties file. For example, an organization wants its users to authenticate by entering a login ID and password in the HTML page, MyLogin.html. After entering the data and clicking the Submit button, the user will be taken directly to the page http://DSAMEServer:58080/MyURL.html. MyLogin.html will contain code that includes the ACTION tag as displayed in Code Example 3-3.
Code Example 3-3 URL Parameter Code for Authentication
<Html>
|
<Head>
|
<Title>
|
My Login Form
|
</Title>
|
</Head>
|
<Body>
|
<Form Name="login_form" Action="/amserver/login?module=LDAP "
Method="POST">
|
<Input Type="TEXT" Name=TOKEN0>
|
<Input Type="PASSWORD" Name=TOKEN1>
|
<Input Type="SUBMIT" Name=Submit Value=Submit>
|
</Form>
|
</Body>
|
</Html>
|
|
|
In the source code, the HTML tag ACTION has the value /amserver/login?module=LDAP. This string can be modified by passing different name/value pairs. These pairs are:
goto=URL—After successful login, DSAME redirects the user to this URL. It overrides the default URL. Example: http://dsame1.red.iplanet.com:8080/amserver/ login?goto=http://webserver.red.iplanet.com/webpage.html
gotoOnFail=URL—After unsuccessful login, DSAME redirects the user to this URL. Example: http://dsame1.red.iplanet.com:8080/amserver/ login?goto=http://webserver.red.iplanet.com/ForgotPassowrd.html
arg=newsession—This argument is typically used in the anonymous to authenticated user login scenario. It allows a login to destroy an existing session and perform a new login in one request. The user first hits the site with an anonymous session and then hits the Register or Login link. Example: http://dsameserver.sun.com/amserver/login?arg=newsession
module=AuthModule—Instead of using the configured authentication modules for an organization, the authentication module is specified via this URL parameter. Example: http://dsame1.red.iplanet.com:8080/amserver/login?module=LDAP
org=OrgString—The Authentication service figures out which organization OR sub-organization, the user is going to authenticate to based on the value of this parameter. If no org parameter is given, the service will use the host:port/URI portion of the URL.
page=n—This allows applications to go directly to a specific page of a login module. For example, if a module has 4 pages and an application wants to send a user directly to page 4 it would pass page=4 in the login request. This is typically used in conjunction with custom authentication modules. For example, http://dsameserver.sun.com/amserver/login?module=LDAP&TOKEN0=user&TOKEN1=password&page=1 http://dsame1.red.iplanet.com:8080/amserver/login?goto= http://wevserver.red.iplanet.com/webpage.html&page=1
iPSPCookie—To enable persistent cookies in DSAME, this parameter must be specified as true in the login URL: iPSPCookie=true. Persistent cookies must also be enabled in the Core Authentication service. This typically is used by portals with the Remember my username and password feature as it allows the user to restart their browser while retaining their session.
Authentication APIs
The authentication APIs are organized in a package called com.iplanet.authentication.spi. It contains the classes, interfaces and methods needed to write a customized authentication service.
|
Note
|
The Overview page for the complete set of public Javadocs can be accessed at Install_Directory/SUNWam/docs/index.html.
|
Authentication API Overview
Each time a user attempts to access a protected resource, a new instance of the authentication Java class is created. (The reference to the class is released once the authentication session has either succeeded or failed.) When an authentication session is invoked, one login page is sent to the browser for each screen directive defined in the screen properties file although not all screens will need to be displayed. The first directive would send a login page asking the user to enter a user identification and a password. When the user submits the information, the validate() method is called. The module gets the information tokens, validates and returns them. If applicable, a second screen is sent and the validate() method is called again. (In the LDAP.properties Code Example 3-1, a second screen would be sent only to a user whose current password is expiring.) When multiple screens are sent to the user, the tokens from a previous screen can be retrieved by using the getTokenForState methods. (Each screen is referred to as a state.) The authentication module keeps all tokens from previous states until authentication is complete.
Naming Conventions
The following naming convention is recommended when creating the custom authentication service. If the new authentication service class is named servicename.java, the authentication module factory class should be named servicenameAuthenticationModuleFactory.java. In addition, the use of upper and lower case letters should be consistent. If the new authentication service class is named NewAuth.java, the authentication module factory class should be named NewAuthAuthenticationModuleFactory.java.
AuthenticationModuleFactory Interface
The AuthenticationModuleFactory interface must be implemented for each custom authentication module. This top-level class contains the newAuthenticationModule() method which creates a new instance of the AuthenticationModule class. This new instance defines the authentication module being customized.
AuthenticationModule Class
The AuthenticationModule class extends the Authenticator class which defines basic methods used in the authentication service. The AuthenticationModule class contains more detailed methods. The instance of the AuthenticationModule class must override the validate(), init(), and getUserTokenId() methods.
The init() method should be used if the class has any specific initialization requirements such as loading a JNI library. init() is called once for each instance of the class. Once a login session is completed, the reference to the class is released.
The validate() method is called for each authentication page specified in the screen properties file and validates the entered credentials and thus, the user. At the point of authentication failure, it throws an AuthenticationException. The reason for failure can be an argument to the exception and will be logged in the DSAME authentication log.
The getUserTokenId() method is called once at the end of a successful authentication session. A login session is deemed successful when all pages in the screen properties file have been sent and the module has not thrown an exception. The method retrieves the authenticated token string that the authenticated user will be known by in the DSAME environment.
|
Note
|
If the instance of DSAME participates in the User Lockout feature, the validate() method throws an InvalidPasswordException after n attempts at login. In order to support this feature, the getUserTokenId() method should be set to return the user ID before the exception is thrown.
|
LoginWorkerFactory
The LoginWorkerFactory interface must be implemented for each custom non-HTML authentication module. This top-level class contains the newLoginWorker() method which creates a new instance of the LoginWorker class. The new instance generates the UI for the authentication module being customized.
|
Note
|
Any static data or reference to any static data in the authentication module must be thread-safe.
|
Sample Authentication Service
A sample authentication program has been provided in the directory, Install_Directory/SUNWam/samples/authentication/providers. It includes the following files:
AuthenticationSample.jar
AuthenticationSample.java
AuthenticationSample.properties
AuthenticationSampleAuthenticationModuleFactory.java
Readme.html
The Readme.html file explains how to compile, deploy and run the Authentication Sample program. It is copied below.
Authentication Sample: Readme.html
The Readme.html file explains how to compile, deploy and run the Authentication Sample program.
Steps to compile the Authentication Sample program
Set the following environment variables.
-
These variables will be used to run the gmake command. You can also set these variables in the Makefile. This Makefile is in the same directory (Install_Directory/SUNWam/samples/authentication/providers) as the Authentication Sample program files.
JAVA_HOME - Set this variable to your installation of JDK. The JDK should be newer than JDK 1.2.2.
CLASSPATH - Modify the /opt to the base of your installation. Install_Directory/SUNWam/web-apps/services/WEB-INF/lib directory.
BASE_CLASS_DIR - Set this variable to the directory where all the Sample compiled classes are located.
JAR_DIR - Set this variable to the directory where the JAR files of the Sample compiled classes will be created.
Go to the Install_Directory/SUNWam/samples/authentication/providers directory and run gmake.
Steps to deploy the Authentication Sample program
Copy AuthenticationSample.jar from JAR_DIR to Install_Directory/SUNWam/web-apps/services/WEB-INF/lib".
Copy AuthenticationSample.properties from Install_Directory/SUNWam/samples/authentication/providers to Install_Directory/SUNWam/web-apps/services/WEB-INF/config/auth/default.
|
Note
|
The properties file name should be the same as the Authentication Sample module name.
|
Modify Install_Directory/SUNWam/web-apps/services/WEB-INF/config/xml/amAuth.xml to include the Authentication Sample in the Authentication menu choices and in the Authenticator's list (in Admin Console) as follows:
Code Example 3-4 amAuth.xml After Modification
<AttributeSchema name="iplanet-am-auth-menu"
|
type="multiple_choice"
|
syntax="string"
|
i18nKey="a1">
|
<ChoiceValues>
|
<Value>LDAP</Value>
|
<Value>Radius</Value>
|
<Value>Membership</Value>
|
<Value>Anonymous</Value>
|
<Value>Cert</Value>
|
<Value>AuthenticationSample</Value>
|
</ChoiceValues>
|
<DefaultValues>
|
<Value>LDAP</Value>
|
</DefaultValues>
|
</AttributeSchema>
|
.....
|
.....
|
.....
|
<AttributeSchema name="iplanet-am-auth-authenticators"
|
type="list"
|
syntax="string"
|
i18nKey="a17">
|
<DefaultValues>
|
<Value>com.iplanet.authentication.modules.radius.Radius</Value>
|
<Value>com.iplanet.authentication.modules.ldap.LDAP</Value>
|
<Value>com.iplanet.authentication.modules.membership.Membership<
/Value>
|
<Value>com.iplanet.authentication.modules.anonymous.Anonymous</V
alue>
|
<Value>com.iplanet.authentication.modules.cert.Cert</Value>
|
<Value>com.iplanet.authentication.modules.application.Applicatio
n</Value>
|
<Value>com.iplanet.am.samples.authentication.providers.Authentic
ationSample</Value>
|
</DefaultValues>
|
</AttributeSchema>
|
|
|
Make a backup copy amAuth.xml.
Delete iPlanetAMAuthService entry and then import (the modified) amAuth.xml using amadmin.
cd <install-root>/SUNWam/bin
./amadmin --runAsDN uid=amAdmin,ou=People,<default_org>,<root_suffix> --password <password> --deleteService iPlanetAMAuthService
./amadmin --runAsDN uid=amAdmin,ou=People,<default_org>,<root_suffix> --password <password> --schema amAuth.xml
Add the AuthenticationSample.jar file path to the Web server JVM classpath:
cd Install_Directory/SUNWam/servers/https-<host>.<domain>/config
Modify jvm12.conf to add Install_Directory/SUNWam/web-apps/services/WEB-INF/lib/AuthenticationSample.jar path to the JVM classpath.
Steps to run the Authentication Sample program
Restart DSAME server Install_Directory/SUNWam/web-apps/services/WEB-INF/bin/amserver start.
Log in to the DSAME console by entering the URL http://<host>.<domain>:<port>/<Deploy-URI>/console.
Select the User Management view.
Select your organization and select services from the Show menu.
Click on the DSAME Core Authentication properties icon.
Add the Authentication Sample class in Pluggable Auth Module Classes.
Select AuthenticationSample from Authentication Menu.
Click Submit to save changes and log out.
Enter the URL http://<host>.<domain>:<port>/<Deploy-URI>/login and select AuthenticationSample from Authentication Menu OR enter the URL http://<host>.<domain>:<port>/<Deploy-URI>/login?module=AuthenticationSample.