What is a built-in authenticator?

Although the HTTP Authentication protocol defines some authentication mechanisms, it does not define SPNEGO as one of them.

However, since JBoss uses the tomcat/catalina engine under the hood, and since the engine has support for the HTTP Authentication protocol, JBoss is able to perform BASIC, FORM, DIGEST, etc. authentication (built-in) out of the box as well as append other authentication mechanisms to the engine like SPNEGO.

This guide is very similar to the Tomcat SPNEGO Authenticator Valve example except that this guide is specific to JBoss configuration files and locations.

The purpose of this guide is to simply illustrate that it is possible to "slip-in" any authentication (AuthN) mechanism and still retain the authorization (AuthZ) mechanisms that JBoss provides out of the box.

Essentially, the engine allows for an AuthN/AuthZ mechanism that is both loosely-coupled and highly-cohesive.

This guide provides source code as well as step-by-step instructions on how to configure JBoss to silently authenticate users via a built-in authenticator that uses Kerberos/SPNEGO as the authentication mechanism.

Summary

By default, JBoss supports such authentication mechanisms as BASIC, FORM, DIGEST, etc. Unfortunately, JBoss does not currently support Kerberos/SPNEGO as an out-of-the-box authentication mechanism.

But fortunately, JBoss does allow you to implement and specify your own authentication mechanism via the tomcat/catalina engine and the war-deployers-jboss-beans.xml file.

JBoss also provides a framework for mapping users to roles. By default, this mapping definition is specified in JBoss' jbossws-users.properties/jbossws-roles.properties files.

This guide does not detail how to use LDAP, JDBC, etc. as the source mapping definition instead of using the JBoss provided properties file (but the implementation is just as simple).

Goals of this guide:

  • Compile the ExampleSpnegoAuthenticatorValve.java source code
  • Add SPNEGO to JBoss' war-deployers-jboss-beans.xml file
  • Modify JBoss' user/role mapping file
  • Modify the web.xml file
  • Create the jboss-web.xml file
  • Run the example and see it in action!

    Before Getting Started

    If you do not already have a working jboss server that authenticates requests via Kerberos/SPNEGO, take a look at the installing JBoss example. After install, ensure that authentication is working by running the hello_spnego.jsp example. It is imperative that you get this working first since we will be using the values you provided in the web.xml file, the creation of the krb5.conf file and changes to the login-config.xml file.

    This guide requires that you are able to get the HTTP Servlet Filter working first.

    Once you have confirmed that all is working as expected (via the HTTP Servlet Filter method), be sure to remove/comment-out the HTTP Servlet Filter definition and filter mapping from the web.xml file.

    Obviously authentication will now fail but now we are ready to get it working again via the tomcat/catalina engine.

    Compiling ExampleSpnegoAuthenticatorValve.java

    Download the latest spnego.jar file (spnego-r7.jar or greater) and place it under the C:\spnego-examples directory named as spnego.jar.

    Download the ExampleSpnegoAuthenticatorValve.java code and place it under the C:\spnego-examples directory.

    Before compiling ExampleSpnegoAuthenticatorValve.java, be sure to change the hard-coded property values in the file. These values should be the same values which was used in your old web.xml file (your old web.xml file had the filter definition and mapping defined and your new web.xml does not or is commented-out).

    You will also need to add C:\spnego-examples\spnego.jar, JBOSS_HOME/common/lib/servlet-api.jar , and JBOSS_HOME/server/default/deploy/jbossweb.sar/jbossweb.jar to your classpath before compilation.

    Note that JBoss 4.2 has the servlet-api.jar under JBOSS_HOME/server/default/lib and the jbossweb.jar is under the JBOSS_HOME/server/default/deploy/jboss-web.deployer directory.

    After compilation, you need to JAR the resulting .class file and place it under the JBOSS_HOME/server/default/lib directory (you can name this jar file any name you want).

    Modifying the war-deployers-jboss-beans.xml file

    Open the JBOSS_HOME/server/default/deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml file in a text (xml) editor and look for the section that contains the element <property name="authenticators"> in the file.

    Note that in JBoss 4.2 the file is named jboss-service.xml and is located under the JBOSS_HOME/server/default/deploy/jboss-web.deployer/META-INF directory.

    Once you have found the list of authenticators in the file, add the following to the list:

    <entry>
        <key>SPNEGO</key>
        <value>ExampleSpnegoAuthenticatorValve</value>
    </entry>
    

    Note that for JBoss 4.2, the xml is slightly different:

    <java:property>
        <java:key>SPNEGO</java:key>
        <java:value>ExampleSpnegoAuthenticatorValve</java:value>
    </java:property>
    

    Modifying the jbossws-users/roles.properties files

    By default, JBoss stores the username/role(s) mapping in the jbossws-users.properties/jbossws-roles.properties files. Consult the JBoss docs if you prefer to use LDAP, JDBC, etc. instead of using these properties files.

    These files are stored under the JBOSS_HOME/server/default/conf/props directory.

    This guide will use the properties files for the username/role(s) mapping definition.

    Open the jbossws-users.properties file in a text editor and replace it's contents with the following:

    # A sample users.properties file for use with the UsersRolesLoginModule
    kermit=thefrog
    DFelix@ATHENA.LOCAL=
    

    Notice that kermit is the username and thefrog is the password. Also notice there is no password defined for DFelix@ATHENA.LOCAL since we will be using SPNEGO.

    Open the jbossws-roles.properties file in a text editor and replace it's contents with the following:

    # A sample roles.properties file for use with the UsersRolesLoginModule
    kermit=friend,role1
    DFelix@ATHENA.LOCAL=role1
    

    Also, notice that kermit has multiple roles defined.

    Modifying the web.xml file

    Add the following to the web.xml file:

    <security-constraint>
        <web-resource-collection>
             <web-resource-name>All JSP Files</web-resource-name>
             <url-pattern>*.jsp</url-pattern>
        </web-resource-collection>
        <auth-constraint>
             <role-name>role1</role-name>
        </auth-constraint>
    </security-constraint>	
    
    <login-config>
        <auth-method>SPNEGO</auth-method>
    </login-config>
    
    <security-role>
        <role-name>role1</role-name>
    </security-role>
    

    Notice that we no longer need to define the SPNEGO HTTP Servlet Filter in the web.xml file.

    Creating the jboss-web.xml file

    Create the jboss-web.xml file under the JBOSS_HOME/server/default/deploy/ROOT.war/WEB-INF directory with the following contents:

    <!DOCTYPE jboss-web PUBLIC
       "-//JBoss//DTD Web Application 5.0//EN"
       "http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd">
       
    <jboss-web>
       <security-domain>java:/jaas/JBossWS</security-domain>
    </jboss-web>
    

    Note that the JBossWS value in the security-domain element corresponds to an entry in the JBOSS_HOME/server/default/conf/login-config.xml file.

    Running/Testing ExampleSpnegoAuthenticatorValve.java

    Open a browser and go to http://medusa:8080/hello_spnego.jsp

    If all is working correctly you should see the following (without being prompted):

    Troubleshooting ExampleSpnegoAuthenticatorValve.java

    The first step to troubleshooting is to first know with absolute certainty that authentication was working when it was configured as an HTTP Servlet Filter.

    TBD

    Links:
    pre-flight checklist
    install guide - tomcat
    install guide - jboss
    install guide - glassfish
    reference docs
    api docs
    download

    Troubleshooting:
    HelloKDC.java
    hello_spnego.jsp
    HelloKeytab.java
    hello_delegate.jsp
    SpnegoHelloClient.java
    ExampleSpnegoAuthenticatorValve.java

    Examples:
    create keytab for client
    create keytab for app server
    credential delegation
    protected SOAP Web Service
    tomcat authenticator valve
    jboss authenticator valve

    Licensing:
    GNU LGPL


    © 2009 Darwin V. Felix. All rights reserved.