Previous     Contents     DocHome     Next     
Directory Server Access Management Edition Programmer's Reference Guide



Chapter 2   Pluggable Authentication SPI


DSAME provides an Authentication and Single Sign-On (SSO) framework with a plug-in architecture. The authentication mechanisms supported in DSAME 5.0 are:

  • LDAP—Authenticates a user using LDAP (Lightweight Directory Access Protocol).

  • Certification-based—Authenticates a user using a Personal Digital Certificate (PDC).

  • RADIUS—Authenticates a user through an external RADIUS server.

  • Membership (Self-registration)—For new user self-registration and login.

  • Anonymous—Any user can log into DSAME as an anonymous user with limited access. Anyone can access it without providing a bind DN or password.

The plug-in framework for authentication provides a way for customers to plug in their own authentication mechanisms. The SSO solution provided by DSAME is primarily for web-based applications. This solution provides a mechanism by which end users need to authenticate only once, and then can access multiple web-based applications without having to re-authenticate. (See Authentication Process Overview for information on authentication architecture and how authentication interacts with the SSO feature.)



Overview of Pluggable Authentication SPI


This chapter describes requirements for writing a supplemental authentication module (SPI—service provider interface) to plug into iPlanet DSAME and provides information on customizing the authentication pages.

The section Authentication Process Overview describes the architecture of the authentication component and its public interfaces. The Section "Writing and Integrating a Pluggable Authentication Module" on page 42 gives information on how to write and integrate a pluggable authentication service (module). See Table 2-1 on page 28 for a list of common tasks related to customizing pluggable authentication modules, and where to find information on them.


Table 2-1    Tasks to Customize Authentication

If you want to

Do

Change login prompts  

Edit the .properties file associated with the login screen that you want to change. See "Understanding the screen.properties File".  

Add authentication capability  

  

Selectively enable or disable auth modules  

Refer to DSAME Administration Guide  

Customize prompts and appearance for specific organizations or sub-organizations  

Refer to DSAME Administration Guide.  


Tip Before beginning to write authentication modules, contact the iPlanet Solutions sales representative to find out if the module needed has already been written and is available from internal resources.


For additional authentication capabilities, use the information in this chapter to write a custom authentication module and integrate it into the iPlanet Directory Server Management Access Edition product.



Authentication Process Overview


The architecture of DSAME's authentication is shown in Figure 2-1. It has three layers:

  • client interface (Authentication Service) using HTML/HTTP

  • framework

  • authentication module interfaces (plug-in SPIs)

Each of these layers is discussed in the following paragraphs.


Client Interface (Authentication Service using HTML/HTTP)

DSAME authentication provides two client interfaces, only one of which is exposed in DSAME 5.0—the Authentication Service which provides an HTML over HTTP interface. (A "public" or "exposed" interface is one that customers can customize to create their own service or module.) Application developers can customize the HTML templates to create new authentication login, logout, and timeout screens. (For more information, see Chapter 3 "HTML Templates.)

Although there are two client interfaces, both use the same underlying authentication framework and authentication modules. Figure 2-1 shows the different authentication components and how they interact within the authentication architecture.

Figure 2-1   

Authentication Architecture


Authentication Service Provided as HTML over HTTP(s) Interface

The Authentication Service is provided as a service within a servlet container using the Java Servlet SDK. Thus, the authentication service can be deployed in an iPlanet Web Server or an iPlanet Application Server that supports a servlet container. As shown in Code Example 2-7, the client interface provided by the Authentication Service is HTML over HTTP(s), which makes it convenient to use with a Web browser.

In a typical scenario, the Authentication service (which is a URL) would be a login page for an organization or a service, or users would be re-directed to the authentication service URL when they access a resource that is protected. The authentication service would then guide the user through a series of one or more screens in the process of gathering credentials (such as user name, password, employee number, etc.), based on the requirements of the authentication modules that were configured. For simple authentication modules like LDAP, the required credentials would be user name and password and could be obtained in one screen. However, for complicated challenge-response type authentication algorithms, more login screens might be required. (For information on customizing the login, logout, and timeout screens, see Chapter 2 "Pluggable Authentication SPI.)

After the user has provided the required credentials, the authentication service relies on the framework to determine if the user has been successfully authenticated. If the authentication process is successful, the user is re-directed to an organization or service home page (URL). If the authentication process fails, the user is re-directed to an error page (URL). Both the re-direction URLs can be configured by the administrator. (For information, see the iPlanet Directory Server Administrator's Guide.)

After a user has been authenticated successfully, he or she is issued an encrypted SSO token identity using the cookie. This SSO token can be used to access different applications without having to re-authenticate. (The SSO token identity can be thought of as similar to a session identity). Also associated with the SSO token identity are attribute-value pairs, which would have information about the user's name, authentication level, authentications performed, etc. The SSO token identity can also be configured by an administrator to expire based on timeouts. (For information, see the iPlanet Directory Server Administrator's Guide.)


Authentication Service Features
The features provided by the Authentication Service (HTML over HTTPs) are:

  • presentation using HTML and can be accessed through any Web browser

  • integration with SSO by setting the SSO cookie

  • configurable support to re-direct users with successful authentication

  • configurable support to handle authentication failures

  • support for authentication timeout, if users do not respond with credentials within specified time.


Authentication Framework

This is the middle tier of DSAME's authentication component which connects the client interfaces to the authentication modules. Features provided by authentication framework are:

  • configuration of authentication modules based on organization, role, or user

  • chaining of authentication modules

The authentication component uses the Service Management Services DTD (sms.dtd) to represent its configuration in a XML file. (See Chapter 5 "Understanding DSAME XMLs and DTDs for information on service XMLs.)


Authentication Plug-In Module Interfaces (SPI)

The authentication component provides a pluggable authentication framework allowing customers to plug in their authentication mechanism.

The authentication mechanisms supported in DSAME 5.0 are:

  • LDAP

  • Certificate (PKI)

  • RADIUS

  • Membership (self-registration)

  • Anonymous

  • Core—Core authentication provides configuration for the authentication service itself. This Core authentication configuration is used by all other authentication modules.

    All authentication services require that the Core authentication service be configured; it must always be configured in Admin Console. The Core authentication service is a key internal DSAME service, like Session, Logging, etc. and has its own profile. The Core authentication service can be considered the "driver" of the other authentication services. The Core authentication can call any of the other configured authentication services (LDAP, RADIUS, etc.)

    The Core authentication service lets you select which authentication modules users will see in Admin Console when they go to an organization, and lets you select when a user gets redirected to another login page, which page (URL), etc. The other authentication services do things like validate credentials.



Overview of Integrating Authentication Modules in DSAME

Every authentication service in DSAME has the following components it needs and interacts with:

  • a screen .properties configuration file; for example, LDAP.properties or AuthenticationSample.properties;

    The authentication framework loads these properties into the display, and passes your input to the authentication module. It displays each screen one at a time, as part of the authentication process. Your customized authentication plug-in module can similarly read and display input and display it on the screen as part of the authentication process. The HTML for the authentication states is dynamically generated based on the parameters set in the .properties configuration file for the authentication module developed.


Note The HTML that is dynamically generated can be overridden. See the "Understanding the screen.properties File" for more information.


  • an I18N .properties file, sometimes also called a "resource bundle" .properties file; for example, LDAP.properties. This file holds all the key/value pairs for the I18N key defined in the Java and XML files.

  • one factory class that implements com.iplanet.authentication.spi.AuthenticationModuleFactory

  • one module class that extends com.iplanet.authentication.spi.AuthenticationModule

  • the amAuth.xml file, which is used by all the internal authentication modules, and an XML file for your customized authentication module or service (for example, <your_custom_auth_module>.xml file).

After the authentication module has been written and integrated, an administrator must configure it from Admin Console so that the module knows where to retrieve this information. For information on configuring authentication modules, see the iPlanet Directory Server Access Management Edition Installation Guide.


Where to find the Public Javadocs for Authentication SPIs

The Javadocs for the following three public authentication interfaces

  • com.iplanet.authentication.spi.AuthenticationModuleFactory

  • com.iplanet.authentication.spi.AuthenticationModule

  • com.iplanet.authentication.spi.AuthenticationException

can be found in the javadocs directory of the product build, or at

http://yourserver:port/docs/en_US/javadocs


Classes and Methods you must Implement when creating a custom Authentication Service

The following sections provide information on the classes and methods you must implement in the sample authentication module, or when writing your own custom authentication service.


AuthenticationModuleFactory Methods that must be Implemented
The DSAME authentication framework implements the factory model for the pluggable authentication modules. You must implement the

  • com.iplanet.authentication.spi.AuthenticationModuleFactory class.

  • newAuthenticationModule() method—This method will create a new instance for the pluggable module you implemented.


AuthenticationModule Methods that must be Implemented
You must implement the following three methods when writing a new pluggable authentication module:

  • The init() method which reads the hostname, password, etc.

  • The second method you need to override is validate(). This is how you control the flow of screen. The validate method validates the user. This method is called by the authentication framework.

  • The third method you must override is getUserTokenId(). It gets the user token ID. The getUserTokenId() method tells the authentication framework who the user (who has just authenticated) is.

The authentication framework controls the entire login process and which authentication module(s) are used to authenticate users.


Do You need to create a Service XML for your custom Authentication Service

Writing a service XML file is optional, whether it is for a service other than authentication, or for a custom authentication service. The only case where service developers need to write a service XML file (such as for a custom authentication service) is when he/she wants certain configuration parameters (attributes) to be manageable from the DSAME Console. The primary purpose of the service XML files is for specifying any attributes (configuration parameters) that service developers want users and administrators to be able to configure from the DSAME Admin Console. The primary purpose of the service XML files is to feed in configuration parameters with default values set, to make them configurable from Admin Console. The APIs handle everything else behind the scenes.

It is important to note that in DSAME 5.0, because much of the DSAME SDK is not public and customizable, you cannot manage the global and organization attribute/value pairs through your external application (you cannot read and write them). The global and organization attributes are not public in this release, relative to writing customized external services.

However, when defining custom authentication service XMLs, you would typically only use the global and organization attribute types, in the DSAME 5.0 release.


Determining when an authentication service XML is necessary
To determine whether you even need to write a service XML file for your authentication service, a service developer must determine whether your authentication service has custom attributes, whether it has configuration parameters that should be configurable from the DSAME Admin Console, such as port_number, server names, etc. And if it does, does he/she want that data to be manageable and retrievable through the DSAME Admin Console. For example, do you want administrators and users to be able to go to the Authentication menu, and configure their server per organization, or port per organization, or is it a configuration parameter (attribute) that does not need to be configurable through Admin Console.

If it is determined that the configuration parameters do not need to be manageable (settable and gettable) through the DSAME Admin Console, then the service developer only needs to write a custom authentication service, but he/she would not need to create a service XML file for the authentication module.

The only reason for authentication service XMLs is to make various configuration parameters configurable from the DSAME Admin Console. (This does not necessarily apply to all service XMLs, because you can group some attributes and put them into a service to make them manageable by administrators and users through DSAME Admin Console.)

The service XML file is a way to let service developers define attributes (configuration parameters) to be configurable from Admin Console, upon which administrators and users can set and get the values. It is up to the application or service to interpret the behavior of the attribute/value pairs specified in the service XML files.


When writing a custom authentication service, only global and organization attributes are used
When defining a service XML file for a custom authentication service, you typically only use "global" and "organization" attributes in DSAME 5.0. Global and organization attribute/value pairs can be read and gotten through the pluggable authentication APIs, which has methods to read and get their attribute values. Authentication service is configured only on a per-organization basis.


When writing custom authentication service, you don't need to update Directory server schema
Because you are defining attributes of type "global" or "organization", you do not need to update the Directory server schema. The global and organization attributes are stored in Directory server as static blobs of data in Directory server; they are not read or stored as LDAP entries.

For the DSAME 5.0 release, because the global and organization attributes are not public in this release, service developers don't have to update the LDAP schema in Directory server if they want to run a custom authentication service. This is because the authentication service uses an exposed pluggable Authentication API that can read and get your authentication service's configuration.


Core Authentication Service Defines Configuration for all Authentication Services

The amAuth.xml file is used by the Core authentication service for its configuration. It can be thought of as a "general" or "parent" authentication service XML file for the all of the authentication services (whether internal to DSAME or external authentication applications). This file must be in the <dsame_root>/web-apps/services/WEB-INF/config/xml directory for the authentication modules to work. Each authentication service must also have its own service XML file, for example, amAuthLDAP.xml, amAuthRADIUS.xml, etc. Similarly, when writing a custom pluggable authentication service, you must create a new service XML file, for example, <your_custom_auth_module>.xml (in addition to making modifications to the Core authentication service).



Understanding the screen.properties File


The screen .properties file is the configuration file for an authentication module. Each authentication module must have a screen .properties configuration file. The file specifies the text, tokens, and password prompts for the login pages associated with the authentication module.

The HTML for the authentication states is dynamically generated based on the parameters set in the .properties configuration file for the authentication module developed. The HTML that is dynamically generated can be overridden with an HTML tag in the .properties file. For example, if a screen in a .properties file has the tag "HTML", the authentication service will read in the entire HTML file specified and display that unmodified instead of dynamically generating the HTML. For example, the screen in Code Example 2-1 wold display "mycustomhtml.html" instead of generating the HTML.

Code Example 2-1    Sample Screen calling an HTML file
SCREEN
TIMEOUT 120
TEXT LDAP Authentication
TOKEN Enter UserId
PASSWORD Enter Password
HTML mycustomhtml.html

The authentication module's .properties file name must be named using the base class name of the authentication module (no package name) and the extension .properties. There is a sample .properties configuration provided in the <dsame_root>/SUNWam/samples/authentication/providers directory called AuthenticationSample.properties. There must be a .properties configuration file with the name of the class (no package name) and the extension .properties; for example, LDAP.properties or AuthenticationSample.properties, or <your_custom_auth_module>.properties.

When deploying your customized pluggable authentication module, you must make sure that the .properties file is copied or located in <DSAME_root>/SUNWam/web-apps/services/WEB-INF/config/auth
/default directory, or the auth/locale directory. The authentication service will look for its configuration files in the <DSAME_root>/SUNWam/web-apps/services/WEB-INF/config/auth
/default directory, by default. If the files are organization-specific, then it will in the <DSAME_root>/SUNWam/web-apps/services/WEB-INF/config/auth
/orgname directory. If the files are organization and locale-specific, the authentication service will look for its configuration files in the <DSAME_root>/SUNWam/web-apps/services/WEB-INF/config/auth
/orgname/locale directory.

Table 2-2 discusses the directives that can be included in a .properties file.


Table 2-2    The .properties File Directives 

Directive

Description

SCREEN  

Each SCREEN entry corresponds to one authentication state (authentication HTML page). The authentication module can set which screen is next, or it can allow the iPlanet Portal Server's auth servlet 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 is similar to a title for the page, and the text <xxx> appears at the top of the screen area provided for the auth module. Only one TEXT directive per SCREEN should be specified. If more than one is provided, then the last one is displayed.  

TOKEN yyy  

The TOKEN directive equates to the following HTML:

<P><STRONG>yyy</STRONG><BR><INPUT TYPE=TEXT NAME=TOKEN0>

The input field's name starts at TOKEN0 and increments with each TOKEN or PASSWORD directive specified per SCREEN.  

PASSWORD zzz  

The PASSWORD directive equates to the following HTML:

<P><STRONG>yyy</STRONG><BR><INPUT TYPE="PASSWORD" NAME=TOKEN0>

The input field's name starts at TOKEN0 and increments with each PASSWORD or TOKEN directive specified per SCREEN.  

IMAGE image-path  

The optional IMAGE directive allows authentication module writers to display a custom background image on each page.  

HTML  

The HTML parameter allows the module writer to use a custom HTML page for the authentication screens.  

<REPLACE>  

The REPLACE tag allows a module writer to substitute dynamic text for the accompanying text descriptions. This allows a module writer to dynamically generate challenges or passwords.

Used in conjunction with the setReplaceText() method.  

The specific directives included will depend on the requirements of the authentication method and the extent of customizing the appearance of the prompts and displays through the authentication process.

Each SCREEN entry corresponds to one authentication state or authentication HTML page. When an authentication session is invoked, one HTML page is sent for each state. The first state sends an HTML page asking the users to enter a token and a password. (Your authentication module can control the order; by default, it is sequential.) When the users submit the token and the password, the validate() method is called. The module gets the tokens, validates them, and returns them. The second page is then sent and the validate() method is again called.

If the module throws a LoginException, an authentication failed page is sent to the user. If no exception is thrown, which implies successful completion, the users are redirected to their default page. The TIMEOUT directive is used to ensure that the users respond in a timely manner. If the time between sending the page and the response is greater than the TIMEOUT value, a time-out page is sent.

When multiple pages are sent to the user, the tokens from a previous page may be retrieved by using the getTokenForState methods. Each page is referred to as a state. The underlying authentication module keeps the tokens from the previous states until the authentication is completed.

Each authentication session creates a new instance of the authentication Java class. The reference to the class is released once the authentication session has either succeeded or failed.


Note

Any static data or reference to any static data in the authentication module must be thread-safe.


Code Example 2-2    Sample.properties File
TEXT This is a sample login page
TOKEN First Name
TOKEN Last Name

SCREEN
TIMEOUT 30
TEXT You made it to page 2
PASSWORD Just enter any password

SCREEN
TIMEOUT 60

TEXT You made it past the first page
TOKEN Enter <REPLACE>'s favorite beer
PASSWORD Enter <REPLACE>'s favorite wine

SCREEN
TEXT 4th page
PASSWORD any password
TOKEN anything here

The .properties file (for example, for the LDAP authentication module, see LDAP.properties in Code Example 2-7) interacts with the authentication program, and displays a screen or multiple screens to a user in the process of authenticating the user. This might be a multi-step process for the user to authenticate, which may prompt the user for multiple inputs. Each screen corresponds to a step in the user authentication process. For example, when a user logs into the LDAP authentication module, it is the .properties file that provides the fields and text that appear on the authentication screens. For example, the LDAP.properties file describes text fields that describes the screen (such as "LDAP Authentication"), tokens (fields) that prompt the user to enter his/her userid, password prompt text, and timeout settings (for example, "120" might give the user 120 seconds to authenticate, after which it times out).

When writing a pluggable authentication module, you must follow the format specified for the .properties file. For example, the "TEXT" field specifies the title of the authentication HTML page. The "TOKEN" field (or keyword) specifies what displays on the authentication HTML screen or page. The "PASSWORD" field or keyword specifies what is displayed on the authentication HTML page. The "HTML" field or keyword can be used to specify that an entire HTML file be read in and displayed unmodified, instead of dynamically generating the HTML. (See Section "Understanding the screen.properties File" on page 36.)


Product Directories where .properties and Sample .java Files are Located

To see a sample .properties file and some sample authentication programs (.java files), go to the <server_root>/samples/authentication/providers directory.) The .properties files for the supported authentication modules (LDAP, Certificate-based, RADIUS, Membership, and Anonymous) are located in the <DSAME_root>/SUNWam/web-apps/services/WEB_INF/classes directory.


Note

A TOKEN in a .properties file is like a keyword or field; it has no relation to an SSO token.


Every authentication module (for example, LDAP, RADIUS, Certificate-based, Membership (Self-registration), and Anonymous) has a .properties file. After a customization engineer creates a new application or service, he or she must copy the .properties file to the <DSAME_root/web-apps/services/WEB-INF/config/auth/default directory. (See Section "Writing and Integrating a Pluggable Authentication Module" on page 42 for information on how to integrate a custom authentication service.)


Use an existing service XML file to create your Custom Authentication XML

When writing a custom authentication service, you could typically use one of the existing internal authentication service XML files (for example, amAuthLDAP.xml) which is provided in DSAME, and create a copy which you can then customize with your custom authentication service's attributes. After loading in this new service XML file using the amadmin CLI tool, make sure you rename the XML file with the name of your custom authentication module.


amAuth.xml is Used for General Authentication Configuration

The amAuth.xml file defines the Core authentication service, which is the overall configuration file for authentication. It defines attributes that are used by the Core authentication service (which defines the overall authentication configuration).

When creating a custom authentication service, customization engineers must modify the amAuth.xml file to include their custom authentication module .class file (com.iplanet.authentication.spi.AuthenticationSample.class, for example) in the Authentication menu choices and in the Authenticator's list. (See Section "Writing and Integrating a Pluggable Authentication Module" on page 42.)

For some information on when a service developer would need to write a custom authentication service XML, see the Section "Do You need to create a Service XML for your custom Authentication Service" on page 34.


Note

The Core authentication service (defined in amAuth.xml) defines overall authentication configuration. The administrator must always configure the Core authentication module in DSAME Console.


For information on configuring the various authentication modules supported, see the iPlanet Directory Server Access Management Edition Administration Guide.



Writing and Integrating a Pluggable Authentication Module


The following sections discuss the requirements and recommendations to follow when writing a new authentication module.


Requirements and Recommendations

A pluggable authentication module for iPlanet DSAME must override certain methods in the AuthenticationModule class and the AuthenticationModuleFactory interface and should adhere to specific naming conventions and standards for easy integration.


Note

For a list and description of the methods used to write the authentication module, see the JavaDocs at
  http://yourserver:port/docs/en_US/javadocs


  • Write your authentication module class which extends and subclasses methods in com.iplanet.authentication.spi.AuthenticationModule

  • Override the validate(), init(), and getUserTokenId() methods

    The validate method replaces the input gathering method. Each time the user submits an HTML page, the validate() method will be called. In the method, authentication-specific routines are called. At any point in this method, if the authentication has failed, the module must throw a LoginException. If desired, the reason for failure can be an argument to the exception. This reason will be logged in the iPlanet Portal Server authentication log.

    init() should be used if the class has any specific initialization such as loading a JNI library.
    init() is called once for each instance of the class. Every authentication session creates a new instance of the class. Once a login session is completed the reference to the class is released.

    getUserTokenId() is called once at the end of a successful authentication session by the iPlanet Portal Server authentication server. This is the string the authenticated user will be known as in the iPlanet Portal Server environment. A login session is deemed successful when all pages in the .properties file have been sent and the module has not thrown an exception.

  • Write your authentication module factory class which implements the com.iplanet.authentication.spi.AuthenticationModuleFactory interface

    You must also implement the AuthenticationModuleFactory interface when creating a pluggable authentication module. The AuthenticationModuleFactory interface defines a factory API which enables the authentication framework to obtain an instance of the corresponding authentication module. It creates a new instance of an AuthenticationModule object for an authentication module.This could be implemented by calling the corresponding constructor of your pluggable authentication module.


    Note
    • The newAuthenticationModule method is not synchronized.


    The implementation of your pluggable authentication module should be thread-safe.


Recommendations

Naming the authentication module and factory classes you write in the following way allows (and forces) the module's class file to be installed with the other authentication modules provided with the iPlanet DSAME software:

If your authentication module class is named <your_custom_auth_module>.java, then name your authentication module factory class <your_custom_auth_module>AuthenticationModuleFactory.java


Compiling the Authentication Sample

Do the following to compile the Authentication Sample program (or a pluggable authentication module that you write at your site). The Authentication Sample is provided in the <dsame_root>/samples/authentication/providers directory:


Set Environment Variables

  1. Set the following environment variables.

    These variables are used to run the gmake command. You can also set these variables in the makefile. The Makefile is located in the same directory (<dsame_root>/SUNWam/samples/authentication/providers) as the Authentication Sample program files.

    1. JAVA_HOME —Set this variable to the directory pathname where your JDK is installed. The JDK should be newer than JDK 1.2.2.

    2. CLASSPATH—Set this variable to the location of the dai.jar file, which is located in <dsame_root>/SUNWam/web-apps/services/WEB-INF/lib

    3. BASE_CLASS_DIR—Set this variable to the directory where all the sample compiled classes are located.

    4. JAR_DIR—Set this variable to the directory where the JAR files (.jar) of the Sample compiled classes will be created.


Run the Make Command

  1. Go to the <dsame_root>/SUNWam/samples/authentication/providers directory and run

    make


Integrating the Authentication Sample program

Do the following to integrate, or deploy, the AuthenticationSample program (or a pluggable authentication module that you write):

  1. Copy <your_custom_auth_module>.jar from the <JAR-DIR> directory to:

    <dsame_root>/SUNWam/web-apps/services/WEB-INF/lib

  2. Copy <your_custom_auth_module>.properties file (or the AuthenticationSample.properties file if you using the sample files) to:

    <dsame-root>/SUNWam/web-apps/services/WEB-INF/config/auth/default
    Note The .properties filename should be similarly named as <your_custom_auth_module>.properties; for example, AuthenticationSample.properties.


  3. Modify <dsame-root>/SUNWam/web-apps/services/WEB-INF/config/xml/
    amAuth.xml     to include your custom sample (or the AuthenticationSample) in the Authentication menu choices and in the Authenticators list in DSAME Admin Console as follows:

Code Example 2-3    Excerpt from amAuth.xml File
<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>

  1. In addition to modifying the amAuth.xml file, you might need to create a new service XML file for your custom authentication module.

  2. Back up the iPlanetAMAuthService by using db2ldif:

    1. cd <directory_install_root>/slapd-<hostname>

    2. ./db2ldif -n userRoot -s "ou=iPlanetAMAuthService,ou=services,<root_suffix>"

  3. Delete the iPlanetAMAuthService entry using amadmin:

    1. /etc/init.d/amserver stop

    2. cd <install-root>/SUNWam/web-apps/services/WEB-INF/bin

    3. ./amadmin -runAsDN uid=amAdmin,ou=People,<default_org>,<root_suffix> --password <password> --deleteService iPlanetAMAuthService

  4. Import the (modified) amAuth.xml file using the amadmin CLI tool:

    1. ./amadmin -runAsDN uid=amAdmin,ou=People,<default_org>,<root_suffix> --password <password> --schema amAuth.xml

  5. Import the new service XML file for the pluggable authentication module that you have written, using amadmin:

    1. ./amadmin -runAsDN uid=amAdmin,ou=People,<default_org>,<root_suffix> --password <password> --schema <your_custom_auth_module>.xml


Note

The new service XML file should include only the attributes to be updated.

Also, the authentication module does not have to have a service XML file unless it has configuration attributes that will need to be manageable through the DSAME Admin Console. An example of configuration attributes that would need to be manageable through Admin Console are port numbers, defaults, and server locations.


  1. Add <your_custom_auth_module>.jar file pathname (or the AuthenticationSample.jar file pathname) to the Web server JVM classpath:

    cd <install-root>/SUNWam/servers/https-<host>.<domain>/config

  2. Modify the jvm12.conf file to add <install-root>/SUNWam/web-apps/services/WEB-INF/lib/AuthenticationSample.jar path to the JVM classpath.


Running the Authentication Sample program

Do the following steps to run the AuthenticationSample program:

  1. Restart the DSAME server:

    <install-root>/SUNWam/web-apps/services/WEB-INF/bin/
    amserver start

  2. Log in to the DSAME console by entering the URL

    http://<host>.<domain>:<port>/amserver/console

  3. Select the User Management view.

  4. Select your organization and select Services from the Show menu.

  5. Click on DSAME Core Authentication properties.

  6. Add AuthenticationSample from the Authentication menu.

    When you log in, you can choose either LDAP or your custom authentication module.


Note

Do not de-select LDAP.


  1. Click Submit to save changes and log out

  2. Enter the URL

    http://<host>.<domain>:<port>/amserver/login

    and select your custom authentication module (or the AuthenticationSample) from the Authentication menu.


    Note

    If you select your new authentication module and it keeps returning to the Authentication menu, check that your CLASSPATH variable setting is correct in the jvm12.conf file. Also check the package.classname in amAuth.xml file; make sure they match.

    Also check the amAuth debug file for errors.


    or

    Enter the URL

    http://<host>.<domain>:<port>/login?module=
    your_custom_auth_module


Sample Code

The following samples show the form and content of the files associated with an authentication module:

  • Sample Properties File

  • Sample Authentication Module Source

  • Sample Authentication XML File


Sample Properties File

There is a Sample.properties provided, which should be copied from:

<DSAME_root>/SUNWam/samples/authentication/providers

to

<DSAME_root>/SUNWam/web-apps/services/WEB-INF/config/auth/default

where /opt is the directory in which it is installed by default.

Code Example 2-4    AuthenticationSample.properties File
SCREEN
TEXT This is a sample login page
TOKEN First Name
TOKEN Last Name

SCREEN
TIMEOUT 30
TEXT You made it to page 2
PASSWORD Just enter any password

SCREEN
TIMEOUT 60
TEXT You made it past the first page
TOKEN Enter <REPLACE>'s favorite beer
PASSWORD Enter <REPLACE>'s favorite wine

SCREEN
TEXT 4th page
PASSWORD who cares
TOKEN anything here


Sample Authentication Module Source

The following samples are located in files named AuthenticationSample.java and AuthenticationModuleFactory.java which are located in:

<DSAME_root>/SUNWam/samples/authentication/providers

Code Example 2-5    Sample Java Module—AuthenticationSample.java  
/*
* "$Id: AuthenticationSample.java,v 1.1 2001/08/21 02:16:21 uchil Exp $"
* Copyright $Date: 2001/12/11 01:01:17 $ Sun Microsystems, Inc. All Rights Reserved.
*
* Some preexisting portions Copyright C 2000 Netscape Communications
* Corporation. All rights reserved.
*
* Sun, Sun Microsystems, and the Sun logo are trademarks or registered
* trademarks of Sun Microsystems, Inc. in the United States and other
* countries. Netscape and the Netscape N logo are registered trademarks of
* Netscape Communications Corporation in the U.S. and other countries. Other
* Netscape logos, product names, and service names are also trademarks of
* Netscape Communications Corporation, which may be registered in other
* countries.
*
* Federal Acquisitions: Commercial Software--Government Users Subject to
* Standard License Terms and Conditions
*
* The product described in this document is distributed under licenses
* restricting its use, copying, distribution, and decompilation. No part of
* the product or this document may be reproduced in any form by any means
* without prior written authorization of the Sun-Netscape Alliance and its
* licensors, if any.
*
* THIS DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED
* CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY
* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT,
* ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE
* LEGALLY INVALID.
*/

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

import java.util.*;
import com.iplanet.authentication.spi.*;

public class AuthenticationSample extends AuthenticationModule {

private String userTokenId;
private String firstName;
private String lastName;

public AuthenticationSample() throws AuthenticationException{
   System.out.println("AuthenticationSample()");
}

public void init() throws AuthenticationException {
   System.out.println("AuthenticationSample initialization");
}

public void validate() throws AuthenticationException {

   int currentState = getCurrentState();

   if (currentState == 1) {
    firstName = getToken(1);
    lastName = getToken(2);
    if (firstName.equals("") || lastName.equals("")) {
      throw new AuthenticationException("names must not be empty");
    }
    return;
   }
   else if (currentState == 2) {
    String pass = getToken(1);
    System.out.println("Replace TExt first: " + firstName + " last: " + lastName);
    setReplaceText(1, firstName);
    setReplaceText(2, lastName);
    return;
   }
   else if (currentState == 3) {
    String[] tokens = getAllTokens();
    for (int i=0; i<getNumberOfTokens(); i++) {
      System.out.println("Token-> " + tokens[i]);
    }
    return;
   }
   else if (currentState == 4) {
    String[] tokens = getAllTokensForState(1);
    for (int i=0; i<getNumberOfTokensForState(1); i++) {
      System.out.println("Token-> " + tokens[i]);
    }
   }

   userTokenId = firstName;
}

public String getUserTokenId() {
   return userTokenId;
}

private static final String sccsID = "$Id: AuthenticationSample.java,v 1.1 2001/08/21 02:16:21 uchil Exp $ Sun Microsystems, Inc.";
}

Code Example 2-6    AuthenticationSampleAuthenticationModuleFactory.java
/*
* "$Id: AuthenticationSampleAuthenticationModuleFactory.java,v 1.1 2001/08/21 02:17:46 uchil Exp $"
* Copyright $Date: 2001/12/11 01:01:17 $ Sun Microsystems, Inc. All Rights Reserved.
*
* Some preexisting portions Copyright C 2000 Netscape Communications
* Corporation. All rights reserved.
*
* Sun, Sun Microsystems, and the Sun logo are trademarks or registered
* trademarks of Sun Microsystems, Inc. in the United States and other
* countries. Netscape and the Netscape N logo are registered trademarks of
* Netscape Communications Corporation in the U.S. and other countries. Other
* Netscape logos, product names, and service names are also trademarks of
* Netscape Communications Corporation, which may be registered in other
* countries.
*

* Federal Acquisitions: Commercial Software--Government Users Subject to
* Standard License Terms and Conditions
*
* The product described in this document is distributed under licenses
* restricting its use, copying, distribution, and decompilation. No part of
* the product or this document may be reproduced in any form by any means
* without prior written authorization of the Sun-Netscape Alliance and its
* licensors, if any.
*
* THIS DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED
* CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY
* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT,
* ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE
* LEGALLY INVALID.
*/

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

import com.iplanet.authentication.spi.*;

/*
* Defines the Authentication Sample module factory
*/
public class AuthenticationSampleAuthenticationModuleFactory
implements AuthenticationModuleFactory
{
/*
* Returns an Authentication Sample module instance
*/
public AuthenticationModule newAuthenticationModule()
throws AuthenticationException
{
return (AuthenticationModule) new AuthenticationSample();
}
}


Sample XML Files

When creating a new service XML file, you can copy an existing authentication service XML file, and alter it as needed for your new customized authentication service. For information on writing a new service, see Chapter 5 "Understanding DSAME XMLs and DTDs.

When creating a new service, you must modify the amAuth.xml file (Core authentication) as described in Section "amAuth.xml is Used for General Authentication Configuration" on page 42.


Resource Bundle .properties File

Every service in DSAME has a corresponding resource bundle .properties file (for an example, see Code Example 2-7).


Note The resource bundle .properties file is different from the screen .properties file. Typically, each service in DSAME, whether internal or external, must have a resource bundle .properties file, and a screen .properties file.


Each service in DSAME (for example, the LDAP authentication service—described in dpAuthLDAP.xml) knows the name of its properties file. The properties in each service's resource bundle properties file are retrieved using the ResourceBundle class. Note that every service's resource bundle .properties file contains keys (such as "a1", "a2", etc.) which map to the actual fields as they will display on each service's page in Admin Console. These index, or localization, keys are described in each service's XML file (for example, amAuthLDAP.xml, etc.)

For example, for LDAP Authentication, all of these localization keys, or index keys, are defined in the amAuthLDAP.xml file, and similarly for each internal DSAME service (logging, session, authentication, etc.) and each external new service that a customization engineer might add to DSAME.

Code Example 2-7    amAuthLDAP.properties File
LDAPex=Unknown LDAP Exception
UPerror=Both UserId and Password Required
classpathError=Cannot find the Class, check classpath
InvalidUP=Invalid userId and password, please try again.
NoUser=Cannot find userId
NoServer=cannot contact server
Naming=naming error
iplanet-am-auth-ldap-service-description=LDAP
PasswordExp=Password Expires In
PasswdMismatch=New Passwords don't match Reenter
UPsame=username and password are same
PInvalid=Cureent Password Entered Is Invalid
PasswdSame=Password should not be same
PasswdMinChars=Password should be atleast 8 characters
a1=LDAP Server and Port
a2=DN to Start User Search
a3=DN for Root User bind
a4=Password for Root User Bind
a5=Search Filter
a6=User Entry Naming Attribute
a7=Search Scope
a8=Enable SSL to LDAP Server
a9=Authentication Level


Previous     Contents     DocHome     Next     
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated December 05, 2001