Specifying the JAAS login module configuration file on the Jetty run line

Fine Tuning the JAASLoginService

To allow the greatest degree of flexibility in using JAAS with web applications, the JAASLoginService supports additional configuration options. You don't ordinarily need to set these explicitly, as Jetty has defaults which work in 99% of cases. However, should you need to, you can configure:

Understanding the RoleCheckPolicy

The RoleCheckPolicy must be an implementation of the org.eclipse.jetty.plus.jaas.RoleCheckPolicy interface, and its purpose is to help answer the question "is User X in Role Y?" for role-based authorization requests. The default implementation distributed with Jetty is the org.eclipse.jetty.plus.jaas.StrictRoleCheckPolicy, which assesses a user as having a particular role if that role is at the top of the stack of roles that have been temporarily pushed onto the user, or if the user has no temporarily assigned roles, the role is among those configured for the user.

You can temporarily assign roles to a user programmatically by using the pushRole(String rolename) method of the org.eclipse.jetty.plus.jaas.JAASUserPrincipal class.

For the majority of webapps, the default StrictRoleCheckPolicy is adequate, but you can provide your own implementation and set it on your tt>JAASLoginService</tt> instance.

Using the CallbackHandler

A CallbackHandler is responsible for interfacing with the user to obtain usernames and credentials to be authenticated.

Jetty ships with a CallbackHandler which interfaces the information contained in the request to the Callbacks that LoginModules requests. You can replace this default with your own implementation if you have specific requirements not covered by the default.

Configuring a Role Principal Implementation Class

When LoginModules authenticate a user, they usually also gather all of the roles that a user has and place them inside the JAAS Subject. As LoginModules are free to use their own implementation of the JAAS Principal to put into the Subject, Jetty needs to know which Principals represent the user and which represent his/her roles when performing authorization checks on security-constraints. The example LoginModules that ship with jetty all use the org.mortbay.jetty.plus.jaas.JAASRole class. However, if you have plugged in some other LoginModules, you must configure the classnames of their role Principal implementations.

Examining Sample Login Modules

At the time of writing, Jetty provides four sample LoginModule implementations:

org.eclipse.jetty.plus.jaas.spi.JDBCLoginModule

org.eclipse.jetty.plus.jaas.spi.PropertyFileLoginModule

org.eclipse.jetty.plus.jaas.spi.DataSourceLoginModule

org.eclipse.jetty.plus.jaas.ldap.LdapLoginModule

We'll take a look at all of these, but first, a word about password handling in Jetty, as it applies to all LoginModules.

Understanding Passwords/Credentials

Passwords can be stored in clear text, obfuscated or checksummed. Use the class org.eclipse.jetty.http.security.Password to generate all varieties of passwords, the output from which you can cut and paste into property files or enter into database tables.

JDBCLoginModule

The JDBCLoginModule stores user passwords and roles in a database that is accessed via JDBC calls. You can configure the JDBC connection information, as well as the names of the table and columns storing the username and credential, and the name of the table and columns storing the roles.

Here is an example login module configuration file entry for it using an HSQLDB driver:

There is no particular schema required for the database tables storing the authentication and role information. The properties userTable, userField, credentialField, userRoleTable, userRoleUserField, userRoleRoleField configure the names of the tables and the columns within them that are used to format the following queries:

Credential and role information is lazily read from the database when a previously unauthenticated user requests authentication. This information is only cached for the length of the authenticated session. When the user logs out or the session expires, the information is flushed from memory.

You can store passwords in the database in plain text or encoded formats, using the Jetty password utility.

DataSourceLoginModule

Similar to the JDBCLoginModule, but this LoginModule uses a DataSource to connect to the database instead of a JDBC driver. The DataSource is obtained by doing a JNDI lookup on java:comp/env/$\{dnJNDIName\}.

Here is a sample login module configuration for the DataSourceLoginModule:

Configuring the Role Principal Implementation Class for the LdapLoginModule[1]

The LdapLoginModule does not deal with the situation of user -> some group -> role group, as it assigns users directly to the role group. If you want to specify role occupants by groups within an organization, you need the ability to sort them in this way. The following example shows how to do so by configuring RoleClassNames information. This example implements WAFFLE, which lets you run Jetty under Windows with Active Directory.

The org.eclipse.jetty.plus.jaas.spi.AbstractLoginModule implements all of the javax.security.auth.spi.LoginModule methods. All you need to do is to implement the getUserInfo method to return an org.eclipse.jetty.plus.jaas.UserInfo instance which encapsulates the username, password and role names as java.lang.Strings for a user.

The AbstractLoginModule does not support any caching, so if you want to cache UserInfo (as, for example, does the org.mortbay.jetty.plus.jaas.spi.PropertyFileLoginModule, then you must provide this yourself.

Examining an Example JAAS WebApp

There is an example of authentication and web authorization in the Jetty distribution in examples/test-jaas-webapp. It uses the PropertyFileLoginModule to perform authentication based on a simple properties file. To use it with the jetty maven plugin:

Other Goodies

RequestParameterCallback

As all servlet containers intercept and process a form submission with action j_security_check, it is usually not possible to insert any extra input fields onto a login form with which to perform authentication: you may only pass j_username and j_password. For those rare occasions when this is not good enough, and you require more information from the user in order to authenticate them, you can use the JAAS callback handler org.mortbay.jetty.plus.jaas.callback.RequestParameterCallback. This callback handler gives you access to all parameters passed in the form submission. To use it, in the login() method of your custom login module, add the RequestParameterCallback to the list of callback handlers the login module uses, tell it which parameters you are want, and then get the value of the parameter back. Here's an example: