Introduction to JAAS

Overview

The Java Authentication and Authorization Service (JAAS) provides a general framework for implementing authentication in a Java application. The implementation of authentication is modular, with individual JAAS modules (or plug-ins) providing the authentication implementations. In particular, JAAS defines a general configuration file format that can be used to configure any custom login modules.

For background information about JAAS, see the JAAS Reference Guide.

JAAS login configuration

The JAAS login configuration file has the general format shown in Example 3.2.

Example 3.2. JAAS Login Configuration File Format

/* JAAS Login Configuration */

LoginEntry {
    ModuleClass Flag Option="Value" Option="Value" ... ;
    ModuleClass Flag Option="Value" Option="Value" ... ;
    ...
};
LoginEntry {
    ModuleClass Flag Option="Value" Option="Value" ... ;
    ModuleClass Flag Option="Value" Option="Value" ... ;
    ...
};
...

Where the file format can be explained as follows:

LoginEntry labels a single entry in the login configuration. An application is typically configured to search for a particular LoginEntry label (for example, in FUSE Message Broker the LoginEntry label to use is specifed in the broker configuration file). Each login entry contains a list of login modules that are invoked in order.
ModuleClass is the fully-qualified class name of a JAAS login module. For example, org.apache.activemq.jaas.PropertiesLoginModule is the class name of FUSE Message Broker's JAAS simple authentication login module.
Flag determines how to react when the current login module reports an authentication failure. The Flag can have one of the following values:
- required—authentication of this login module must succeed. Always proceed to the next login module in this entry, irrespective of success or failure.
- requisite—authentication of this login module must succeed. If success, proceed to the next login module; if failure, return immediately without processing the remaining login modules.
- sufficient—authentication of this login module is not required to succeed. If success, return immediately without processing the remaining login modules; if failure, proceed to the next login module.
- optional—authentication of this login module is not required to succeed. Always proceed to the next login module in this entry, irrespective of success or failure.
Option="Value"—after the Flag, you can pass zero or more option settings to the login module. The options are specified in the form of a space-separated list, where each option has the form Option="Value". The login module line is terminated by a semicolon, ;.

Location of the login configuration file

There are two general approaches to specifying the location of the JAAS login configuration file, as follows:

Set a system property—set the value of the system property, java.security.auth.login.config, to the location of the login configuration file. For example, you could set this system property on the command line, as follows:
```
java -Djava.security.auth.login.config=/var/activemq/config/login.config ...
```
Configure the JDK—if the relevant system property is not set, JAAS checks the $JAVA_HOME/jre/lib/security/java.security security properties file, looking for entries of the form:
```
login.config.url.1=file:C:/activemq/config/login.config
```
If there is more than one such entry, login.config.url.n, the entries must be consecutively numbered. The contents of the login files listed in java.security are merged into a single configuration.

In addition to these general approaches, FUSE Message Broker defines a custom approach to locating the JAAS login configuration. If the system property is not specified, the broker searches the CLASSPATH for a file named, login.config.