How the Authentication SPIs Work

• Extending the AMLoginModule Class

• Pluggable JAAS Module

• Authentication Post Processing

Access Manager provides the capability to plug new, Java-based authentication modules into its framework allowing proprietary authentication providers to be managed using the Access Manager console. A custom authentication module must first be created using Java. Once created, the custom module can be added to the list of available authentication modules.

This guide does not document the JAAS. For more information on these APIs, see the Java Authentication And Authorization Service Developer’s Guide. Additional information can be found at http://java.sun.com/products/jaas/.

Extending the AMLoginModule Class

Custom authentication modules extend the com.sun.identity.authentication.spi.AMLoginModule class. The class must also implement the init(), process() and getPrincipal() methods in order to communicate with the authentication module configuration files. The callbacks are then dynamically generated based on this file. Other methods that can be defined include setLoginFailureURL and setLoginSuccessURL which defines URLs to send the user to 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.

Pluggable JAAS Module

The Java Authentication and Authorization Service (JAAS) is a set of APIs that enable services to authenticate and enforce access controls upon users. It implements a Java technology version of the standard Pluggable Authentication Module (PAM) framework, and supports user-based authorization. Access Manager supports pure JAAS pluggable authentication modules. In Access Manager, pure JAAS modules extend the JAAS LoginModule rather than AMLoginModule. A pure JAAS module is plugged in to the Authentication framework using the Authentication API.

Authentication Post Processing

The Authentication SPI includes the AMPostAuthProcessInterface which can be implemented for post-processing tasks. The following are examples of post-processing tasks:

• Adding attributes to a user’s session after successful authentication

• Sending notification to an administrator after failed authentication

• General clean-up such as clearing cookies after logout or logging out of other system components.

The Core Authentication Service contains the Authentication PostProcessing Class attribute which contains the authentication post-processing class name as its value. Custom post processing interfaces can also be implemented.

AMPostAuthProcessInterface can be implemented for post authentication processing on authentication success, failure and logout. The SPI is configurable at the organization , service and role levels. The Authentication Service invokes the post processing SPI methods on successful, failed authentication and logout.

The AMPostProcessInterface class has 3 methods:

• onLoginSuccess

• onLoginFailure

• onLogout

Some supporting information on these methods is provided in the following sections. For a comprehensive listing and detailed information on all Access Manager methods, see the Javadoc installed in the following directory:

AccessManager-base/SUNWam/docs

onLoginSuccess

This method should be implemented for post-processing after a successful authentication. Authentication Service will invoke this method on successful authentication.

Method signature is:

 public void onLoginSuccess(Map requestParamsMap,
                               HttpServletRequest request,
                               HttpServletResponse response,
                               SSOToken ssoToken)
     throws AuthenticationException;

where

• requestParamaMap is a map containing HttpServletRequest parameters

• request HttpServletRequest object

• response HttpServletResponse object

  com.sun.identity.authentication.spi.AuthenticationException is thrown on error.

onLoginFailure

This method should be implemented for post processing after a failed authentication. Authentication Service will invoke this method on failed authentication.

Method signature is:

 public void onLoginFailure(Map requestParamsMap,
                             HttpServletRequest request,
                             HttpServletResponse response)
    throws AuthenticationException;

where

• requestMap is a map containing HttpServletRequest parameters

• request HttpServletRequest object

• response HttpServletRequest object

  com.sun.identity.authentication.spi.AuthenticationException is thrown on error.

onLogout

This method should be implemented for post-processing on a logout request. Authentication Service will invoke this method on logout.

Method signature is:

 public void onLogout(HttpServletRequest request,
                       HttpServletResponse response,
                      SSOToken ssoToken)
    throws AuthenticationException;

where

• request HttpServletRequest object is a map containing HttpServletRequest parameters

• response HttpServletResponse object

• ssoToken authenticated user’s single sign on token

  com.sun.identity.authentication.spi AuthenticationException is thrown on error.