LoginModule Bridge Profile (JASPIC) in glassfish
By Sudarsan Sridhar on Jan 28, 2010
The LoginModule Bridge Profile is a provision in the JSR-196 (JASPIC) spec, by which a server-side message layer authentication module (ServerAuthModule) may delegate some security processing to JAAS LoginModules.
An implementation of this profile requires three types of classes.
- A ServerAuthModule validates client requests and secures responses to the client. This class is called by the container. To know more about how to write and configure a custom SAM for the Glassfish servlet container, click here.
- One or more LoginModule(s) provide pluggable authentication. The LoginModule(s) are plugged into the LoginContext for any application by using the javax.security.auth.login.Configuration system. In Glassfish, the configuration is present in the file, <domain-dir>/config/login.conf. To know more about the syntax of this file, click here.
- A CallbackHandler provides a protocol-specific method of obtaining user credentials. The ServerAuthModule instantiates a CallbackHandler and passes it to the LoginContext. This CallbackHandler is then used by the LoginModule(s) to obtain the user credentials for authentication.
Communication with the container
In order to validate client requests and secure the responses to the client, the ServerAuthModule needs to communicate with the container.
- The container calls the service methods, validateRequest, secureResponse, cleanSubject on the ServerAuthModule to request message security processing.
- The container calls the lifecycle method, initialize on the ServerAuthModule to pass configuration options and request/ response policies. Besides this, the container passes a CallbackHandler which must be used by the ServerAuthModule to create the caller and group principals as required by the container. This is done by employing the CallerPrincipalCallback and GroupPrincipalCallback, respectively.
- The container passes a clientSubject in the call to the validateRequest method, which must be updated by the ServerAuthModule when the authentication succeeds.
Duties of the ServerAuthModule
The ServerAuthModule must follow some guidelines while initializing the LoginContext and updating the subject.
- The ServerAuthModule must check the options passed during initialize for a String with key "javax.security.auth.login.LoginContext". If this String is non-null, the LoginContext must be instantiated by this name. Otherwise, the ServerAuthModule must use its own fully qualified class name to instantiate the LoginContext.
- Once the LoginContext is created, LoginContext#login may be invoked from within validateRequest in order to delegate security processing to the LoginModule(s) configured in the LoginContext.
- Once the authentication succeeds, the ServerAuthModule must transfer the Principals from the LoginContext Subject to the clientSubject. If the ServerAuthModule implements a profile requiring use of CallerPrincipalCallback and GroupPrincipalCallback, then it must use the container provided callback handler by passing the name value of the caller and group principals in the subject. This ensures that the principal implementations are consistent with the ones used by the container.
- During cleanSubject method, the ServerAuthModule must clear the client Subject of the principals and call LoginContext#logout.
- Any LoginException must be thrown as a corresponding AuthException from the ServerAuthModule.
You can check out the sample netbeans project and corresponding login.conf file for testing this profile. For using this project, you must include the javax.security.auth.message and javax.servlet api jars from your glassfish installation into the project. For v3, you need to include these jars from the modules directory. For v2, you need to include javaee.jar & jmac-api.jar from the lib directory.
You can learn more about JSR-196 (JASPIC), JAAS and SAMs in the following documents:
- JSR-196, Java Authentication Service Provider Interface for Containers.
- Pluggable Authentication in the Glassfish Web Tier.
- JAAS Authentication Tutorial.
- Adding Authentication Mechanisms to the Glassfish Servlet Container.
- OPENID - JSR-196 WITH OPENID4JAVA">Glassfish & OpenID - JSR-196 with openid4java