Pluggable Authentication in the Glassfish Web Tier

JSR 196 defines a generic SPI that extends the concepts of JAAS to the authentication of network messages. The spec defines profiles that establish contracts for the use of the SPI in specific contexts. The first profile defined in the spec is called the Servlet Container profile. This profile defines what a compatible Servlet container must do in order for it to support integration of portable JSR 196 compatible server authentication modules (i.e., SAMS). The profile also establishes the requirements that must be satisfied by a SAM for it to be pluggable in a compatible Servlet container. The spec and its associated javadocs may be found at JSR 196

Glassfish is a compatible implementation of the Servlet Container Profile and you can see a sample SAM (for use in any compatible Servlet container) at SPNEGO SAM. It is relatively easy to implememt a SAM, and I will be making more samples available (e.g., an OpenID SAM) for people to learn from and try out. Also the SPI is planned for inclusion in EE 6.0.

The SPI and the Servlet Container Profile:

  • the SPI defines a subject based contract that allows the SAM to, return more than just a single principal and to do so without reliance on proprietary apis.
  • The SPI also defines callbacks that are made available to the SAM, so that the SAM can enlist services of the container including for the purpose of distinguishing the "user" principal among those in the returned subject, to establish group principals in a form understood by the container authorization system, to validate a username and password at the realm bound to the application, or to gain access to the keystores of the container.
  • The profile makes it possible for the SAM to manage sessions, by ensuring that the SAM is called independent of whether an authentication session has already been established, and with sufficient context so that the SAM can force authentication for requests to resources which are covered by a Servlet auth-contraint.
The steps for integrating a new auth mechanism in the Glassfish Servlet container are as follows:
  • write a ServerAuthModule (i.e., a SAM) which mostly boils down to implementing the following method:
    AuthStatus validateRequest(MessageInfo messageInfo, 
                               Subject clientSubject, 
    		           Subject serviceSubject) throws AuthException;
    The Servlet Container Profile defines what will be passed to the SAM via messageInfo (i.e., the HttpServletRequest, HttpServletResponse, and a Map of property values).
  • package your SAM in a jar, and place your jar in the glassfish lib directory.
  • configure the SAM for use with your application. This may be done in 2 steps:
    • Define your SAM as a message-security-provider in domain.xml (see the example in To create an JSR196 httpservlet provider).
    • Bind the SAM for use with your application. You can do this by defining the httpservlet-security-provider attribute in the sun-web-app.xml corresponding to your app. The value of the attribute would be set to name you assigned to your SAM step 1.
that should do it.


ps: I described how you can use one of the config systems that is bundled with Glassfish to configure a SAM for use with your application. You can also use JSR 196 to replace the config system and thereby change the way the SAM would be configured...More on that later.


What is the life-cycle of a ServerAuthModule that is used in servlet mode in GlassFish.

For example, of the options below when will GlassFish create a new instance of the ServerAuthModule class

1) At server start-up
2) At deployment of a WAR that references the SAM in the sun-web.xml deployment descriptor
3) When a new session for a user starts
4) On every request

The reason that I am asking is that I'd like to add some performance optimizations to the SAM like the following:
1) A cache of user/group lookups so I don't have to hit the database to load groups. The cache entries would self-expire after a reasonable amount of time.
2) An internal JDBC connection pool (Or can I just lookup and use a pool on the server?)

If the life-cycle is #4, then my optimizations are going to be harder.

Posted by Dave on March 26, 2008 at 04:11 AM EDT #

When you said "sun-web-app.xml", did you mean to say "sun-web.xml"?

Could you provide a sample of what an httpservlet-security-provider attribute should look like?

I can't seem to find an example anywhere and I keep getting:

"DPL8007: Invalid Deployment Descriptors element httpservlet-security-provider value MySAM"

Posted by Brian on April 14, 2008 at 04:45 AM EDT #

When a request is processed, is the ServerAuthModule executed before or after the potential SSL information is injected in the HttpServletRequest ?

I would like to get the client certificate to use it's DN as a principal name and do checks about the certificate issuer.

I've tried to get the HttpServletRequest attribute but it's always null.

Thanks in advance


Posted by Paul Merlin on September 11, 2008 at 08:09 PM EDT #

The 196 spec identifies the point at which the SAM is invoked as being after the connection requirements (i.e., transport guarantees) are satisfied and before the runtime enforces the auth-constraints that would trigger an authentication. As such, ssl client auth may not have occurred at the time the SAM is invoked. In Glassfish, you can instigate SSL client auth from your SAM (if an SSL transport has already been established as a result of the enforcement of a transport guarantee) by requesting the proprietary attribute "org.apache.coyote.request.X509Certificate". For this to work in Glassfish, I think your app's web.xml will need to define a login-config with an auth-method of CLIENT-CERT). I'll look into whether the servlet EG would be willing to standardize an api/attribute that can be used to instigate ssl client auth.

Posted by Ronald Monzillo on November 06, 2008 at 07:02 AM EST #

Hi. We have a custom Jaspi SAM for a propietary SSO system running on Glassfish v2. The httpservlet version works fine, but the server don't call the soap version. I think its a configuration error.

We have configured the soap provider in the server (domain.xml):

<message-security-config auth-layer="SOAP">
<!-- turned off by default -->
<provider-config class-name="gn.jcar.jaspi.SoapCarSam" provider-id="SoapCarSam" provider-type="server">
<request-policy auth-source="sender"/>
<response-policy auth-source="content"/>

And this is the end point configuration in the application (sun-web.xml):

<message-security-binding auth-layer="SOAP" provider-id="SoapCarSam">
<request-protection auth-source="sender"/>
<response-protection auth-source="content"/>

Thank you.

Posted by Fernando on November 25, 2008 at 12:33 AM EST #

It looks like you want your message-security-binding to apply to all methods/operartions of the endpoint. If that is the case, please try replacing the message element with an empty message element (i.e., <message/>). Let me know what happens.

Posted by Ronald Monzillo on November 25, 2008 at 05:20 AM EST #

The SPNEGO project home page is now hosted (directly) at:
I changed the link in the blog entry.

Posted by Ronald Monzillo on June 15, 2009 at 04:41 AM EDT #

Post a Comment:
  • HTML Syntax: NOT allowed



« June 2016