jakarta.security.auth.message.config

Class AuthConfigFactory

java.lang.Object

jakarta.security.auth.message.config.AuthConfigFactory

public abstract class AuthConfigFactory
extends Object

This class is used to obtain AuthConfigProvider objects that can be used to obtain authentication context configuration objects, that is, ClientAuthConfig and ServerAuthConfig objects.

Authentication context configuration objects are used to obtain authentication context objects. Authentication context objects, that is, ClientAuthContext and ServerAuthContex objects, encapsulate authentication modules. Authentication modules are pluggable components that perform security-related processing of request and response messages.

Callers do not operate on modules directly. Instead they rely on an authentication context to manage the invocation of modules. A caller obtains an authentication context by calling the getAuthContext method on a ClientAuthConfig or ServerAuthConfig obtained from an AuthConfigProvider.

The following represents a typical sequence of calls for obtaining a client authentication context, and then using it to secure a request.

1. AuthConfigFactory factory = AuthConfigFactory.getFactory();
2. AuthConfigProvider provider = factory.getConfigProvider(layer,appID,listener);
3. ClientAuthConfig config = provider.getClientAuthConfig(layer,appID,cbh)
4. String authContextID = config.getAuthContextID(messageInfo);
5. ClientAuthContext context = config.getAuthContext(authContextID,subject,properties);
6. context.secureRequest(messageInfo,subject);

A system-wide AuthConfigFactory implementation can be set by invoking setFactory, and retrieved using getFactory.

Every implementation of this abstract class must offer a public, zero argument constructor. This constructor must support the construction and registration (including self-registration) of AuthConfigProviders from a persistent declarative representation. For example, a factory implementation class could interpret the contents of a file containing a sequence of configuration entries, with one entry per AuthConfigProvider, and with each entry representing:

• The fully qualified name of the provider implementation class (or null)
• The list of provider initialization properties (which could be empty)

Any provider initialization properties must be specified in a form that can be passed to the provider constructor within a Map of key, value pairs, and where all keys and values within the Map are of type String.

The entry syntax must also provide for the optional inclusion of information sufficient to define a RegistrationContext. This information would only be present when the factory will register the provider. For example, each entry could provide for the inclusion of one or more RegistrationContext objects of the following form:

• The message layer name (or null)
• The application context identifier (or null)
• The registration description (or null)

When a RegistrationContext is not included, the factory must make it convenient for the provider to self-register with the factory during the provider construction (see registerConfigProvider(AuthConfigProvider provider, ...)).

An AuthConfigFactory implementation is free to choose is own persistent declarative syntax as long as it conforms to the requirements defined by this class.

See Also:

ClientAuthContext, ServerAuthContext, ClientAuthConfig, ServerAuthConfig, Properties

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	AuthConfigFactory.RegistrationContext Represents the layer identifier, application context identifier, and description components of an AuthConfigProvider registration at the factory.

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_FACTORY_SECURITY_PROPERTY The name of the Security property used to define the default AuthConfigFactory implementation class.
static String	GET_FACTORY_PERMISSION_NAME The name of the SecurityPermission required to call getFactory
static SecurityPermission	getFactorySecurityPermission The SecurityPermission, with name GET_FACTORY_PERMISSION_NAME, that is used to authorize access to the getFactory method.
static String	PROVIDER_REGISTRATION_PERMISSION_NAME The name of the SecurityPermission to be used to authorize access to the update methods of the factory implementation class.
static SecurityPermission	providerRegistrationSecurityPermission An instance of the SecurityPermission (with name PROVIDER_REGISTRATION_PERMISSION_NAME) for use in authorizing access to the update methods of the factory implementation class.
static String	SET_FACTORY_PERMISSION_NAME The name of the SecurityPermission required to call setFactory
static SecurityPermission	setFactorySecurityPermission The SecurityPermission, with name SET_FACTORY_PERMISSION_NAME, that is used to authorize access to the setFactory method.

Constructor Summary

Constructors

Constructor and Description
AuthConfigFactory()

Method Summary

Modifier and Type	Method and Description
abstract String[]	detachListener(RegistrationListener listener, String layer, String appContext) Disassociate the listener from all the provider registrations whose layer and appContext values are matched by the corresponding arguments to this method.
abstract AuthConfigProvider	getConfigProvider(String layer, String appContext, RegistrationListener listener) Get a registered AuthConfigProvider from the factory.
static AuthConfigFactory	getFactory() Get the system-wide AuthConfigFactory implementation.
abstract AuthConfigFactory.RegistrationContext	getRegistrationContext(String registrationID) Get the the registration context for the identified registration.
abstract String[]	getRegistrationIDs(AuthConfigProvider provider) Get the registration identifiers for all registrations of the provider instance at the factory.
abstract void	refresh() Cause the factory to reprocess its persistent declarative representation of provider registrations.
abstract String	registerConfigProvider(AuthConfigProvider provider, String layer, String appContext, String description) Registers within the (in-memory) factory, a provider of ServerAuthConfig and/or ClientAuthConfig objects for a message layer and application context identifier.
abstract String	registerConfigProvider(String className, Map properties, String layer, String appContext, String description) Registers within the factory and records within the factory's persistent declarative representation of provider registrations a provider of ServerAuthConfig and/or ClientAuthConfig objects for a message layer and application context identifier.
abstract boolean	removeRegistration(String registrationID) Remove the identified provider registration from the factory (and from the persistent declarative representation of provider registrations, if appropriate) and invoke any listeners associated with the removed registration.
static void	setFactory(AuthConfigFactory factory) Set the system-wide AuthConfigFactory implementation.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_FACTORY_SECURITY_PROPERTY

public static final String DEFAULT_FACTORY_SECURITY_PROPERTY

The name of the Security property used to define the default AuthConfigFactory implementation class.

See Also:

Constant Field Values

GET_FACTORY_PERMISSION_NAME

public static final String GET_FACTORY_PERMISSION_NAME

The name of the SecurityPermission required to call getFactory

See Also:

Constant Field Values

SET_FACTORY_PERMISSION_NAME

public static final String SET_FACTORY_PERMISSION_NAME

The name of the SecurityPermission required to call setFactory

See Also:

Constant Field Values

PROVIDER_REGISTRATION_PERMISSION_NAME

public static final String PROVIDER_REGISTRATION_PERMISSION_NAME

The name of the SecurityPermission to be used to authorize access to the update methods of the factory implementation class.

See Also:

Constant Field Values

getFactorySecurityPermission

public static final SecurityPermission getFactorySecurityPermission

The SecurityPermission, with name GET_FACTORY_PERMISSION_NAME, that is used to authorize access to the getFactory method.

setFactorySecurityPermission

public static final SecurityPermission setFactorySecurityPermission

The SecurityPermission, with name SET_FACTORY_PERMISSION_NAME, that is used to authorize access to the setFactory method.

providerRegistrationSecurityPermission

public static final SecurityPermission providerRegistrationSecurityPermission

An instance of the SecurityPermission (with name PROVIDER_REGISTRATION_PERMISSION_NAME) for use in authorizing access to the update methods of the factory implementation class.

Constructor Detail

AuthConfigFactory

public AuthConfigFactory()

Method Detail

getFactory

public static AuthConfigFactory getFactory()

Get the system-wide AuthConfigFactory implementation.

If a non-null system-wide factory instance is defined at the time of the call, for example, with setFactory, it will be returned. Otherwise, an attempt will be made to construct an instance of the default AuthConfigFactory implementation class. The fully qualified class name of the default factory implementation class is obtained from the value of the DEFAULT_FACTORY_SECURITY_PROPERTY security property. When an instance of the default factory implementation class is successfully constructed by this method, this method will set it as the system-wide factory instance.

The absolute pathname of the Java security properties file is JAVA_HOME/lib/security/java.security, where JAVA_HOME refers to the directory where the JDK was installed.

When a SecurityManager is enabled, the getFactorySecurityPermission will be required to call this method. If at the time of the call, a system-wide factory instance has not already been defined, then the setFactorySecurityPermission will also be required.

Returns:

The non-null system-wide AuthConfigFactory instance set at the time of the call, or if that value was null, the value of the system-wide factory instance established by this method. This method returns null when the system-wide factory was not defined when this method was called and no default factory name was defined via the security property.

Throws:

SecurityException - If the caller does not have permission to retrieve the factory, or set it as the system-wide instance. Also thrown if an exception was thrown during the class loading, or construction of the default AuthConfigFactory implementation class; in which case the SecurityException will contain the root Exception as its cause.

setFactory

public static void setFactory(AuthConfigFactory factory)

Set the system-wide AuthConfigFactory implementation.

If an implementation was set previously, it will be replaced.

Listeners are not notified of a change to the registered factory.

Parameters:

factory - The AuthConfigFactory instance, which may be null.

Throws:

SecurityException - If the caller does not have permission to set the factory.

getConfigProvider

public abstract AuthConfigProvider getConfigProvider(String layer,
                                                     String appContext,
                                                     RegistrationListener listener)

Get a registered AuthConfigProvider from the factory. Get the provider of ServerAuthConfig and ClientAuthConfig objects registered for the identified message layer and application context.

All factories shall employ the following precedence rules to select the registered AuthConfigProvider that matches the layer and appContext arguments:

• The provider specifically registered for the values passed as the layer and appContext arguments shall be selected.
• If no provider is selected according to the preceding rule, the provider specifically registered for the value passed as the appContext argument and for all (that is, null) layers shall be selected.
• If no provider is selected according to the preceding rules, the provider specifically registered for the value passed as the layer argument and for all (that is, null) appContexts shall be selected.
• If no provider is selected according to the preceding rules, the provider registered for all (that is, null) layers and for all (that is, null) appContexts shall be selected.
• If no provider is selected according to the preceding rules, the factory shall terminate its search for a registered provider.

The above precedence rules apply equivalently to registrations created with a null or non-null className argument.

Parameters:

layer - A String identifying the message layer for which the registered AuthConfigProvider is to be returned. The value of this argument may be null.

appContext - A String that identifies the application messaging context for which the registered AuthConfigProvider is to be returned. The value of this argument may be null.

listener - The RegistrationListener whose notify method is to be invoked if the corresponding registration is unregistered or replaced. The value of this argument may be null.

Returns:

The implementation of the AuthConfigProvider interface registered at the factory for the layer and appContext, or null if no AuthConfigProvider is selected. An argument listener is attached even if the return value is null.

registerConfigProvider

public abstract String registerConfigProvider(String className,
                                              Map properties,
                                              String layer,
                                              String appContext,
                                              String description)

Registers within the factory and records within the factory's persistent declarative representation of provider registrations a provider of ServerAuthConfig and/or ClientAuthConfig objects for a message layer and application context identifier. This method typically constructs an instance of the provider before registering it with the factory. Factories may extend or modify the persisted registrations of existing provider instances, if those instances were registered with ClassName and properties arguments equivalent to those passed in the current call.

This method employs the two argument constructor required to be supported by every implementation of the AuthConfigProvider interface, and this method must pass a null value for the factory argument of the constructor. AuthConfigProviderImpl AuthConfigProviderImpl(Map properties, AuthConfigFactory factory).

At most one registration may exist within the factory for a given combination of message layer and appContext. Any pre-existing registration with identical values for layer and appContext is replaced by a subsequent registration. When replacement occurs, the registration identifier, layer, and appContext identifier remain unchanged, and the AuthConfigProvider (with initialization properties) and description are replaced.

Within the lifetime of its Java process, a factory must assign unique registration identifiers to registrations, and must never assign a previously used registration identifier to a registration whose message layer and or appContext identifier differ from the previous use.

Programmatic registrations performed by using this method must update (according to the replacement rules described above) the persistent declarative representation of provider registrations employed by the factory constructor.

When a SecurityManager is enabled, before loading the argument provider, and before making any changes to the factory, this method must confirm that the calling access control context has been granted the providerRegistrationSecurityPermission

Parameters:

className - The fully qualified name of an AuthConfigProvider implementation class (or null). Calling this method with a null value for this parameter shall cause getConfigProvider to return null when it is called with layer and appContext values for which the resulting registration is the best match.

properties - A Map object containing the initialization properties to be passed to the properties argument of the provider constructor. This argument may be null. When this argument is not null, all the values and keys occurring in the Map must be of type String.

layer - A String identifying the message layer for which the provider will be registered at the factory. A null value may be passed as an argument for this parameter, in which case the provider is registered at all layers.

appContext - A String value that may be used by a runtime to request a configuration object from this provider. A null value may be passed as an argument for this parameter, in which case the provider is registered for all configuration ids (at the indicated layers).

description - A text String describing the provider. This value may be null.

Returns:

A String identifier assigned by the factory to the provider registration, and that may be used to remove the registration from the factory.

Throws:

SecurityException - If the caller does not have permission to register a provider at the factory, or if the the provider construction (given a non-null className) or registration fails.

registerConfigProvider

public abstract String registerConfigProvider(AuthConfigProvider provider,
                                              String layer,
                                              String appContext,
                                              String description)

Registers within the (in-memory) factory, a provider of ServerAuthConfig and/or ClientAuthConfig objects for a message layer and application context identifier. This method does NOT effect the factory's persistent declarative representation of provider registrations, and is intended to be used by providers to perform self-Registration.

At most one registration may exist within the factory for a given combination of message layer and appContext. Any pre-existing registration with identical values for layer and appContext is replaced by a subsequent registration. When replacement occurs, the registration identifier, layer, and appContext identifier remain unchanged, and the AuthConfigProvider (with initialization properties) and description are replaced.

Within the lifetime of its Java process, a factory must assign unique registration identifiers to registrations, and must never assign a previously used registration identifier to a registration whose message layer and or appContext identifier differ from the previous use.

When a SecurityManager is enabled, and before making any changes to the factory, this method must confirm that the calling access control context has been granted the providerRegistrationSecurityPermission

Parameters:

provider - The AuthConfigProvider to be registered at the factory (or null). Calling this method with a null value for this parameter shall cause getConfigProvider to return null when it is called with layer and appContext values for which the resulting registration is the best match.

layer - A String identifying the message layer for which the provider will be registered at the factory. A null value may be passed as an argument for this parameter, in which case the provider is registered at all layers.

appContext - A String value that may be used by a runtime to request a configuration object from this provider. A null value may be passed as an argument for this parameter, in which case the provider is registered for all configuration ids (at the indicated layers).

description - A text String describing the provider. This value may be null.

Returns:

A String identifier assigned by the factory to the provider registration, and that may be used to remove the registration from the factory.

Throws:

SecurityException - If the caller does not have permission to register a provider at the factory, or if the provider registration fails.

removeRegistration

public abstract boolean removeRegistration(String registrationID)

Remove the identified provider registration from the factory (and from the persistent declarative representation of provider registrations, if appropriate) and invoke any listeners associated with the removed registration.

When a SecurityManager is enabled, and before making any changes to the factory, this method must confirm that the calling access control context has been granted the providerRegistrationSecurityPermission

Parameters:

registrationID - A String that identifies a provider registration at the factory

Returns:

True if there was a registration with the specified identifier and it was removed. Return false if the registrationID was invalid.

Throws:

SecurityException - If the caller does not have permission to unregister the provider at the factory.

detachListener

public abstract String[] detachListener(RegistrationListener listener,
                                        String layer,
                                        String appContext)

Disassociate the listener from all the provider registrations whose layer and appContext values are matched by the corresponding arguments to this method.

Factories should periodically notify Listeners to effectively detach listeners that are no longer in use.

When a SecurityManager is enabled, and before making any changes to the factory, this method must confirm that the calling access control context has been granted the providerRegistrationSecurityPermission

Parameters:

listener - The RegistrationListener to be detached.

layer - A String identifying the message layer or null.

appContext - A String value identifying the application context or null.

Returns:

An array of String values where each value identifies a provider registration from which the listener was removed. This method never returns null; it returns an empty array if the listener was not removed from any registrations.

Throws:

SecurityException - If the caller does not have permission to detach the listener from the factory.

getRegistrationIDs

public abstract String[] getRegistrationIDs(AuthConfigProvider provider)

Get the registration identifiers for all registrations of the provider instance at the factory.

Parameters:

provider - The AuthConfigurationProvider whose registration identifiers are to be returned. This argument may be null, in which case it indicates that the IDs of all active registrations within the factory are to be returned.

Returns:

An array of String values where each value identifies a provider registration at the factory. This method never returns null; it returns an empty array when there are no registrations at the factory for the identified provider.

getRegistrationContext

public abstract AuthConfigFactory.RegistrationContext getRegistrationContext(String registrationID)

Get the the registration context for the identified registration.

Parameters:

registrationID - A String that identifies a provider registration at the factory

Returns:

A RegistrationContext or null. When a Non-null value is returned, it is a copy of the registration context corresponding to the registration. Null is returned when the registration identifier does not correspond to an active registration

refresh

public abstract void refresh()

Cause the factory to reprocess its persistent declarative representation of provider registrations.

A factory should only replace an existing registration when a change of provider implementation class or initialization properties has occurred.

When a SecurityManager is enabled, and before the point where this method could have caused any changes to the factory, this method must confirm that the calling access control context has been granted the providerRegistrationSecurityPermission

Throws:

SecurityException - If the caller does not have permission to refresh the factory, or if an error occurred during the reinitialization.