javax.security.auth.message.config

Interface AuthConfigProvider

public interface AuthConfigProvider

This interface is implemented by objects that can be used to obtain authentication context configuration objects i.e., ClientAuthConfig or ServerAuthConfig objects. Authentication context configuration objects serve as sources of the authentication context objects, i.e, ClientAuthContext or ServerAuthContext objects, for a specific message layer and messaging context.

Authentication context objects encapsulate the initialization, configuration, and invocation of authentication modules, i.e., ClientAuthModule or ServerAuthModule objects, for a specific message exchange within a specific message layer and messaging context.

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

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

1. AuthConfigProvider provider;
2. ClientAuthConfig config = provider.getClientAuthConfig(layer,appID,cbh);
3. String operation = config.getOperation(authParam);
4. ClientAuthContext context = config.getAuthContext(operation,properties);
5. context.secureRequest(authParam,subject,...);

Every implementation of this interface must offer a public, single argument constructor with the following signature:

 public AuthConfigProviderImpl(Map properties);

where the properties argument may be null, and where all values and keys occuring in a non-null properties argument must be of type String.

An AuthConfigFactory may be used to obtain the ConfigProvider for a specific message layer and application context identifier.

Since:

May 12, 2006

Version:

$Revision$

Author:

Anil Saldhana, Charlie Lai, Ron Monzillo (Javadoc for JSR-196)

Method Summary

Methods

Modifier and Type	Method and Description
ClientAuthConfig	getClientAuthConfig(String layer, String appContext, CallbackHandler handler) Get an instance of ClientAuthConfig from this provider.
ServerAuthConfig	getServerAuthConfig(String layer, String appContext, CallbackHandler handler) Get an instance of ServerAuthConfig from this provider.
void	refresh() Causes a dynamic configuration provider to update its internal state such that any resulting change to its state is recognized by authentication context configuration objects previously created by the provider within the current process context.

Method Detail

getClientAuthConfig

ClientAuthConfig getClientAuthConfig(String layer,
                                   String appContext,
                                   CallbackHandler handler)
                                     throws AuthException,
                                            SecurityException

Get an instance of ClientAuthConfig from this provider. The implementation of this method returns a ClientAuthConfig instance that describes the configuration of ClientAuthModules at a given message layer, and for use in an identified application context.

Parameters:

layer - a String identifying the message layer for the returned ClientAuthConfig object.

appContext - a String that identifies the messaging context for the returned ClientAuthConfig object.

handler - a CallbackHandler to be passed to the ClientAuthModules encapsulated by ClientAuthContext objects derived from the returned ClientAuthConfig. This parameter may be null, in which case the implementation may assign a default handler to the configuration. The authconfigprovider.client.callbackhandler security property is used to define the fully qualified name of the default CallbackHandler implementation class.

Returns:

a ClientAuthConfig Object that describes the configuration of ClientAuthModules at the message layer and messaging context identified by the layer and appContext arguments. This method does not return null.

Throws:

AuthException - if this factory does not support the assignment of a default CallbackHandler to the returned ClientAuthConfig.

SecurityException - if the caller does not have permission to retrieve the configuration.

getServerAuthConfig

ServerAuthConfig getServerAuthConfig(String layer,
                                   String appContext,
                                   CallbackHandler handler)
                                     throws AuthException,
                                            SecurityException

Get an instance of ServerAuthConfig from this provider. The implementation of this method returns a ServerAuthConfig instance that describes the configuration of ServerAuthModules at a given message layer, and for use in an identified application context.

Parameters:

layer - a String identifying the message layer for the returned ServerAuthConfig object.

appContext - a String that identifies the messaging context for the returned ServerAuthConfig object.

handler - a CallbackHandler to be passed to the ServerAuthModules encapsulated by ServerAuthContext objects derived from the returned ServerAuthConfig. This parameter may be null, in which case the implementation may assign a default handler to the configuration. The authconfigprovider.client.callbackhandler security property is used to define the fully qualified name of the default CallbackHandler implementation class.

Returns:

a ServerAuthConfig Object that describes the configuration of ServerAuthModules at the message layer and messaging context identified by the layer and appContext arguments. This method does not return null.

Throws:

AuthException - if this factory does not support the assignment of a default CallbackHandler to the returned ServerAuthConfig.

SecurityException - if the caller does not have permission to retrieve the configuration.

refresh

void refresh()

Causes a dynamic configuration provider to update its internal state such that any resulting change to its state is recognized by authentication context configuration objects previously created by the provider within the current process context.

The effect on the authentication context configuration objects should be extended to the authentication context objects obtained from the configuration objects, such that the context objects recognize changes in the state of the configuration object from which they were obtained.

Throws:

AuthException - if an error occured during the refresh.

SecurityException - if the caller does not have permission to refresh the provider.