watch this  

This HOWTO explains the steps necessary to implement authentication in JBoss using the underlying Linux OS. Using a custom JBoss LoginModule (provided), SysAuth and Linux/PAM, users on your website can use their Linux username and password to authenticate. I post snippets of code and config. files along the way and provide a single download with everything at the end. <!-more->

Initial Setup The first thing you will need is SysAuth. It is a Java interface to PAM, the underlying authenication subsystem that drives most, if not all, current Linux distributions. You will need the jar file when compiling your Java code and the shared library, libSysAuth.so, when running in JBoss.

The rest of this tutorial assumes that you have JBoss 3.2.* installed in a directory called jboss.

Configuring JBoss First, decide on a place to put the SysAuth shared library. For simplicity’s sake, I put it in jboss/bin. Next, we need to indicate where JBoss should look for the shared lib by modifying the java.library.path variable passed to the JVM. For JBoss, that is accomplished by modifying changing the JAVA_OPTS variable in jboss/bin/run.conf.

Add the following to the end of jboss/bin/run.conf:

JAVA_OPTS="-Djava.library.path=bin $JAVA_OPTS" 

Download: run.conf

Configuring PAM I have tested this setup on Gentoo and RedHat ES 3, though it should work for any Linux distribution that uses PAM. The only change needed is to add an entry to the /etc/pam.d/ directory. We’ll call the file called java_auth. Depending on your PAM configuration, you will need to use one of the following. In RedHat (and, most likely, all others), java_auth should look like so:

auth       required     pam_stack.so service=system-auth

This particular configuration “passes” authentication through to the system-level configuration. In Gentoo, I was able to get by with:

auth    required  pam_unix.so

Try the first. If it doesn’t work, try the second. If that doesn’t work: pester your Sys Admin—they love this stuff!

One more note: BEWARE OF TABS. I spent way too longing wrestling with a problem caused by a spurious tab.

Download: java_auth

Build a Custom JBoss Login Module The process of creating a custom JBoss Login Module is pretty advanced and there are many, many options. But, in the case of simple authenication against the underlying Linux operating system we can take a pretty direct approach. To implement a login module that will supply a username and password to PAM (via SysAuth) we need to subclass JBoss’s UsernamePasswordLoginModule class. The subclassing requires that we implement the following functions:

• public boolean validatePassword(String inputPassword, String expectedPassword)
• public String getUsersPassword()
• public Group[] getRoleSets()

So, put this in a file called MyLoginModule.java. Compile it with SysAuth.jar in your classpath. The class should end up in the WEB-INF/lib directory of your Web Application. Our main concern is with getUsersPassword which is where we will use SysAuth.

    public boolean validatePassword(String inputPassword, String expectedPassword)
    {
        boolean result = false;
        result = SysAuth.isAllowed(getUsername(),inputPassword);
        return result;
    }

Pretty simple, huh? As you can see, it simply passes the username and password to SysAuth. Sysauth will return true or false for authenticated or denied, respectively. The other two functions are equally exciting:

    public String getUsersPassword() throws LoginException {
        return "";
    }

and here we create an arbitrary group to which our user will belong (more on this later):

    public Group[] getRoleSets() throws LoginException {
         userRoles.addMember(new SimplePrincipal("AuthenticatedUsers"));
        Group[] roleSets = {userRoles};
        return roleSets;
    }

Download: MyLoginModule.java

While we are here, it is a good time to point out the main deficiency in this PAM-based implementation: Authorization. I have yet to find a good way to setup any advanced group- or role-based access controls. Basically, the user is either authenticated or not. This is a deficiency in PAM not JBoss or JAAS.

Configure your Web Application

Now, let’s bring it all together by configuring your web application to use the custom login module we wrote. All of these changes are standard JBoss configuration changes for using JAAS. Check jboss for more information.

First, we need to setup a JBoss security configuration. So, we will need to add the following to jboss/server/default/conf/login-config.xml. (Note: if you are using a custom server/configuration, just change “default” to the name of your server/configuration). Put the following at the bottom of login-config.xml, just before the closing < / policy >:

<application -policy name="my_security">
    <authentication>
        <login -module code="com.example.security.MyLoginModule" 
            flag="required" debug="true">
        </login>
    </authentication>
</application>

Download: login-config.xml

Set the class package to wherever you put your code.

Second, we need to tell our web application to use the built-in JBoss authentication scheme. Gee, thanks, JBoss! We get this by having a form that calls j_security_check. Again, standard stuff. I put mine in index.html

    <form id="login" action="j_security_check" method="post">
        <h1>Login</h1><br />
        <p>Username</p><input type="text" size="10" name="j_username"/>
        <p>Password</p><input type="password" size="10" name="j_password"/>
        <input type="submit" value="Login"/>
    </input></input></input></form>

Download: index.html

Note: the names of the form controls does matter. Next you need to configure your web.xml:

    <welcome -file-list>tml</welcome>

    <error -page>
        <error -code>400</error>
        <location>/index.html</location>
    </error>
    <!-- Default: Access to everything requires login -->
    <security -constraint>
        <web -resource-collection>
            <web -resource-name>My Web Application</web>
            <description>Require users to authenticate</description>
            <url -pattern>*.jsp</url>
            <http -method>POST</http>
            <http -method>GET</http>
        </web>
        <auth -constraint>
            <description>Only allow AuthenticatedUsers role</description>
            <role -name>*</role>
        </auth>
        <user -data-constraint>
            <description>Encryption is not required for the application in general. </description>
            <transport -guarantee>NONE</transport>
        </user>
    </security>
    <login -config>
        <auth -method>FORM</auth>
        <form -login-config>
            <form -login-page>/index.html</form>
            <form -error-page>/LoginError.html</form>
        </form>
    </login>
    <security -role>
        <role -name>AuthenticatedUsers</role>
    </security>
 </>

Download: web.xml

As you can see, this is pretty standard stuff. The only things to note are that I set role-name to * which basically means: any user who has been authenticated. You could change this to be “AuthenticatedUsers” or whatever you pass back from getRoleSets in the Login Module. But, again, PAM won’t give you different groups… The other thing to note is that I set the error page for 400 (Bad Request) errors to the login page, index.html. This gets around a -bug- feature in JBoss.

Next, we need to modify jboss-web.xml. This one is pretty easy. It ties together your app and the security configuration we setup above.

< ?xml version="1.0" encoding="ISO-8859-1"?>
<jboss -web>
    <context -root>/</context>
    <security -domain>java:/jaas/my_security</security>
</jboss>

That’s all there is to it!

Download: jboss-web.xml

Summary

1. Download SysAuth
2. Put libSysAuth.so in jboss/bin
3. Modify jboss/run.conf: set JAVA_OPTS=”-Djava.library.path=bin $JAVA_OPTS”
4. Create java_auth file in /etc/pam.d/
5. Create MyLoginModule class, in the WEB-INF/lib directory of your application
6. Add custom application-policy to login-config.xml to use our custom Login Module
7. Modify web.xml
8. Add entry in jboss-web.xml for our security configuration (application-policy)

Conclusion

This HOWTO certainly assume that you have some JBoss “know-how”. But as a supplment to all the great info on the JBoss site, it should be enough to get you going. Please feel free to post comments. Suggestions are welcome too!

Download all the files you need to change to make this work: jboss_linux_authentication.tar.gz

Version 1.0