Sun Java System Access Manager 7 2005Q4 Developer's Guide

Writing a Sample Login Module

Use the AMLoginModule SPI to write your own sample login module.

ProcedureTo Write a Sample Login Module

  1. Creating a Module Properties File.

  2. Writing the Principal Class.

  3. Implementing the LoginModule Interface.

    The following are the default directories used in the sample exercise for the various platforms:

    Solaris Sparc/x86: <PRODUCT_DIR> = base-directory/SUNWam

    Linux: <PRODUCT_DIR> = base-directory/sun/identity

    W2K: <PRODUCT_DIR> = base-directory

Creating a Module Properties File

Create a Module properties XML file with the same name of the class (no package name) and use the extension .xml. You must create an XML file with this naming convention even if no states required

Based on this configuration file, the Authentication user interface will dynamically generate a login page.

You can define page states in the module properties file as shown in Creating a Module Properties File. Each callback element corresponds to one login page state. When an authentication process is invoked, Callback[] values will be generated from the user’s Login Module for each state. All login state definitions start with 1. The module controls the login process, and then determines what the next state is.

Auth_Module_Properties.dtd defines the data structure that will be used by each authentication module to specify its properties. Auth_Module_Properties.dtd provides definitions to initiate, construct and send required callbacks information to the Authentication graphical user interface. Auth_Module_Properties.dtd is stored in the <PRODUCT_DIR>/dtd directory.

Example 5–7 Module Configuration Sample

<ModuleProperties moduleName="LoginModuleSample" version="1.0" >
         <Callbacks length="2" order="1" timeout="60" 
							header="This is a sample login page">
             <Prompt> User Name </Prompt>
             <Prompt> Last Name </Prompt>
         <Callbacks length="1" order="2" timeout="60" 
							header="You made it to page 2" >
             <PasswordCallback echoPassword="false" >
             <Prompt> Just enter any password </Prompt>
Module Configuration Sample

In this module configuration sample, page state one has two callbacks. The first callback is for user ID, and second is for Last Name. When the user fills in the callbacks, the following events occur:

Writing the Principal Class

After creating module configuration XML file, the next step is to write a Sample Principal class which implements The constructor takes the user’s username as an argument. If authentication is successful, the module will return this principal to Authentication framework. The Authentication framework populates a Subject with a SamplePrincipal representing the user.

Implementing the LoginModule Interface

AMLoginModule is an abstract class which implements JAAS LoginModule. AMLoginModule provides methods for accessing Access Manager services and the module XML configuration. Login Module writers must subclass AMLoginModule class and implement the following methods:

For detailed descriptions, syntax, and parameters, see the Sun Java System Access Manager 7 2005Q4 Java API Reference. The following sections provide some supporting information about these methods.

init() This is an abstract method, Module writer should implement to initialize this LoginModule with the relevant information. If this LoginModule does not understand any of the data stored in sharedState or options parameters, the data can be ignored. This method is called by a AMLoginModule after thisSampleLoginModule has been instantiated, and prior to any calls to its other public methods. The method implementation should store away the provided arguments for future use. The init method may additionally peruse the provided sharedState to determine what additional authentication state it was provided by other LoginModules, and may also traverse through the provided options to determine what configuration options were specified to affect the LoginModule’s behavior. It may save option values in variables for future use.

process() The process method is called to authenticate a Subject. This method implementation should perform the actual authentication. For example, it may cause prompting for a user name and password, and then attempt to verify the password against a password database. If your LoginModule requires some form of user interaction (retrieving a user name and password, for example), it should not do so directly. That is because there are various ways of communicating with a user, and it is desirable for LoginModules to remain independent of the different types of user interaction. Rather, the LoginModule’s process method should invoke the handle method of the CallbackHandler passed to this method to perform the user interaction and set appropriate results, such as the user name and password and the AMLoginModule internally passes the GUI an array of appropriate Callbacks, for example a NameCallback for the user name and a PasswordCallback for the password, and the GUI performs the requested user interaction and sets appropriate values in the Callbacks.

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

getPrincipal() This method should be called once at the end of a successful authentication session. A login session is deemed successful when all pages in the Module properties XML 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 Access Manager environment.

Note –

If the custom authentication module requires or already uses a service configuration XML file: