Appendix B: JAAS Login Configuration File

JAAS authentication is performed in a pluggable fashion, so Java applications can remain independent from underlying authentication technologies. Configuration information such as the desired authentication technology is specified at runtime. The source of the configuration information (for example, a file or a database) is up to the current javax.security.auth.login.Configuration implementation. The default Configuration implementation, ConfigFile, gets its configuration information from login configuration files. For details about the default login Configuration implementation provided with JAAS, see the com.sun.security.auth.login.ConfigFile class.

Login Configuration File Structure and Contents

A login configuration file consists of one or more entries, each specifying which underlying authentication technology should be used for a particular application or applications. The structure of each entry is the following:

<name used by application to refer to this entry> { 
    <LoginModule> <flag> <LoginModule options>;
    <optional additional LoginModules, flags and options>;
};

Thus, each login configuration file entry consists of a name followed by one or more LoginModule-specific entries, where each LoginModule-specific entry is terminated by a semicolon and the entire group of LoginModule-specific entries is enclosed in braces. Each configuration file entry is terminated by a semicolon.

Example 6-1 Login Configuration File for JAAS Authentication Tutorial

As an example, the login configuration file used for the JAAS Authentication Tutorial tutorial contains just one entry, which is

Sample {
   sample.module.SampleLoginModule required debug=true;
};

Here, the entry is named Sample and that is the name that the JAAS Authentication tutorial application (SampleAcn.java) uses to refer to this entry. The entry specifies that the LoginModule to be used to do the user authentication is the SampleLoginModule in the sample.module package and that this SampleLoginModule is required to "succeed" in order for authentication to be considered successful. The SampleLoginModule succeeds only if the name and password supplied by the user are the ones it expects (testUser and testPassword, respectively).

The name for an entry in a login configuration file is the name that applications use to refer to the entry when they instantiate a LoginContext, as described in JAAS Authentication Tutorial in the JAAS authentication tutorial. The name can be whatever name the application developer wishes to use. Here, the term "application" refers to whatever code does the JAAS login.

The specified LoginModules are used to control the authentication process. Authentication proceeds down the list in the exact order specified, as described in the Configuration class.

The subparts of each LoginModule-specific entry are the following:

LoginModule: This specifies a class implementing the desired authentication technology. Specifically, the class must be a subclass of the LoginModule class, which is in the javax.security.auth.spi package. A typical LoginModule may prompt for and verify a user name and password, as is done by the SampleLoginModule (in the sample.module package) used for these tutorials. Any vendor can provide a LoginModule implementation that you can use. Some implementations are supplied with the JDK from Oracle. You can view the reference documentation for the various LoginModules, all in the com.sun.security.auth package:
flag: The flag value indicates whether success of the preceding LoginModule is required, requisite, sufficient, or optional. If there is just one LoginModule-specific entry, as there is in our tutorials, then the flag for it should be "required". The options are described in more detail in the Configuration class.
LoginModule options: If the specified LoginModule implementation has options that can be set, you specify any desired option values here. This is a space-separated list of values which are passed directly to the underlying LoginModule. Options are defined by the LoginModule itself, and control the behavior within it. For example, a LoginModule may define options to support debugging/testing capabilities.

The correct way to specify options in the configuration file is by using a name-value pairing, for example debug=true, where the option name (in this case, debug) and value (in this case, true) should be separated by an equals symbol.

Example 6-2 Login Configuration File Demonstrating required, sufficient, requisite, and optional Flags

The following is a sample login configuration file that demonstrates the required, sufficient, requisite, and optional flags. See the Configuration class for more information about these flags.

Login1 {
       sample.SampleLoginModule required debug=true;
    };

    Login2 {
       sample.SampleLoginModule required;
       com.sun.security.auth.module.NTLoginModule sufficient;
       com.foo.SmartCard requisite debug=true;
       com.foo.Kerberos optional debug=true;
    };

The application Login1 only has one configured LoginModule, SampleLoginModule. Therefore, an attempt by Login1 to authenticate a subject (user or service) will be successful if and only if the SampleLoginModule succeeds.

The authentication logic for the application Login2 is easier to explain with the following table:

Table 6-1 Login2 Authentication Status

Module Class	Flag	Authentication Attempt 1	Authentication Attempt 2	Authentication Attempt 3	Authentication Attempt 4	Authentication Attempt 5	Authentication Attempt 6	Authentication Attempt 7	Authentication Attempt 8
`SampleLoginModule`	required	pass	pass	pass	pass	fail	fail	fail	fail
`NTLoginModule`	sufficient	pass	fail	fail	fail	pass	fail	fail	fail
SmartCard	requisite	*	pass	pass	fail	*	pass	pass	fail
Kerberos	optional	*	pass	fail	*	*	pass	fail	*
Overall Authentication	not applicable	pass	pass	pass	fail	fail	fail	fail	fail

* = trivial value due to control returning to the application because a previous requisite module failed or a previous sufficient module succeeded.

Where to Specify Which Login Configuration File Should Be Used

The configuration file to be used can be specified in one of two ways:

On the command line.

You can use a -Djava.security.auth.login.config interpreter command line argument to specify the login configuration file that should be used. We use this approach for all the tutorials. For example, we run our SampleAcn application in the JAAS Authentication Tutorial using the following command, which specifies that the configuration file is the sample_jaas.config file in the current directory:
```
java -Djava.security.auth.login.config==sample_jaas.config sample.SampleAcn
```
Note:

If you use a single equals sign (=) with the java.security.auth.login.config system property (instead of a double equals sign (==)), then the configurations specified by both this system property and the java.security file are used.
In the Java Security Properties file.

An alternate approach to specifying the location of the login configuration file is to indicate its URL as the value of a login.config.url.n property in the security properties file. The Security Properties file is the java.security file located in the conf/security directory of the JDK.

Here, n indicates a consecutively-numbered integer starting with 1. Thus, if desired, you can specify more than one login configuration file by indicating one file's URL for the login.config.url.1 property, a second file's URL for the login.config.url.2 property, and so on. If more than one login configuration file is specified (that is, if n > 1), then the files are read and concatenated into a single configuration.

Here is an example of what would need to be added to the security properties file in order to indicate the sample_jaas.config login configuration file used by this tutorial. This example assumes the file is in the C:\AcnTest directory on Windows:
```
login.config.url.1=file:C:/AcnTest/sample_jaas.config
```
(Note that URLs always use forward slashes, regardless of what operating system the user is running.)