javax.security.auth.message.config.AuthConfigProvider Maven / Gradle / Ivy
Show all versions of jboss-jaspi-api_1.0_spec Show documentation
package javax.security.auth.message.config;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.message.AuthException;
//$Id$
/**
* 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.
*
* - AuthConfigProvider provider;
* - ClientAuthConfig config = provider.getClientAuthConfig(layer,appID,cbh);
* - String operation = config.getOperation(authParam);
* - ClientAuthContext context = config.getAuthContext(operation,properties);
* - 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.
* @author Anil Saldhana
* @author Charlie Lai, Ron Monzillo (Javadoc for JSR-196)
* @since May 12, 2006
* @version $Revision$
*/
public interface AuthConfigProvider
{
/**
* 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.
*
* @param layer a String identifying the message layer for the returned
* ClientAuthConfig object.
* @param appContext a String that identifies the messaging context for the
* returned ClientAuthConfig object.
* @param 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.
* @return 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.
* @throws SecurityException if the caller does not have permission to retrieve
* the configuration.
*/
ClientAuthConfig getClientAuthConfig( 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.
*
* @param layer a String identifying the message layer for the returned
* ServerAuthConfig object.
* @param appContext a String that identifies the messaging context for the
* returned ServerAuthConfig object.
* @param 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.
* @return 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.
* @throws SecurityException if the caller does not have permission to retrieve
* the configuration.
*/
ServerAuthConfig getServerAuthConfig( String layer, String appContext,
CallbackHandler handler) throws AuthException, SecurityException;
/**
* 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.
* @throws SecurityException if the caller does not have permission to
* refresh the provider.
*/
void refresh();
}