Recipe 15.7 Creating the JAAS Configuration File

Problem

You want to create the JAAS configuration file.

Solution

Create the configuration file, then specify the configuration's location on your filesystem in the ${java.home}/jre/lib/security/java.security file.

Discussion

Using JAAS also involves writing a configuration file to identify the LoginModule(s) that a particular application will use. The configuration file in Example 15-11 specifies an application named "WebLogin."

Example 15-11. A JAAS configuration file

WebLogin {
   com.jspservletcookbook.DataSourceLoginModule requisite;
};

Although only one module is specified in this recipe, one of the powerful features of the JAAS security design is to use multiple LoginModules or layers in order to authenticate users. A user might have to be authenticated in several ways before she gains access to web components and data (e.g., first her irises are scanned, then she must specify a username and password).

The configuration file specifies:

• The fully qualified class name of the LoginModule(s).

• A "Flag" value, which is just a constant expression such as "required" or "requisite." The example uses "requisite." Table 15-1 describes the different Flag values.

• One or more "options" (Example 15-11 does not identify any options). The options represent a space-separated list of name/value pairs, such as debug="true" (you can use any name/value pairing you want). The options allow the configuration file to pass properties and values to the underlying LoginModule.

Table 15-1. Flag values for JAAS configuration files

Flag name	Description
Required	The LoginModule is required to succeed, and overall authentication fails if a LoginModule marked "required" fails. However, if a failure occurs, authentication still continues down the LoginModule list.
Requisite	The LoginModule is required to succeed, and runtime control returns to the application (rather than continuing with any other listed LoginModules) if authentication failure occurs.
Sufficient	If the LoginModule succeeds, control returns to the application and does not continue with any other listed LoginModules. If an authentication failure occurs, authentication continues with any other LoginModule. In other words, the failure of this LoginModule does not automatically lead to the failure of overall authentication, as in "required" or "requisite."
Optional	Success is not required with this LoginModule. If authentication success or failure occurs, authentication continues with any other listed LoginModules.

The basic structure of the configuration file looks like this:

ApplicationName{

    ModuleName Flag Options;
    ModuleName Flag Options;
    ModuleName Flag Options;
};

AnotherApplication{

    ModuleName Flag Options;
    ModuleName Flag Options;
};

Again, you do not have to use multiple LoginModules.

See this Javadoc page for more details on configuration: http://java.sun.com/j2se/1.4.1/docs/api/javax/security/auth/login/Configuration.html.

How does the JAAS implementation find the configuration file? The directory ${java.home}/jre/lib/security contains a file named java.security. This is a "properties" or "policy" file in Java security parlance—a text file containing name/value pairs. The following line of text provides the location of the JAAS configuration file for the authentication servlet of Example 15-11:

login.config.url.1=file:h:/home/.java.login.config

If you have other JAAS configuration files that you want to combine with this one, use syntax similar to login.config.url.2=file:h:/home/.my.config (note the incremented number 2), placed within the java.security file.

You can use any filenaming convention; the configuration filename does not have to begin with a period.

A single JAAS configuration file can specify the LoginModule(s) for multiple application names. Recipe 15.8 shows a servlet that uses the LoginModule described in Recipe 15.5.

See Also

Sun Microsystems' JAAS developer's guide: http://java.sun.com/j2se/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.html; a list of JAAS tutorials and sample programs: http://java.sun.com/j2se/1.4.2/docs/guide/security/jaas/JAASRefGuide.html; the Javadoc relating to JAAS configuration files: http://java.sun.com/j2se/1.4.1/docs/api/javax/security/auth/login/Configuration.html; Recipe 15.8 on using JAAS with a servlet; Recipe 15.9 on using JAAS with a JSP.