public abstract class Configuration extends Object
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 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 - TheLoginModule
is required to succeed. If it succeeds or fails, authentication still continues to proceed down theLoginModule
list. 2) Requisite - TheLoginModule
is required to succeed. If it succeeds, authentication continues down theLoginModule
list. If it fails, control immediately returns to the application (authentication does not proceed down theLoginModule
list). 3) Sufficient - TheLoginModule
is not required to succeed. If it does succeed, control immediately returns to the application (authentication does not proceed down theLoginModule
list). If it fails, authentication continues down theLoginModule
list. 4) Optional - TheLoginModule
is not required to succeed. If it succeeds or fails, authentication still continues to proceed down theLoginModule
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.
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.
- Since:
- 1.4
- See Also:
LoginContext
,security properties
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
Configuration.Parameters
This represents a marker interface for Configuration parameters. -
Constructor Summary
Constructors Modifier Constructor Description protected
Configuration()
Sole constructor. -
Method Summary
Modifier and Type Method Description abstract AppConfigurationEntry[]
getAppConfigurationEntry(String name)
Retrieve the AppConfigurationEntries for the specifiedname
from this Configuration.static Configuration
getConfiguration()
Get the installed login Configuration.static Configuration
getInstance(String type, Configuration.Parameters params)
Returns a Configuration object of the specified type.static Configuration
getInstance(String type, Configuration.Parameters params, String provider)
Returns a Configuration object of the specified type.static Configuration
getInstance(String type, Configuration.Parameters params, Provider provider)
Returns a Configuration object of the specified type.Configuration.Parameters
getParameters()
Return Configuration parameters.Provider
getProvider()
Return the Provider of this Configuration.String
getType()
Return the type of this Configuration.void
refresh()
Refresh and reload the Configuration.static void
setConfiguration(Configuration configuration)
Set the loginConfiguration
.
-
Constructor Details
-
Configuration
protected Configuration()Sole constructor. (For invocation by subclass constructors, typically implicit.)
-
-
Method Details
-
getConfiguration
Get the installed 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
- if the caller does not have permission to retrieve the Configuration.- See Also:
setConfiguration(javax.security.auth.login.Configuration)
-
setConfiguration
Set the loginConfiguration
.- Parameters:
configuration
- the newConfiguration
- Throws:
SecurityException
- if the current thread does not have Permission to set theConfiguration
.- See Also:
getConfiguration()
-
getInstance
public static Configuration getInstance(String type, Configuration.Parameters params) throws NoSuchAlgorithmExceptionReturns a Configuration object of the specified type.This method traverses the list of registered security providers, starting with the most preferred Provider. A new Configuration object encapsulating the ConfigurationSpi implementation from the first Provider that supports the specified type is returned.
Note that the list of registered providers may be retrieved via the
Security.getProviders()
method.- Implementation Note:
- The JDK Reference Implementation additionally uses the
jdk.security.provider.preferred
Security
property to determine the preferred provider order for the specified algorithm. This may be different than the order of providers returned bySecurity.getProviders()
. - Parameters:
type
- the specified Configuration type. See the Configuration section in the Java Security Standard Algorithm Names Specification for a list of standard Configuration types.params
- parameters for the Configuration, which may be null.- Returns:
- the new
Configuration
object - Throws:
IllegalArgumentException
- if the specified parameters are not understood by theConfigurationSpi
implementation from the selectedProvider
NoSuchAlgorithmException
- if noProvider
supports aConfigurationSpi
implementation for the specified typeNullPointerException
- iftype
isnull
SecurityException
- if the caller does not have permission to get aConfiguration
instance for the specified type- Since:
- 1.6
- See Also:
Provider
-
getInstance
public static Configuration getInstance(String type, Configuration.Parameters params, String provider) throws NoSuchProviderException, NoSuchAlgorithmExceptionReturns a Configuration object of the specified type.A new Configuration object encapsulating the ConfigurationSpi implementation from the specified provider is returned. The specified provider must be registered in the provider list.
Note that the list of registered providers may be retrieved via the
Security.getProviders()
method.- Parameters:
type
- the specified Configuration type. See the Configuration section in the Java Security Standard Algorithm Names Specification for a list of standard Configuration types.params
- parameters for the Configuration, which may be null.provider
- the provider.- Returns:
- the new
Configuration
object - Throws:
IllegalArgumentException
- if the specified provider isnull
or empty, or if the specified parameters are not understood by theConfigurationSpi
implementation from the specified providerNoSuchProviderException
- if the specified provider is not registered in the security provider listNoSuchAlgorithmException
- if the specified provider does not support aConfigurationSpi
implementation for the specified typeNullPointerException
- iftype
isnull
SecurityException
- if the caller does not have permission to get aConfiguration
instance for the specified type- Since:
- 1.6
- See Also:
Provider
-
getInstance
public static Configuration getInstance(String type, Configuration.Parameters params, Provider provider) throws NoSuchAlgorithmExceptionReturns a Configuration object of the specified type.A new Configuration object encapsulating the ConfigurationSpi implementation from the specified Provider object is returned. Note that the specified Provider object does not have to be registered in the provider list.
- Parameters:
type
- the specified Configuration type. See the Configuration section in the Java Security Standard Algorithm Names Specification for a list of standard Configuration types.params
- parameters for the Configuration, which may be null.provider
- the Provider.- Returns:
- the new
Configuration
object - Throws:
IllegalArgumentException
- if the specifiedProvider
isnull
, or if the specified parameters are not understood by theConfigurationSpi
implementation from the specified ProviderNoSuchAlgorithmException
- if the specifiedProvider
does not support aConfigurationSpi
implementation for the specified typeNullPointerException
- iftype
isnull
SecurityException
- if the caller does not have permission to get aConfiguration
instance for the specified type- Since:
- 1.6
- See Also:
Provider
-
getProvider
Return the Provider of this Configuration.This Configuration instance will only have a Provider if it was obtained via a call to
Configuration.getInstance
. Otherwise this method returns null.- Returns:
- the Provider of this Configuration, or null.
- Since:
- 1.6
-
getType
Return the type of this Configuration.This Configuration instance will only have a type if it was obtained via a call to
Configuration.getInstance
. Otherwise this method returns null.- Returns:
- the type of this Configuration, or null.
- Since:
- 1.6
-
getParameters
Return Configuration parameters.This Configuration instance will only have parameters if it was obtained via a call to
Configuration.getInstance
. Otherwise this method returns null.- Returns:
- Configuration parameters, or null.
- Since:
- 1.6
-
getAppConfigurationEntry
Retrieve the AppConfigurationEntries for the specifiedname
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 specifiedname
-
refresh
public 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.The default implementation of this method does nothing. This method should be overridden if a refresh operation is supported by the implementation.
- Throws:
SecurityException
- if the caller does not have permission to refresh its Configuration.
-