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 class javax.security.auth.login.Configuration. It reads configuration information from configuration files, which are described in this section.

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:

<entry name> { 
    <LoginModule> <flag> <LoginModule options>;
    <LoginModule> <flag> <LoginModule options>;
    // ...
    };

Thus, each login configuration file entry consists of a name followed by one or more LoginModule-specific items. Each LoginModule-specific item specifies a LoginModule, a flag value, and options to be passed to the LoginModule. (These are described futher below.) Each LoginModule-specific item is terminated by a semicolon and the entire group of items is enclosed in braces. Each configuration file entry is terminated by a semicolon.

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

JaasSample {
    com.sun.security.auth.module.Krb5LoginModule required;
};

Here, the entry is named "JaasSample" and that is the name that the JAAS Authentication tutorial application (JaasAcn.java) uses to refer to this entry. The entry specifies that the LoginModule to be used to do the user authentication is the Krb5LoginModule in the com.sun.security.auth.module package and that this Krb5LoginModule is required to "succeed" in order for authentication to be considered successful. The Krb5LoginModule succeeds only if the name and password supplied by the user are successfully used to log the user into the Kerberos KDC.

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 Instantiating a LoginContext 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, whether it is your application (as shown in the JAAS Authentication and JAAS Authorization tutorials) or a Login utility that does the JAAS operations for you (as shown in the Use of JAAS Login Utility and Use of Java GSS-API for Secure Message Exchanges Using JAAS Login Utility tutorials.)

The subparts of each LoginModule-specific item are described by the following. See the Configuration documentation for more information.

LoginModule

This specifies the fully qualified class name for a class that implements a particular authentication technology. Specifically, the class must implement the javax.security.auth.spi.LoginModule interface. A typical LoginModule may prompt for and verify a user name and password. Any vendor can provide a LoginModule implementation that you can use. Some implementations are supplied with the JRE from Sun Microsystems. Throughout these tutorials we use the Krb5LoginModule in the com.sun.security.auth.module package. The Krb5LoginModule uses Kerberos as the underlying authentication technology. 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 LoginModule is "required", "requisite", "sufficient", or "optional".
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. See the Krb5LoginModule documentation for information about the options defined for the Krb5LoginModule used for all the tutorials in this series.

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.

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 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 JaasAcn application in the JAAS Authentication tutorial using the following command, which specifies that the configuration file is the jaas.conf file in the current directory:
```
java -Djava.security.auth.login.config=jaas.conf JaasAcn
```
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 lib/security directory of the JRE.

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 jaas.conf login configuration file used by this tutorial. This example assumes the file is in the C:\AcnTest directory on a Microsoft Windows system:
```
login.config.url.1=file:C:/AcnTest/jaas.conf
```
(Note that URLs always use forward slashes, regardless of what operating system the user is running.)