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 from Sun Microsystems reads configuration information from configuration files, which are described in this document.

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.

As an example, the login configuration file used for the JAAS Authentication 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 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.

The specified LoginModules (described below) are used to control the authentication process. Authentication proceeds down the list in the exact order specified, as described here.

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

Where to Specify Which Login Configuration File Should Be Used

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

  1. 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
    
  2. 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 J2RE.

    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 a Microsoft Windows system:

    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.)