private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery
JAAS implements a Java version of the standard Pluggable Authentication Module (PAM) framework.
JAAS can be used for two purposes:
for authentication of users, to reliably and securely determine who is currently executing Java code, regardless of whether the code is running as an application, an applet, a bean, or a servlet; and
for authorization of users to ensure they have the access control rights (permissions) required to do the actions performed.
JAAS authentication is performed in a pluggable fashion. This permits applications to remain independent from underlying authentication technologies. New or updated authentication technologies can be plugged under an application without requiring modifications to the application itself. Applications enable the authentication process by instantiating a LoginContext object, which in turn references a Configuration to determine the authentication technology(ies), or LoginModule(s), to be used in performing the authentication. Typical LoginModules may prompt for and verify a username and password. Others may read and verify a voice or fingerprint sample.
See Java Authentication and Authorization Service (JAAS) Reference Guide for more information about JAAS.
Many application servers support JAAS as a means of bringing greater flexibility to the declarative security models of the J2EE (now known as the JavaEE) specification. Jetty support for JAAS provides greater alternatives for servlet security, and increases the portability of web applications.
The JAAS support aims to dictate as little as possible whilst providing a sufficiently flexible infrastructure to allow users to drop in their own custom LoginModules.
Using JAAS with jetty is very simply a matter of declaring a
org.eclipse.jetty.jaas.JAASLoginService, creating a jaas
login module configuration file and specifying it on the jetty run line.
Let's look at an example.
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
Then you need to create a JAASLoginService with the matching name of "xyz":
The name of the realm-name that you declare in
web.xml must match exactly the Name element in
your jetty config file.
You can declare your JAASLoginService in a couple of different ways:
If you have more than one webapp that you would like to use the same security infrastructure, then you can declare your JAASLoginService in a top-level jetty xml file as a bean that is added to the org.eclipse.jetty.Server. Here's an example:
Alternatively, you can use a JAASLoginService with just a specific webapp by creating a context xml file for the webapp, and specifying the JAASLoginService in it:
Set up your
LoginModule in a configuration file,
following the syntax
It is imperative that the application name on the first line is
exactly the same as the
LoginModuleName from your jetty
You may find it convenient to name this configuration file as
$JETTY_HOME/etc/login.conf because, as we will see
below, some of the wiring up for jaas has been done for you, only
requiring you to uncomment the appropriate lines in start.ini.
You now need to invoke jetty with support for jaas. There are 2 aspects to this:
adding jaas-related jars to the jetty container classpath
setting the System property java.security.auth.login.config
The easist way to get the required extra jars on the classpath, and set the System property is to use jetty start.ini mechanism and uncomment the following lines:
Note that if you placed your login module
configuration file created in Step 2 in another directory inside
$JETTY_HOME, then change the "etc/login.conf" line appropriately. If you
placed it outside of $JETTY_HOME, then edit the
etc/jetty-jaas.xml file directly and replace the property
jetty.login.conf with the absolute location
of the file.
If you created a new jetty xml configuration file to hold the
definition of your JAASLoginService in Step 1, then you can ensure it is
executed by adding it into the start.ini file too. For
example, if you created the file
etc/my-jaas.xml, then add
that into the JAAS section like so:
If in Step 1 you opted to make a context xml file for your webapp and declared the JAASLoginService in it, then uncommenting the JAAS section of the start.ini file is all you need do.
To allow the greatest degree of flexibility in using JAAS with web
JAASLoginService supports a
couple of configuration options. Note that you don't ordinarily need to
set these explicitly, as jetty has defaults which will work in 99% of
cases. However, should you need to, you can configure:
a policy for role-based authorization (Default:
a CallbackHandler (Default:
a list of classnames for the Principal implementation that
equate to a user role (Default:
Here's an example of setting each of these (to their default values):
The RoleCheckPolicy must be an implementation of the
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
which will assess a user as having a particular role iff 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
amongst those configured for the user.
Roles can be temporarily assigned to a user programmatically by
using the pushRole(String rolename) method of the
For the majority of webapps, the default StrictRoleCheckPolicy will be quite adequate, however you may provide your own implementation and set it on your JAASUserRealm instance.
A CallbackHandler is responsible for interfacing with the user to obtain usernames and credentials to be authenticated.
Jetty ships with the
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>s. The example
LoginModules that ship with jetty all use the
org.eclipse.jetty.jaas.JAASRole class. However,
if you have plugged in some other LoginModules, you must configure the
classnames of their role Principal implementations.
Passwords can be stored in clear text, obfuscated or
checksummed. The class
should be used to generate all varieties of passwords,the output from
which can be cut and pasted into property files or entered into
See more on this under Secure Password Obfuscation.
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 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:
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 "Passwords/Credentials" note 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 doing a jndi lookup on
Here is a sample login module configuration for it:
With this login module implementation, the authentication and role information is read from a property file.
The file parameter is the location of a properties file of the same format as the etc/realm.properties example file. The format is:
Here's an example:
The contents of the file are fully read in and cached in memory the first time a user requests authentication.
If you want to implement your own custom LoginModule, there are two
classes to be familiar with
implements all of the
javax.security.auth.spi.LoginModule methods. All
you need to do is to implement the getUserInfo method to return a
org.eclipse.jetty.jaas.UserInfo instance which
encapsulates the username, password and role names (note: as
java.lang.Strings) for a user.
The AbstractLoginModule does not support any caching, so if you want
to cache UserInfo (eg as does the
then you must provide this yourself.
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_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
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's an
An example webapp using jaas can be found in our git repo: