Class Configuration
A Configuration object is responsible for specifying which LoginModules should be used for a particular application, and in what order the LoginModules should be invoked.
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.
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 a 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 - TheLoginModuleis required to succeed. If it succeeds or fails, authentication still continues to proceed down theLoginModulelist. 2) Requisite - TheLoginModuleis required to succeed. If it succeeds, authentication continues down theLoginModulelist. If it fails, control immediately returns to the application (authentication does not proceed down theLoginModulelist). 3) Sufficient - TheLoginModuleis not required to succeed. If it does succeed, control immediately returns to the application (authentication does not proceed down theLoginModulelist). If it fails, authentication continues down theLoginModulelist. 4) Optional - TheLoginModuleis not required to succeed. If it succeeds or fails, authentication still continues to proceed down theLoginModulelist.
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, $, 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:
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=$$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.
There is only one Configuration object installed in the runtime at any given time. A Configuration object can be installed by calling the setConfiguration method. The installed Configuration object can be obtained by calling the getConfiguration method.
If no Configuration object has been installed in the runtime, a call to getConfiguration installs an instance of the default Configuration implementation (a default subclass implementation of this abstract class). The default Configuration implementation can be changed by setting the value of the login.configuration.provider security property to the fully qualified name of the desired Configuration subclass implementation.
Application code can directly subclass Configuration to provide a custom implementation. In addition, an instance of a Configuration object can be constructed by invoking one of the getInstance factory methods with a standard type. The default policy type is «JavaLoginConfig». See the Configuration section in the Java Security Standard Algorithm Names Specification for a list of standard Configuration types.
Class Configuration
A configuration encapsulates the readability graph that is the output of resolution. A readability graph is a directed graph whose vertices are of type ResolvedModule and the edges represent the readability amongst the modules. Configuration defines the modules() method to get the set of resolved modules in the graph. ResolvedModule defines the reads() method to get the set of modules that a resolved module reads. The modules that are read may be in the same configuration or may be in parent configurations.
Configuration defines the resolve method to resolve a collection of root modules, and the resolveAndBind method to do resolution with service binding. There are instance and static variants of both methods. The instance methods create a configuration with the receiver as the parent configuration. The static methods are for more advanced cases where there can be more than one parent configuration.
Each layer of modules in the Java virtual machine is created from a configuration. The configuration for the boot layer is obtained by invoking ModuleLayer.boot().configuration() . The configuration for the boot layer will often be the parent when creating new configurations.
Example
The following example uses the resolve method to resolve a module named myapp with the configuration for the boot layer as the parent configuration. It prints the name of each resolved module and the names of the modules that each module reads.
Path dir1 = . dir2 = . dir3 = . ; ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3); Configuration parent = ModuleLayer.boot().configuration(); Configuration cf = parent.resolve(finder, ModuleFinder.of(), Set.of("myapp")); cf.modules().forEach(m -> < System.out.format("%s ->%s%n", m.name(), m.reads().stream() .map(ResolvedModule::name) .collect(Collectors.joining(", "))); >); Class Configuration
A configuration encapsulates the readability graph that is the output of resolution. A readability graph is a directed graph whose vertices are of type ResolvedModule and the edges represent the readability amongst the modules. Configuration defines the modules() method to get the set of resolved modules in the graph. ResolvedModule defines the reads() method to get the set of modules that a resolved module reads. The modules that are read may be in the same configuration or may be in parent configurations.
Configuration defines the resolve method to resolve a collection of root modules, and the resolveAndBind method to do resolution with service binding. There are instance and static variants of both methods. The instance methods create a configuration with the receiver as the parent configuration. The static methods are for more advanced cases where there can be more than one parent configuration.
Each layer of modules in the Java virtual machine is created from a configuration. The configuration for the boot layer is obtained by invoking ModuleLayer.boot().configuration() . The configuration for the boot layer will often be the parent when creating new configurations.
Example
The following example uses the resolve method to resolve a module named myapp with the configuration for the boot layer as the parent configuration. It prints the name of each resolved module and the names of the modules that each module reads.
ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3); Configuration parent = ModuleLayer.boot().configuration(); Configuration cf = parent.resolve(finder, ModuleFinder.of(), Set.of("myapp")); cf.modules().forEach(m -> < System.out.format("%s ->%s%n", m.name(), m.reads().stream() .map(ResolvedModule::name) .collect(Collectors.joining(", "))); >);