Sun OpenSSO Enterprise 8.0 Developer's Guide

Writing Authentication Modules with the Authentication Service SPI

OpenSSO Enterprise provides the com.sun.identity.authentication.spi package to write Java-based authentication modules and plug them into the Authentication Service framework, allowing proprietary authentication providers to be managed using the OpenSSO Enterprise console. The authentication module is created using the abstract com.sun.identity.authentication.spi.AMLoginModule class which implements the JAAS LoginModule class.

The com.sun.identity.authentication.spi.AMLoginModule interface provides methods to access the Authentication Service and the authentication module's callback requirements file. This class takes advantage of many built-in features of OpenSSO Enterprise and scales well. Once created, a custom authentication module can be added to the list of authentication modules displayed by the OpenSSO Enterprise console. Use the following list of procedures as a checklist to complete the task.

  1. Create a callback requirements file for the new authentication module.

    See Creating an Authentication Module Callback Requirement File.

  2. Implement a Principal class.

    See Writing a Principal Class for the Authentication Module.

  3. Create a service file for the new authentication module.

    See Creating an Authentication Module Service File.

  4. (OPTIONAL) Create a localization properties file for the new authentication module.

    See Creating an Authentication Module Localization Properties File.

  5. Develop the custom authentication module.

    See Extending the AMLoginModule Class

  6. (OPTIONAL) Add post processing features.

    See Adding Authentication Post Processing Features.

  7. Access http://osso-host.osso-domain:osso-port/opensso/ssoadm.jsp from a browser and choose create-svc to create the service in OpenSSO Enterprise.

    You will need to copy the authentication module's service file to the text box. For more information regarding the ssoadm options, see the Sun OpenSSO Enterprise 8.0 Administration Reference.

  8. Choose the register-auth-module option (also on ssoadm.jsp) to register the custom authentication module with the Core Authentication framework.

    Enter the complete module name including the prepended package. For more information regarding the ssoadm options, see the Sun OpenSSO Enterprise 8.0 Administration Reference.

  9. Restart OpenSSO Enterprise.

    The custom authentication module is now listed under the Configuration tab as an Authentication option.

Note –

After deploying the opensso.war, you can also point a browser to http://openSSO-host.openSSO-domain:openSSO-port/opensso/samples/authentication/AuthSampleLoginModule.html for the sample, How to Write Sample Login Module using AMLoginModule SPI (Service Provider Interface)?.

Creating an Authentication Module Callback Requirement File

The authentication module's callback requirements file is XML that defines the module's authentication requirements and login state information. The parameters in this file automatically and dynamically customize the authentication module's user interface in the form of login pages, providing the means to initiate, construct and send the credential requests to the Distributed Authentication User Interface. Auth_Module_Properties.dtd defines the data structure of the file.

When an authentication process is invoked, the values nested in the Callbacks element of the module's callback requirements file are used to generate login screens. The module controls the login process, and determines each concurring screen. LDAP.xml, the callback requirements file for the LDAP authentication module, illustrates this concept.

Example 1–2 LDAP Authentication Module Callback Requirements File

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

    <Callbacks length="2" order="1" timeout="120" 
     header="This server uses LDAP Authentication" >
            <Prompt> User Name: </Prompt>
        <PasswordCallback echoPassword="false" >
            <Prompt> Password: </Prompt>

    <Callbacks length="4" order="2" timeout="120" 
     header="Change Password&lt;BR&gt;&lt;/BR&gt;#REPLACE#&lt;BR&gt;&lt;/BR&gt;" >
        <PasswordCallback echoPassword="false" >
            <Prompt>Old Password </Prompt>
        <PasswordCallback echoPassword="false" >
            <Prompt> New Password </Prompt>
        <PasswordCallback echoPassword="false" >
            <Prompt> Confirm Password </Prompt>
                    <Value> Submit </Value>
                    <Value> Cancel </Value>

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

    <Callbacks length="0" order="4" timeout="120" template="user_inactive.jsp" 


The initial interface has two Callback elements corresponding to requests for the user identifier and password. When the user enters values, the following events occur:

Note –

Name the authentication module's callback requirements file using the same name as that of the authentication module's class (no package information) and use the extension .xml. Create the file and use this naming convention even if no states are required for the module.

The file is located in the appropriate localized directory in the OpenSSO-Deploy-base/config/auth directory. Use one of the provided files as a template for creating the file and copy it to the aforementioned directory when finished.

Writing a Principal Class for the Authentication Module

After creating the authentication module's callback requirements file, write a class which implements to represent the entity requesting authentication. For example, the constructor takes the username as an argument. If authentication is successful, the module will return this principal to the Authentication Service which populates the login state and session token with the information representing the user.

Creating an Authentication Module Service File

The authentication module's service file is written in XML and imported to OpenSSO Enterprise to allow the management of its attributes using the OpenSSO Enterprise console. The name of the service file follows the format amAuthmodulename.xml (for example, amAuthSafeWord.xml or amAuthLDAP.xml). The file is located in OpenSSO-Deploy-base/WEB-INF/classes. The new service file must conform to the sms.dtd. Use one of the provided authentication module service files as a template. Conversely, you can use the template provided.

Example 1–3 Authentication Module Service File Template

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

<!DOCTYPE ServicesConfiguration
PUBLIC "=//iPlanet//Service Management Services (SMS) 1.0 DTD//EN"

  <Service name="iPlanetAMAuthMYMODULEAuthService" version="1.0">
       <AttributeSchema name="iplanet-am-auth-mymoduleauth-primary-server"
       <AttributeSchema name="iplanet-am-auth-mymoduleauth-primary-base-dn"
       <AttributeSchema name="iplanet-am-auth-mymoduleauth-primary-search-base-dn"
       <AttributeSchema name="iplanet-am-auth-mymoduleauth-primary-bind-dn"
           <Value>cn=Directory Manager</Value>
       <AttributeSchema name="iplanet-am-auth-mymoduleauth-primary-bind-passwd"
       <AttributeSchema name="iplanet-am-auth-mymoduleauth-auth-level"
        <OrganizationConfiguration name="/">		
               <Attribute name=

Creating an Authentication Module Localization Properties File

A localization properties file specifies the screen text that an administrator will see when directed to an authentication module's service page in the OpenSSO Enterprise console as well as messages (error or otherwise) displayed by the module. Following are some concepts behind the creation of this file.

The file is located in OpenSSO-Deploy-base/WEB-INF/classes and follows the naming format; for example, Use one of the provided authentication module localization properties files as a template for creating the file and copy it to the aforementioned directory when finished.

Extending the AMLoginModule Class

Custom authentication modules extend the com.sun.identity.authentication.spi.AMLoginModule class and must implement the init(), process() and getPrincipal() methods. The module should also invoke the setAuthLevel() method. Other methods that can be implemented include setLoginFailureURL() and setLoginSuccessURL() which define URLs to which the user is sent based on a failed or successful authentication, respectively. To make use of the account locking feature with custom authentication modules, the InvalidPasswordException exception should be thrown when the password is invalid. These sections contain information on the three main methods.

Implementing the init() Method

init() is an abstract method that initializes the module with relevant information. This method is called by AMLoginModule prior to any other method calls. The method implementation should store the provided arguments for future use. It may peruse the sharedState to determine what information it was provided by other modules, and may also traverse through the options to determine the configuration parameters that will affect the module's behavior. The data can be ignored if the module being developed does not understand it.

Implementing the process() Method

process() is called to perform the actual authentication. For example, it may prompt for a user name and password, and then attempt to verify the credentials. If your module requires user interaction (for example, retrieving a user name and password), it should not do so directly. This method should invoke the handle method of the interface to retrieve and display the appropriate callbacks. The AMLoginModule then internally passes the callback values to the Distributed Authentication User Interface which performs the requested authentication.

Consider the following points while writing the process() method:

Implementing the getPrincipal() Method

getPrincipal() should be called once at the end of a successful authentication session. This method retrieves the authenticated token string which will refer to the authenticated user in the OpenSSO Enterprise environment. A login session is deemed successful when all pages in the module's configuration properties file have been sent and the module has not thrown an exception.

Adding Authentication Post Processing Features

The com.sun.identity.authentication.spi.AMPostAuthProcessInterface interface can be implemented for post processing tasks on authentication success, failure and logout using the methods onLoginSuccess(), onLoginFailure(), and onLogout(), respectively. The Authentication Post Processing Classes are defined in the Core Authentication Service and configurable at several levels such as at the realm or role levels. Post processing tasks might include: