jakarta.security.auth.message.config.AuthConfigProvider Maven / Gradle / Ivy

Go to download
/*
 * Copyright (c) 1997, 2020 Oracle and/or its affiliates and others.
 * All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0, which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the
 * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
 * version 2 with the GNU Classpath Exception, which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 */

package jakarta.security.auth.message.config;

import javax.security.auth.callback.CallbackHandler;

import jakarta.security.auth.message.AuthException;

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

 * Authentication context objects encapsulate the initialization, configuration, and invocation of authentication
 * modules, that is, 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 authContextID = config.getAuthContextID(messageInfo);
 *   
ClientAuthContext context = config.getAuthContext(authContextID,subject,properties);
 *   
context.secureRequest(messageInfo,subject);
 * 
 *
 * 
 * Every implementation of this interface must offer a public, two argument constructor with the following signature:
 * 
 * 
 * 
 * public AuthConfigProviderImpl(Map properties, AuthConfigFactory factory);
 * 
 * 
 * 
 * where the properties argument may be null, and where all values and keys occurring in a non-null properties argument
 * must be of type String. When the factory argument is not null, it indicates that the provider is to self-register at
 * the factory by calling the following method on the factory:
 * 
 *  * 
 * public String 
 * registerConfigProvider(AuthConfigProvider provider, String layer, String appContext, String description);
 * 
 * 
 *
 * @see ClientAuthContext
 * @see ServerAuthContext
 * @see AuthConfigFactory
 */
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. This argument must not
     * be null.
     *
     * @param appContext A String that identifies the messaging context for the returned ClientAuthConfig object. This
     * argument must not be null.
     *
     * @param handler A CallbackHandler to be passed to the ClientAuthModules encapsulated by ClientAuthContext objects
     * derived from the returned ClientAuthConfig. This argument may be null, in which case the implementation may assign a
     * default handler to the configuration. The CallbackHandler assigned to the configuration must support the Callback
     * objects required to be supported by the profile of this specification being followed by the messaging runtime. The
     * CallbackHandler instance must be initialized with any application context needed to process the required callbacks on
     * behalf of the corresponding application.
     *
     * @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.
     *
     * @exception AuthException If this provider does not support the assignment of a default CallbackHandler to the
     * returned ClientAuthConfig.
     *
     * @exception SecurityException If the caller does not have permission to retrieve the configuration.
     */
    ClientAuthConfig getClientAuthConfig(String layer, String appContext, CallbackHandler handler) throws AuthException;

    /**
     * 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 a particular application context.
     *
     * @param layer A String identifying the message layer for the returned ServerAuthConfig object. This argument must not
     * be null.
     *
     * @param appContext A String that identifies the messaging context for the returned ServerAuthConfig object. This
     * argument must not be null.
     *
     * @param handler A CallbackHandler to be passed to the ServerAuthModules encapsulated by ServerAuthContext objects
     * derived from the returned ServerAuthConfig. This argument may be null, in which case the implementation may assign a
     * default handler to the configuration. The CallbackHandler assigned to the configuration must support the Callback
     * objects required to be supported by the profile of this specification being followed by the messaging runtime. The
     * CallbackHandler instance must be initialized with any application context needed to process the required callbacks on
     * behalf of the corresponding application.
     *
     * @return A ServerAuthConfig Object that describes the configuration of ServerAuthModules at a given message layer, and
     * for a particular application context. This method does not return null.
     *
     * @exception AuthException If this provider does not support the assignment of a default CallbackHandler to the
     * returned ServerAuthConfig.
     *
     * @exception SecurityException If the caller does not have permission to retrieve the configuration.
     */
    ServerAuthConfig getServerAuthConfig(String layer, String appContext, CallbackHandler handler) throws AuthException;

    /**
     * Causes a dynamic configuration provider to update its internal state such that any resulting change to its state is
     * reflected in the corresponding authentication context configuration objects previously created by the provider within
     * the current process context.
     *
     * @exception SecurityException If the caller does not have permission to refresh the provider, or if an error occurred
     * during the refresh.
     */
    void refresh();

}