Administration Reference

Provider Extensions

The following topics are covered in this section:

What is a Provider Extension?

A provider extension is a plug-in function that you write to extend the capabilities of the existing providers. You can use these plug-ins to manipulate existing policy data in a way that is not already provided, or to retrieve data from external sources to add to an authorization or role mapping decision or a deployment audit. You can use these plug-ins with the ASI Authorization, ASI Role Mapping, Log4j Audit Channel, and Database Authentication providers.

While the security providers supplied with AquaLogic Enterprise Security are configurable, the plug-ins enable you to customize them to add additional functionality. For example, you may want some form of special business logic to retrieve additional data that you want to use before the authorization decision is made or for the custom processing of data, such as the audit context. Plug-ins are provided for a variety of functions:

The following sections provide more information on the plug-ins and how to use them.

asi_classes JAR Required for Provider Extensions

The asi_classes.jar (located in SSM/lib) contains classes required for provider extensions. That is, in order to implement provider extensions you need classes in asi_classes.jar.

Authorization and Role Mapping Extensions

AquaLogic Enterprise Security supports using Java-based plug-ins and language extensions with security providers. You can use these plug-ins to performed custom functions for authorization and role mapping.

The following types of plug-ins are supported:

Using Java-Based Plug-ins

AquaLogic Enterprise Security providers support three types of Java-based plug-ins: resource converters, attribute retrievers, and attribute converters. Table 4-1 shows the types of Java-based plug-ins that each security provider supports.

To use these plug-ins, you must perform the following tasks:

For instructions for performing these tasks, refer to the following sections:

Using the Java-based Plug-in Interfaces

To implement a Java-based plug-in interface, you must perform the following steps:

Resource Converter

Resource converters are used by ASI Authorization and ASI Role Mapping providers to convert WebLogic Server resources into an internal resource format that is recognized by AquaLogic Enterprise Security. For a description of the policy data formats, see the BEA AquaLogic Enterprise Security Policy Managers Guide.

ResourceConverter is an interface in the com.bea.security.providers.authorization.asi package. This interface is used to implement plug-ins for converting from the Security Framework defined resource interface into an access query. There is no standard for resource definitions so plug-ins are needed to handle each of the resource types. The set of resource types is not fixed and you can define your own resource, in which case, you need to define a resource converter to allow the ASI Authorization provider to protect the resource. Numerous resource converters are supplied for your use, one for each defined WebLogic Server and AquaLogic Enterprise Resource type. Table 4-2 lists and describes the methods provided by the ResourceConverter interface.

Configuring a Custom Resource Converter

To configure a custom resource converter, you must implement the resource converter and register it with the configured ASI Authorization and ASI Role Mapping providers.

To configure a resource converter, perform the following steps:

Attribute Retriever

Attribute retrievers are used by ASI Authorization and ASI Role Mapping providers to retrieve attributes for use by AquaLogic Enterprise Security authorization and role mapping. AttributeRetriever is an interface in the com.bea.security.providers.authorization package that you can use to implement plug-ins for retrieving attributes. You use an implementation of the AttributeRetriever interface to get embedded data from complex data objects. For example, if the ContextHandler includes an address element, you can use an attribute retriever to make the zip code portion of the address available separately. You can also use an attribute retriever to fetch data from external data sources, for example, JDBC data stores.

Version 2.5 of AquaLogic Enterprise Security includes a new version of the AttributeRetriever interface, AttributeRetrieverV2. The AttributeRetrieverV2 interface includes an additional RequestHandle parameter.

You can register multiple attribute retrievers with the same attribute name. If you do so, the attribute retrievers are called in order until one of them returns a non-null result.

Table 4-3 lists and describes the methods provided by the AttributeRetriever interface.

Table 4-4lists and describes the methods provided by the AttributeRetrieverV2 interface.

RequestHandle getAttribute Method

The com.bea.security.providers.authorization.asi.ARME.evaluator.RequestHandle interface, which is implemented for you and passed to your AttributeRetrieverV2 implementation, has two methods, getAttribute() and appendReturnData(), which are defined as follows:

public AttributeElement getAttribute(String name, boolean typeCheck)
throws ArmeRuntimeException, BadParameterException, CredvarException,BoolEvalInternalException, NotReadyException;

public void appendReturnData(String name, Object data);
}

Of the two methods, the RequestHandle.getAttribute() is of most interest to AttributeRetrieverV2 implementations. The RequestHandle.getAttribute() method gets the named attribute and its value, and optionally type-checks the value. The getAttribute() method returns the attribute name and value as a com.wles.util.AttributeElement object.

The AttributeElement object represents an attribute name/value pair for a single element or a list. In the case of a list, your AttributeRetrieverV2 code might then transfer the AttributeElement list value to a list of String-type objects, such as in the following code fragment from the AttributeRetrieverV2 example:

try {

            AttributeElement attrElement = requestHandle.getAttribute("asi_subjectgroups", true);

            Object value = null;

            //It must be a list attribute

            if(!attrElement.isList()) {

                return null;

            }

            //transfer AttributeElement value to a list of String type object.

            List subjectGroupList = (List)attrElement.getValueAs(String.class);

            value = String.valueOf(subjectGroupList.size());

            return value;

        } catch(Exception e) {

            //failed to retrieve attributes.

            return null;

        }

Your AttributeRetrieverV2 implementation can use the RequestHandle.getAttribute() method to get the value for user and resource attributes. However, it should not rely on the RequestHandle.getAttribute() method to get values of dynamic or extension attributes, as they may or may not be computed for a particular request.

The ASI providers always evaluate the minimum number of policies that are logically required, and attributes are retrieved only when a policy that references them is evaluated. Therefore, some attribute values will not be available. AttributeRetrieverV2 will not get the attribute value unless the policy has been explicitly evaluated.

Configuring a Custom Attribute Retriever

To configure a custom attribute retriever, you must implement the attribute retriever, and then register it with the configured ASI Authorization and ASI Role Mapping providers.

To configure an attribute retriever, perform the following steps:

Attribute Converter

Attribute converters are used by ASI Authorization and ASI Role Mapping providers to convert context data to an internal attribute format. For a description of the policy data formats, see the BEA AquaLogic Enterprise Security Policy Managers Guide.

To create attribute converters, you implement the TypeConverter interface. This interface converts between native Java types and ASI formatted Strings. If you create a new ASI type, you may want to create a Java class to handle it and implement a TypeConverter interface to handle that class. ASI types are the credential types that are visible through the console such as integer, date, and string types, and so on, versus Java data types.

Table 4-5 lists and describes methods provided by the TypeConverter interface.

Configuring a Custom Attribute Converter

To configure a custom attribute converter, you must implement the attribute converter and register it with the configured ASI Authorization and ASI Role Mapping providers.

To configure an attribute converter, perform the following steps:

Using Java Entensions Plug-Ins

You can use Java extensions plug-ins to add your own custom initialization, shutdown, and authorization and role mapping evaluation functions to the standard ones provided. After you develop a function, administrators can manipulate its input using the Administration Console. The plug-in appears to the administrator simply as new evaluation functions or newly available dynamic attributes.

This section describes the Application Programming Interface (API) for writing custom extension functions to enhance features available through the policy language.

Custom Initialization/Shutdown Interface

You can implement the com.bea.security.providers.authorization.asi.InitializationShutdownFunction interface to add initialization and shutdown functions for your plug-in.

The init() method is invoked during the Authorization or Role Mapping provider initialization and initializes attributes for the provider. For example, it might open a database connection pool. The shutdown() method is invoked during the Authorization or Role Mapping provider shutdown and might then close the connections to the pool.

The InitializationShutdownFunction interface includes a key map of constants and attributes primarily supported by the AsiAuthorizer security provider. A portion of this key map is shown in Listing 4-1.

/**

     * map key for get ATZ provider or RM provider's version info.

     */

    public static final String VERSION = "Version";

    /**

     * map key for get ATZ provider or RM provider's description info.

     */

    public static final String DESCRIPTION = "Description";

    /**

     * map key for get ATZ provider or RM provider's class name.

     */

    public static final String PROVIDER_CLASSNAME = "ProviderClassName";

    /**

     * map key for get advanced configuration properties for ATZ provider or RM provider. The corresoponding value in map is <code>Properties<code>.

     */

    public static final String ADVANCED_CONFIGURATION_PROPERTIES = "AdvancedConfigurationProperties";

    /**

     * map key for get ATZ provider or RM provider's directory.

     */

    public static final String DIRECTORY = "Directory";

    /**

     * map key for get configuration for preload attributes.

     */

    public static final String PRELOAD_ATTRIBUTES = "PreLoadAttributes";

    /**

     * map key for get configuration for session eviction capacity.

     */

    public static final String SESSION_EVICTION_CAPACITY = "SessionEvictionCapacity";
:
:

The attributes are described in the BLM Configuration API Security Providers Reference. You use this key map to get initialization parameters for the plug-in.

Listing 4-2 shows the init() function from the BEA_HOME\ales25-ssm\java-ssm\examples\MyEvaluationFunction example.

/**

public void init(Map config) {

        // Initialization function executed.

        // Samples to get value from Map.

        //get advanced configuration properties

        Properties advanced = (Properties)config.get(ADVANCED_CONFIGURATION_PROPERTIES);

        //get all configured evaluation function class names.

        String[] evalFunctions = (String[])config.get(EVALUATION_FUNCTIONS);

        String ifActivateOnStartUp = config.get(ACTIVATE_ON_STARTUP).toString();

        return;

    }

Custom Evaluation Method Plug-in

You can use a named evaluation method to make additional authorization request data available, and therefore allow a more complex attribute evaluation to be performed. This method is invoked while the policy contains a custom evaluation function with a matching name. For example:

grant(any, //app/policy/ASI, //user/asi/test/) if myFunc(name);

where myFunc() is the custom evaluation function name. You must register one evaluation class that includes the myFunc() method.

You can use whatever name you want, but the name must exactly match the name you supply in the policy, and the method must have exactly these arguments:

public boolean some_method_name(RequestHandle requestHandle,

            Object[] args,

            Subject subject,

            Map roles,

            Resource resource,

            ContextHandler contextHandler)

Table 4-6 contains a description of the evaluation method arguments.

RequestHandle appendReturnData Method

The RequestHandle.appendReturnData() method appends the evaluation result to an object so that it can be retrieved after atzSvc.isAccessAllowed() is invoked.

You pass in an Object containing the evaluation result. The appendReturnData()method converts the Object to a suitable ASI type, and then appends it to a com.bea.security.providers.authorization.asi.ARME.engine.EvalResultI object. You can access this result after the atzSvc.isAccessAllowed() method is invoked. The QueryResources example (BEA_HOME\ales22-ssm\java-ssm\examples\QueryResources) shows how to access the returned data.

If the same attribute value is redefined by another plug-in within the same policy, the result value is overwritten.

The evaluation result (the appended data) is returned only if the complete rule condition result is true. That is, the evaluation result is returned only if the policy successfully executes.

For example, if the rule condition includes two evaluation functions, both func1(arg1) and func2(arg2) can invoke appendReturnData, but the data is not available unless both functions evaluate to true. As a programming practice, do not call appendReturnData unless your evaluation result is true.

The policy might not execute if another policy makes evaluating it superfluous. For example, once a user is explicitly denied access with a deny policy, a thousand grant policies cannot undo the one deny. Knowing this, as soon as a single grant policy for an access attempt is found, BEA AquaLogic Enterprise Security looks only for deny policies. When a single deny policy is found, it stops looking.

Configuring a Custom Entensions Plug-In

To configure a custom extensions plug-in, you must implement the extensions plug-in, and then register it with the configured ASI Authorization and ASI Role Mapping providers.

To configure a custom extensions plug-in, perform the following steps:

Custom Audit Plug-ins

The Log4j Audit Channel provider uses Log4j renderer classes that convert the associated audit event object into a simple string representation. However, you can write custom renderers that convert the audit event object to something other than the default string representation and register them as plug-ins using the Administration Console.

Refer to the following topics for information how to write and register custom audit plug-ins:

Using the Custom Audit Plug-in

To implement an audit plug-in interface, you must perform the following steps:

Audit Plug-in Renderer Class

To write a plug-in renderer class, you must implement the org.apache.log4j.or.ObjectRenderer interface and then register the renderer class to the type of Audit Event class for which you want to use that renderer. For example, weblogic.security.spi.MyAuditEvent=com.bea.security.providers.
audit.MyAuditEventRenderer

For instructions on how to write a renderer for a custom object, see the Log4j documentation located at http://logging.apache.org/log4j/docs/documentation.html.

Table 4-7 lists and describes a sample AuditEventRenderer class.

Database Authentication Plug-in

The Database Authentication extension is used by the Database Authentication provider to customize authentication features. The default database authentication extension (located in the com.bea.security.providers.authentication.dbms.DefaultDBMSPluginImpl package) is designed to authenticate the user against the policy database. This implementation uses a specific password hashing algorithm, namely, SHA1 and SHA-1. It also uses a special format for the user name and the group name that is pertinent to the policy database. The hashing algorithm used is:

{Algorithm} + 4 byte Salt+passwordhash

The policy database uses name scope (for example, directory name) and a qualified name format to store the user and group. See the BEA AquaLogic Enterprise Security Policy Managers Guide for details.

If you are authenticating users against another database that uses a different password hashing algorithm and a different user/group name format, you may decide to implement your own plug-in by following the guidelines provided with the plug-in.

A custom database authentication plug-in must also extend the DBMSPlugin abstract class (located in the com.bea.security.providers.authentication.dbms.DBMSPlugin package). The DBMSPlugin abstract class implementation must include the methods described in Table 4-8.

To use your plug-in implementation, you need to deploy the plug-in class (or its JAR file) in the classpath of the Database Authentication provider (/lib/providers or, if you are using the WebLogic Server 9.x SSM, /lib/providers/wls/v9) and use the WebLogic Server Administration Console (if you are using the WebLogic Server 9.x SSM) or the ALES Administration Console (for other SSMs) to configure the Database Authentication provider to use the plug-in.

Table 4-8 lists and describes the methods provided by the DBMSPlugin abstract class.

The options object is a map containing optional information that the plug-in may want to use. The most common options of use and their keys for retrieval are: