Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Portal Server 6 2004Q2 Migration Guide 

Chapter 3
Migrating Custom Authentication Modules

Note

All instances of the Sun™ ONE Portal Server 3.0 product refer to what were formerly known as the iPlanet™ Portal Server 3.0, Service Pack 3a, iPlanet™ Portal Server 3.0, Service Pack 4 products, and iPlanet™ Portal Server 3.0, Service Pack 5 products.

Custom authentication modules from Sun ONE Portal Server 3.0 must be simulated in Sun™ ONE Identity Server as plugged-in authentication modules. All custom authentication modules must implement the Authentication Service Provider Interface (SPI) which provides the authentication framework, and should be written using com.sun.identity.authentication.spi.AMLoginModule class. In addition, to implementing theAMLoginModule SPI, there are a number of configuration files that must also be created. This chapter describes the interfaces and classes required to migrate custom authentication modules from a Sun ONE Portal Server 3.0 and the high-level steps necessary to implement them in the Sun ONE Identity Server. This chapter contains the following sections:

Implementing the Authentication Service Provider Interface (SPI)

The Sun ONE Identity Server 6.1 authentication framework provides the Authentication Service Provider Interface (SPI) to invoke specific authentication modules. The Authentication SPI implements the Java™ Authentication and Authorization Service (JAAS) LoginModule API, and provides methods to access the Authentication Service and module configuration properties. The Authentication SPI is defined in the com.sun.identity.authentication.spi package. The Authentication SPI contains the abstract class, AMLoginModule,used for writing pluggable authentication modules. To write an authentication module, you extend the AMLoginModule class. Because AMLoginModule is an abstract class, it must be subclassed with the name of the authentication module. The class must also implement the init, process, and getPrincipal abstract methods in order to communicate with the module configuration properties files.

See the Sun ONE Identity Server Javadocs for details on implementing the Authentication SPI and the AMLoginModule class. Refer to Appendix C, "Public API Changes Between Sun ONE Portal Server 3.0 and Sun ONE Portal Server 6.2" for details on mapping APIs.

Creating the AuthModule.jar File

Once the custom authentication module is written and compiled, create a .jar file for the module and put it in the BaseDir/SUNWam/web-apps/services/lib directory.

To create the AuthModule.jar file, issue the command:

jar -cvf AuthModulename.jar *.class

where the *.class file corresponds to the name of the authentication module you created that extended the com.sun.identity.authentication.spi.AMLoginModule class.

Creating the XML Service File

Each authentication service must have its own service XML file. This file specifies the user and administrator configurable attributes and allows them to be managed using the Sun ONE Identity Server administration console. The name of the XML service file typically follows the format amAuthModuleName.xml (for example, amAuthSafeWord.xml or amAuthLDAP.xml) and is located in the BaseDir/SUNWam/config/xml directory.

Creating the Authentication Module Configuration File

The authentication module configuration file specifies the authentication module credentials required by an identity (either user, service or application) in order to authenticate to the module. Typically, the settings in this file define the user authentication screens. The name of the authentication module configuration file typically follows the format ModuleName.xml (for example, SafeWord.xml or LDAP.xml) and is located in the BaseDir/SUNWam/web-apps/services/config/auth/default directory.

In Sun ONE Identity Server 5.1 implementation, this file was a .properties file (for example, LDAP.properties). In Sun ONE Identity Server 6.1 implementation, this file is now a .xml file (for example, LDAP.xml). After converting LDAP data, the conversion tool will have created an ImportDir/xml/component/iwtAuthModule_Name.xml file. The import tool does not import the iwtAuthModule_Name.xml. Because the authentication module must be rewritten to the Authentication SPI, it is recommended that you create a new ModuleName.xml file for the custom authentication module although the iwtAuthModule_Name.xml can be useful to look through as you develop the ModuleName.xml file.

Creating the Localization Properties File

The localization properties file defines the language-specific screen text for the attribute names for the module. The name of the localization properties file typically follows the format amAuthModuleName.properties (for example, amAuthSafeWord.properties or amAuthLDAP.properties) and is located in the BaseDir/SUNWam/locale directory under sub-directory appropriate to the locale (for example, en_US, or FR).

Modifying the amAuth.xml File

The amAuth.xml file defines the “parent” core authentication service. This file is located in the BaseDir/SUNWam/config/xml directory. Whenever a new authentication service is created, attributes in this file must be modified in order to recognize an authentication module.

  1. Make a backup copy of the amAuth.xml file.
  2. Add a value defining in the custom authentication module to the iplanet-am-auth-authenticators attribute list in the amAuth.xml file. The value contains a text string specifying the full class name of the module, including package. For example,

    3. <Value>com.sun.identity.authentication.modules.Modulename.MODULENAME
    </Value>

  3. Add a value defining the custom authentication module to the iplanet-am-auth-allowed-modules attribute in the amAuth.xml file. The value contains a text string specifying the name of the module to display in Admin console for the module and the name defined for the module in the iplanet-am-auth-authenticators attribute list. For example,

    4. <ChoiceValue i18nKey="Module">MODULENAME</ChoiceValue>

  4. Save the updated amAuth.xml file.
  5. Type the following command to delete the old core service file.

    6. BaseDir/SUNWam/bin/amadmin --runAsDN uid=amadmin,ou=People,default_org,root_suffix --password password --deleteService iplanetAMAuthService

  6. Type the following command to load the updated core service file.

    7. BaseDir/SUNWam/bin/amadmin --runAsDN uid=amadmin,ou=People,default_org,root_suffix --password password --schema amAuth.xml



Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.