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

• Implementing the process() Method

• Implementing the getPrincipal() Method

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 javax.security.auth.callback.CallbackHandler 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:

• Perform the authentication and if successful, save the authenticated principal.

• Return -1 if authentication succeeds.

• Throw an exception, such as AuthLoginException, if authentication fails or return the relevant state specified in the module's configuration properties file

• Throw an exception, such as InvalidPasswordException, if using the Login Failure Lockout feature

• If multiple states are available to the user, the Callback array from a previous state may be retrieved by using the getCallback() method. The underlying login module keeps callback information from previous states until the login process is completed.

• If a module needs to substitute dynamic text (generate challenges, passwords or user identifiers) in the next state, use the getCallback() method to retrieve the callback for the next state, modify the text, and call replaceCallback() to update the array.

• Each authentication session will create a new instance of your module's Java class. The reference to the class will be released once the authentication session has either succeeded or failed.

• Any static data or reference to any static data in your module must be thread-safe.

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.