Java 2 Platform EE v1.3: Class Configuration - Java Platform, Enterprise Edition v1.3.1 API Specifications

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.login
Class Configuration

java.lang.Object
  |
  +--javax.security.auth.login.Configuration

public abstract class Configuration
extends java.lang.Object

This is an abstract class for representing the configuration of LoginModules under an application. The Configuration specifies which LoginModules should be used for a particular application, and in what order the LoginModules should be invoked. This abstract class needs to be subclassed to provide an implementation which reads and loads the actual Configuration.

When the LoginContext needs to read the Configuration to determine which LoginModules are configured for a particular application, appName, it makes the following calls:

	config = Configuration.getConfiguration();
	entries = config.getAppConfigurationEntry(appName);

A login configuration contains the following information. Note that this example only represents the default syntax for the Configuration. Subclass implementations of this class may implement alternative syntaxes and may retrieve the Configuration from any source such as files, databases, or servers.

      Application {
	      Module  Flag    ModuleOptions;
	      Module  Flag    ModuleOptions;
	      Module  Flag    ModuleOptions;
      };
      Application {
	      Module  Flag    ModuleOptions;
	      Module  Flag    ModuleOptions;
      };
      other {
	      Module  Flag    ModuleOptions;
	      Module  Flag    ModuleOptions;
      };

Each entry in the Configuration is indexed via an application name, Application, and contains a list of LoginModules configured for that application. Authentication proceeds down the list in the exact order specified. If an application does not have specific entry, it defaults to the specific entry for "other".

The Flag value controls the overall behavior as authentication proceeds down the stack. The following represents a description of the valid values for Flag and their respective semantics:

      1) Required     - The LoginModule is required to succeed.
			If it succeeds or fails, authentication still continues
			to proceed down the LoginModule list.

      2) Requisite    - The LoginModule is required to succeed.
			If it succeeds, authentication continues down the
			LoginModule list.  If it fails,
			control immediately returns to the application
			(authentication does not proceed down the
			LoginModule list).

      3) Sufficient   - The LoginModule is not required to
			succeed.  If it does succeed, control immediately
			returns to the application (authentication does not
			proceed down the LoginModule list).
			If it fails, authentication continues down the
			LoginModule list.

      4) Optional     - The LoginModule is not required to
			succeed.  If it succeeds or fails,
			authentication still continues to proceed down the
			LoginModule list.

The overall authentication succeeds only if all Required and Requisite LoginModules succeed. If a Sufficient LoginModule is configured and succeeds, then only the Required and Requisite LoginModules prior to that Sufficient LoginModule need to have succeeded for the overall authentication to succeed. If no Required or Requisite LoginModules are configured for an application, then at least one Sufficient or Optional LoginModule must succeed.

ModuleOptions is a space separated list of LoginModule-specific values which are passed directly to the underlying LoginModules. 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 is by using the following key-value pairing: debug=true. The key and value should be separated by an 'equals' symbol. Note that there is no limit to the number of options a LoginModule may define.

The following represents an example Configuration entry based on the syntax above:

      Login {
	      sun.modules.SmartCard   required;
	      sun.modules.Kerberos    optional	debug=true;
      };

This Configuration specifies that an application named, "Login", requires users to first authenticate to the sun.modules.SmartCard LoginModule, which is required to succeed. Even if the sun.modules.SmartCard authentication fails (an incorrect pin was entered), the sun.modules.Kerberos LoginModule still gets invoked. This helps hide the source of failure. Since the sun.modules.Kerberos LoginModule is Optional, the overall authentication succeeds only if the sun.modules.SmartCard LoginModule (Required) succeeds.

Also note that the LoginModule-specific option, debug=true, is passed to the sun.modules.Kerberos LoginModule. This turns on a debugging flag, which outputs helpful debugging information to a file.

The default Configuration implementation can be changed by setting the value of the "login.configuration.provider" security property (in the Java security properties file) to the fully qualified name of the desired Configuration implementation class. The Java security properties file is located in the file named <JAVA_HOME>/lib/security/java.security, where <JAVA_HOME> refers to the directory where the JDK was installed.

See Also:: LoginContext

Constructor Summary

protected Configuration()
          Sole constructor.

Method Summary

abstract AppConfigurationEntry[] getAppConfigurationEntry(java.lang.String applicationName)
          Retrieve an array of AppConfigurationEntries which corresponds to the configuration of LoginModules for this application.

static Configuration getConfiguration()
          Get the current Login Configuration.

abstract void refresh()
          Refresh and reload the Configuration.

static void setConfiguration(Configuration configuration)
          Set the current Login Configuration

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Configuration

protected Configuration()

Sole constructor. (For invocation by subclass constructors, typically implicit.)

Method Detail

getConfiguration

public static Configuration getConfiguration()

Get the current Login Configuration.

Returns:: the current Login Configuration.
Throws:: java.lang.SecurityException - if the caller does not have permission to retrieve the Configuration.

setConfiguration

public static void setConfiguration(Configuration configuration)

Set the current Login Configuration

Parameters:: configuration - the new Configuration
Throws:: java.lang.SecurityException - if the current thread does not have Permission to set the Configuration.

getAppConfigurationEntry

public abstract AppConfigurationEntry[] getAppConfigurationEntry(java.lang.String applicationName)

Retrieve an array of AppConfigurationEntries which corresponds to the configuration of LoginModules for this application.

Parameters:: applicationName - the name used to index the Configuration.
Returns:: an array of AppConfigurationEntries which corresponds to the configuration of LoginModules for this application, or null if this application has no configured LoginModules.

refresh

public abstract void refresh()

Refresh and reload the Configuration.

This method causes this object to refresh/reload its current Configuration. This is implementation-dependent. For example, if the Configuration object is stored a file, calling refresh will cause the file to be re-read.

Throws:: java.lang.SecurityException - if the caller does not have permission to refresh the Configuration.