LoginModule Bridge Profile (JASPIC) in glassfish

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.

 Implementation Classes

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.
  • 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.

Further Reading

You can learn more about JSR-196 (JASPIC), JAAS and SAMs in the following documents:


Hi Thx For your Post mate... But i could not have understood one point yet... Do we still need to implement a custom realm for this?

Posted by Ilker GURCAN on February 16, 2010 at 07:04 AM IST #

No. If a custom ServerAuthModule is found, it is called and no realms are used.

Posted by Sudarsan Sridhar on February 16, 2010 at 07:11 AM IST #

Thx for your reply mate...What about if i would like to authenticate users with form authentication?... Getting form's fields' values from the request which is embedded in messageInfo is right and a secure way? And one more question about cleanSubject method...How can i invoke this method when a user clicks on a log-out button?

Posted by Ilker GURCAN on February 16, 2010 at 08:28 AM IST #

The Glassfish Security FAQ contains a comparision of Realms and SAMs which you may find helpful. please check out:

A SAM that implements FBL \*might\* would have logic like the following:

if (requestIsResponseToLoginForm) {
valid = validateUsernamePassword
if (valid) {
return SUCCESS
} else {
} else if (requestIsAuthenticated) {
return SUCCESS
} else if (PolicyIsMandatory) {
return SUCCESS

The SAM could validate the username and password obtained from the login form by using its CallbackHandler to handle a PasswordvalidationCallback. In Glassfish, the CallbackHandler, will handle the Callback by invoking the underlying realm.

Posted by Ron Monzillo on February 17, 2010 at 03:08 AM IST #

Very Thx Mr. Monzillo and Sudarsan for your advices. i had followed all of them whole night and after that i achieved my goal at last...Still there is a little problem but i am trying to solve it which is authorization header info in request is always null when i try to use my own DBLogin Module with my own SAM on Mr. Sudarsan's Sample Web Application in this article...but when i use Mr. Sudarsan's Sample Web Application with my own SAM and his LoginModule, authorization header info is not null strangely...I am using tagishauth.jar from Andy Armstrong as LoginModule and trying to be authenticated by BASIC authentication method(which is declared in Mr. Sudarsan's Sample)...
Thx once more to both of you...

Posted by Ilker GURCAN on February 17, 2010 at 05:41 AM IST #

Mr. Monzillo i solved all the problem except one...When i try to use form authentication it always returns response with http 404 error... runtime can't find /j_security_check URL after my sam authenticates the user with my login module...i did authentication as you had adviced me...i get the j_username and j_password from the form's fields and authenticate the user...everything is going well until my validateRequest method returns AuthState.SUCCESS...When it returns, runtime responds me with an http 404 error... In your opinion What might i do wrong?

Posted by Ilker GURCAN on February 18, 2010 at 12:17 PM IST #

Sorry for the post i have found out the problem... According to servlet spec the life of the request is only within service method of servlet...The problem occurs because of this object's lifecycle...i had read the whole servlet spec and found out the mistake...I am sure,This SAM implementation will spread out the whole software world quickly:) So Thx to all people who involved in developing this powerful artifact...

Posted by Ilker GURCAN on February 19, 2010 at 12:12 PM IST #

thank you for this (rare) article on JSR-196, it helped me a lot.

I noticed while reading JSR-196 specification that "A new LoginContext instance should be created for each new request, and a LoginContext instance should not be shared across different requests." [§6.2, page 53]

In your sample project, the LoginContext is created in the initialize method, so does it comply with the Bridge Profile contract ? Is it called for every request ?


Posted by Marian on March 29, 2010 at 11:43 AM IST #

Many thanks for a nice coverage of the topic. You've explained everything very well and besides the articles you advised to read were of great help. As for me, I always looked for some materials at http://www.sharedshares.com SE but now I see that what I have to do is only to visit your website from time to time. Thanks!

Posted by Sandok on November 02, 2010 at 05:42 PM IST #

Post a Comment:
  • HTML Syntax: NOT allowed

This blog shares my learnings through experimentation and overcoming obstacles during a day's work.


« July 2014