javax.security.auth.login
Class Configuration

java.lang.Object sample code for java.lang.Object definition code for java.lang.Object 
  extended by javax.security.auth.login.Configuration

public abstract class Configuration
extends Object sample code for java.lang.Object definition code for 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.

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.

      Name {
              ModuleClass  Flag    ModuleOptions;
              ModuleClass  Flag    ModuleOptions;
              ModuleClass  Flag    ModuleOptions;
      };
      Name {
              ModuleClass  Flag    ModuleOptions;
              ModuleClass  Flag    ModuleOptions;
      };
      other {
              ModuleClass  Flag    ModuleOptions;
              ModuleClass  Flag    ModuleOptions;
      };
 

Each entry in the Configuration is indexed via an application name, Name, and contains a list of LoginModules configured for that application. Each LoginModule is specified via its fully qualified class name. Authentication proceeds down the module 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, and the value should be surrounded by double quotes. If a String in the form, ${system.property}, occurs in the value, it will be expanded to the value of the system property. 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 {
   com.sun.security.auth.module.UnixLoginModule required;
   com.sun.security.auth.module.Krb5LoginModule optional
                   useTicketCache="true"
                   ticketCache="${user.home}${/}tickets";
 };
 

This Configuration specifies that an application named, "Login", requires users to first authenticate to the com.sun.security.auth.module.UnixLoginModule, which is required to succeed. Even if the UnixLoginModule authentication fails, the com.sun.security.auth.module.Krb5LoginModule still gets invoked. This helps hide the source of failure. Since the Krb5LoginModule is Optional, the overall authentication succeeds only if the UnixLoginModule (Required) succeeds.

Also note that the LoginModule-specific options, useTicketCache="true" and ticketCache=${user.home}${/}tickets", are passed to the Krb5LoginModule. These options instruct the Krb5LoginModule to use the ticket cache at the specified location. The system properties, user.home and / (file.separator), are expanded to their respective values.

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 sample code for javax.security.auth.login.LoginContext definition code for javax.security.auth.login.LoginContext

Constructor Summary
protected Configuration sample code for javax.security.auth.login.Configuration.Configuration() definition code for javax.security.auth.login.Configuration.Configuration() ()
          Sole constructor.
 
Method Summary
abstract  AppConfigurationEntry sample code for javax.security.auth.login.AppConfigurationEntry definition code for javax.security.auth.login.AppConfigurationEntry [] getAppConfigurationEntry sample code for javax.security.auth.login.Configuration.getAppConfigurationEntry(java.lang.String) definition code for javax.security.auth.login.Configuration.getAppConfigurationEntry(java.lang.String) (String sample code for java.lang.String definition code for java.lang.String  name)
          Retrieve the AppConfigurationEntries for the specified name from this Configuration.
static Configuration sample code for javax.security.auth.login.Configuration definition code for javax.security.auth.login.Configuration getConfiguration sample code for javax.security.auth.login.Configuration.getConfiguration() definition code for javax.security.auth.login.Configuration.getConfiguration() ()
          Get the Login Configuration.
abstract  void refresh sample code for javax.security.auth.login.Configuration.refresh() definition code for javax.security.auth.login.Configuration.refresh() ()
          Refresh and reload the Configuration.
static void setConfiguration sample code for javax.security.auth.login.Configuration.setConfiguration(javax.security.auth.login.Configuration) definition code for javax.security.auth.login.Configuration.setConfiguration(javax.security.auth.login.Configuration) (Configuration sample code for javax.security.auth.login.Configuration definition code for javax.security.auth.login.Configuration  configuration)
          Set the Login Configuration.
 
Methods inherited from class java.lang.Object sample code for java.lang.Object definition code for java.lang.Object
clone sample code for java.lang.Object.clone() definition code for java.lang.Object.clone() , equals sample code for java.lang.Object.equals(java.lang.Object) definition code for java.lang.Object.equals(java.lang.Object) , finalize sample code for java.lang.Object.finalize() definition code for java.lang.Object.finalize() , getClass sample code for java.lang.Object.getClass() definition code for java.lang.Object.getClass() , hashCode sample code for java.lang.Object.hashCode() definition code for java.lang.Object.hashCode() , notify sample code for java.lang.Object.notify() definition code for java.lang.Object.notify() , notifyAll sample code for java.lang.Object.notifyAll() definition code for java.lang.Object.notifyAll() , toString sample code for java.lang.Object.toString() definition code for java.lang.Object.toString() , wait sample code for java.lang.Object.wait() definition code for java.lang.Object.wait() , wait sample code for java.lang.Object.wait(long) definition code for java.lang.Object.wait(long) , wait sample code for java.lang.Object.wait(long, int) definition code for java.lang.Object.wait(long, int)
 

Constructor Detail

Configuration sample code for javax.security.auth.login.Configuration() definition code for javax.security.auth.login.Configuration()

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

Method Detail

getConfiguration sample code for javax.security.auth.login.Configuration.getConfiguration() definition code for javax.security.auth.login.Configuration.getConfiguration()

public static Configuration sample code for javax.security.auth.login.Configuration definition code for javax.security.auth.login.Configuration  getConfiguration()
Get the Login Configuration.

Returns:
the login Configuration. If a Configuration object was set via the Configuration.setConfiguration method, then that object is returned. Otherwise, a default Configuration object is returned.
Throws:
SecurityException sample code for java.lang.SecurityException definition code for java.lang.SecurityException - if the caller does not have permission to retrieve the Configuration.
See Also:
setConfiguration(javax.security.auth.login.Configuration) sample code for javax.security.auth.login.Configuration.setConfiguration(javax.security.auth.login.Configuration) definition code for javax.security.auth.login.Configuration.setConfiguration(javax.security.auth.login.Configuration)

setConfiguration sample code for javax.security.auth.login.Configuration.setConfiguration(javax.security.auth.login.Configuration) definition code for javax.security.auth.login.Configuration.setConfiguration(javax.security.auth.login.Configuration)

public static void setConfiguration(Configuration sample code for javax.security.auth.login.Configuration definition code for javax.security.auth.login.Configuration  configuration)
Set the Login Configuration.

Parameters:
configuration - the new Configuration
Throws:
SecurityException sample code for java.lang.SecurityException definition code for java.lang.SecurityException - if the current thread does not have Permission to set the Configuration.
See Also:
getConfiguration() sample code for javax.security.auth.login.Configuration.getConfiguration() definition code for javax.security.auth.login.Configuration.getConfiguration()

getAppConfigurationEntry sample code for javax.security.auth.login.Configuration.getAppConfigurationEntry(java.lang.String) definition code for javax.security.auth.login.Configuration.getAppConfigurationEntry(java.lang.String)

public abstract AppConfigurationEntry sample code for javax.security.auth.login.AppConfigurationEntry definition code for javax.security.auth.login.AppConfigurationEntry [] getAppConfigurationEntry(String sample code for java.lang.String definition code for java.lang.String  name)
Retrieve the AppConfigurationEntries for the specified name from this Configuration.

Parameters:
name - the name used to index the Configuration.
Returns:
an array of AppConfigurationEntries for the specified name from this Configuration, or null if there are no entries for the specified name

refresh sample code for javax.security.auth.login.Configuration.refresh() definition code for javax.security.auth.login.Configuration.refresh()

public abstract void refresh()
Refresh and reload the Configuration.

This method causes this Configuration object to refresh/reload its contents in an implementation-dependent manner. For example, if this Configuration object stores its entries in a file, calling refresh may cause the file to be re-read.

Throws:
SecurityException sample code for java.lang.SecurityException definition code for java.lang.SecurityException - if the caller does not have permission to refresh its Configuration.