Configure a Jetty org.eclipse.jetty.jaas.JAASLoginService to match the <realm-name> in your web.xml file. For example, if the web.xml contains a realm called "xyz" like so:

<login-config>
  <auth-method>FORM</auth-method>
  <realm-name>xyz</realm-name>
  <form-login-config>
    <form-login-page>/login/login</form-login-page>
    <form-error-page>/login/error</form-error-page>
  </form-login-config>
</login-config>

Then you need to create a JAASLoginService with the matching name of "xyz":

<New class="org.eclipse.jetty.jaas.JAASLoginService">
  <Set name="Name">Test JAAS Realm</Set>
  <Set name="LoginModuleName">xyz</Set>
</New>

You can declare your JAASLoginService in a couple of different ways:

Set up your LoginModule in a configuration file, following the syntax rules :

xyz {
       com.acme.SomeLoginModule required debug=true;
    };

You may find it convenient to name this configuration file as etc/login.conf because, as we will see below, some of the wiring up for JAAS has been done for you.

You now need to invoke Jetty with support for JAAS. There are 2 aspects to this:

To accomplish the above, use the Jetty startup modules mechanism to add the JAAS module:

java -jar start.jar --add-to-start=jaas

Now you will have a file named start.d/jaas.ini, which contains:

--module=jaas
jaas.login.conf=etc/login.conf

The jaas.login.conf property refers to the location of your LoginModule configuration file that you established in Step 2. If you called it etc/login.conf, then your work is done. Otherwise, change the value of the jaas.login.conf property to be the location of your LoginModule configuration file. Jetty will automatically use this property to set the value of the System property java.security.auth.login.config.

The RoleCheckPolicy must be an implementation of the org.eclipse.jetty.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.jaas.StrictRoleCheckPolicy, which will assess 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. If the user has no temporarily assigned roles, the role is amongst those configured for the user.

Roles can be temporarily assigned to a user programmatically by using the pushRole(String rolename) method of the org.eclipse.jetty.jaas.JAASUserPrincipal class.

For the majority of webapps, the default StrictRoleCheckPolicy will be quite adequate, however you may provide your own implementation and set it on your JAASLoginService instance.

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

Jetty ships with the org.eclipse.jetty.jaas.DefaultCallbackHandler which interfaces the information contained in the request to the Callbacks that are requested by LoginModules. You can replace this default with your own implementation if you have specific requirements not covered by the default.

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-constraint>. The example LoginModules that ship with Jetty all use the org.eclipse.jetty.jaas.JAASRole class. However, if you have plugged in other LoginModules, you must configure the classnames of their role Principal implementations.

The JDBCLoginModule stores user passwords and roles in a database that are 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 names of the table and columns storing the roles.

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

jdbc {
      org.eclipse.jetty.jaas.spi.JDBCLoginModule required
      debug="true"
      dbUrl="jdbc:hsqldb:."
      dbUserName="sa"
      dbDriver="org.hsqldb.jdbcDriver"
      userTable="myusers"
      userField="myuser"
      credentialField="mypassword"
      userRoleTable="myuserroles"
      userRoleUserField="myuser"
      userRoleRoleField="myrole";
      };

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:

  select <credentialField> from <userTable>
          where <userField> =?
  select <userRoleRoleField> from <userRoleTable>
          where <userRoleUserField> =?

Credential and role information is lazily read from the database when a previously unauthenticated user requests authentication. Note that 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.

Note that passwords can be stored in the database in plain text or encoded formats - see the note on "Passwords/Credentials" above.

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 performing a JNDI lookup on java:comp/env/${dnJNDIName}.

A sample login module configuration using this method:

ds {
     org.eclipse.jetty.jaas.spi.DataSourceLoginModule required
     debug="true"
     dbJNDIName="ds"
     userTable="myusers"
     userField="myuser"
     credentialField="mypassword"
     userRoleTable="myuserroles"
     userRoleUserField="myuser"
     userRoleRoleField="myrole";
    };

With this login module implementation, the authentication and role information is read from a property file.

props {
        org.eclipse.jetty.jaas.spi.PropertyFileLoginModule required
        debug="true"
        file="/somewhere/somefile.props";
      };

The file parameter is the location of a properties file of the same format as the etc/realm.properties example file. The format is:

<username>: <password>[,<rolename> ...]

Here’s an example:

fred: OBF:1xmk1w261u9r1w1c1xmq,user,admin
harry: changeme,user,developer
tom: MD5:164c88b302622e17050af52c89945d44,user
dick: CRYPT:adpexzg3FUZAk,admin

The contents of the file are fully read in and cached in memory the first time a user requests authentication.

Here’s an example:

ldaploginmodule {
   org.eclipse.jetty.jaas.spi.LdapLoginModule required
   debug="true"
   contextFactory="com.sun.jndi.ldap.LdapCtxFactory"
   hostname="ldap.example.com"
   port="389"
   bindDn="cn=Directory Manager"
   bindPassword="directory"
   authenticationMethod="simple"
   forceBindingLogin="false"
   userBaseDn="ou=people,dc=alcatel"
   userRdnAttribute="uid"
   userIdAttribute="uid"
   userPasswordAttribute="userPassword"
   userObjectClass="inetOrgPerson"
   roleBaseDn="ou=groups,dc=example,dc=com"
   roleNameAttribute="cn"
   roleMemberAttribute="uniqueMember"
   roleObjectClass="groupOfUniqueNames";
   };

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.eclipse.jetty.jaas.callback.RequestParameterCallback. This callback handler gives you access to all parameters that were 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 params you are interested in, and then get the value of the parameter back. Here is an example:

public class FooLoginModule extends AbstractLoginModule
{
     public boolean login()
        throws LoginException
     {

        Callback[] callbacks = new Callback[3];
        callbacks[0] = new NameCallback();
        callbacks[1] = new ObjectCallback();

        //as an example, look for a param named "extrainfo" in the request
        //use one RequestParameterCallback() instance for each param you want to access
        callbacks[2] = new RequestParameterCallback ();
        ((RequestParameterCallback)callbacks[2]).setParameterName ("extrainfo");


        callbackHandler.handle(callbacks);
        String userName = ((NameCallback)callbacks[0]).getName();
        Object pwd = ((ObjectCallback)callbacks[1]).getObject();
        List paramValues = ((RequestParameterCallback)callbacks[2]).getParameterValues();

        //use the userName, pwd and the value(s) of the parameter named "extrainfo" to
        //authenticate the user

     }
}

An example webapp using JAAS can be found in the Jetty GitHub repository: