Administrative 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 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. These plug-ins can be used with the ASI Authorization, ASI Role Mapping, Log4j Audit Channel, and Database Authentication providers.

While the out-of-box security providers 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:

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.

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

Authorization and Role Mapping Extensions

This product supports the use of Java-based plug-ins and language extensions with the out-of-box security providers such as ASIAuthorizer and ASIRoleMapper. You can use these plug-ins to augment authorization and role mapping processing logic.

The following sections describe plug-ins in detail:

Plug-in Types

Four types of Java-based plug-ins are supported: attribute retrievers, evaluation functions, resource converters, and attribute converters. These plug-ins can only be used with ASI Authorization and ASI Role Mapping providers.

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

Attribute Retrievers

Attribute retrievers are used by ASI Authorization and ASI Role Mapping providers to retrieve attributes for use during runtime evaluation of policy. The out-of-the-box attribute retrievers can be configured in the Administration Console (for the WLS SSM this must be done using the WebLogic console).

There is no need to create an attribute retriever to retrieve values from LDAP or a database store. Such retrievers can be directly configured via the ASIAuthorizer provider's Configuration tab in the Administration Console.

Custom Attribute Retrievers

Dynamic attributes are often used to write policy constraints. In such cases the value of the dynamic attribute can come either from the application context or from an external source. If the external source is not a database store or LDAP, you must write a custom attribute retriever.

Examples:

AttributeRetriever is an interface in the com.bea.security.providers.authorization package that you can use to implement plug-ins for retrieving attributes.

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 7-1 lists and describes the methods provided by the AttributeRetrieverV2 interface.

RequestHandle.getAttribute() Method

The com.bea.security.providers.authorization.asi.ARME.evaluator.RequestHandle object has the getAttribute() and appendReturnData() methods. These 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. This method gets the named attribute and its value, and optionally type-checks the value. It returns the attribute name and value as a com.wles.util.AttributeElement object. For example if your attribute retriever needed to make an HTTP request to obtain the stock quote, then the application context can contain the URL of the stock quote service and you would use getAttribute() to obtain this value. This function will also help in obtaining the value of all the runtime system attributes (sys_*) such as sys_dir, sys_app_q etc. Please refer to the Advanced Topics section in the Policy Managers Guide for a full list of system attributes.

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

try { 
AttributeElement attrElement = requestHandle.getAttribute("sys_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;
}

The AttributeRetrieverV2 implementation can use the RequestHandle.getAttribute() method to get the value for user and resource attributes. However, when this method is used to get values of dynamic attributes that may be handled by other Attribute Retrievers (including built-in database and LDAP), it is possible that the ASIAuthorizer may or may not have computed it yet when the custom AttrbuteRetriever was called. In order to make sure that required attributes are present, always list them before the attribute in the policy constraint via the use of sys_defined(<attr>) function. For example, the attribute retriever depends on the URL attribute being present in the RequestHandle. If this attribute is also computed by another attribute retriever, instead of being passed in as an application context, then the rule constraint would have to look something like this: IF sys_defined(URL) and BEAS_quote >= 19;

RequestHandle.getAttribute() and RequestHandle.appendReturnData() are also applicable to Evaluation functions, which are described in the next section.

ASI providers always evaluate the minimum number of required policies and attributes are retrieved only when a policy that references them is evaluated. Therefore, not all attribute retrievers are guaranteed to be called for all policy evaluations. OES attributes retrievers are not called unless the policy has been explicitly evaluated and the attribute can not be obtained from the application context or is not an associated user attribute.

Configuring a Custom Attribute Retriever

To configure a custom attribute retriever, perform the following steps:

Configuring Caching for Custom Attributes

Caching options can be specified for all attribute values returned by a custom attribute retriever. To set these options, select the Custom Attribute Retriever’s Cache All Attributes checkbox and specify how long the values should be cached in the Cache All Attributes TLL field.

It is also possible to specify a caching requirement for individual attributes. When this is done, the caching parameters take precedence over those defined for the custom attribute retriever.

To specify a caching requirement for an attribute, perform the following steps:

Evaluation Functions

You can use a named evaluation function to augment built-in authorization and role mapping logic. This method is invoked when 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.

A custom evaluation function is implemented as a method in a class that should also implement init() and shutdown() methods. This class may contain one or more custom evaluation functions. You can choose any name for custom evaluation function so long as the corresponding method name matches the name that is used in a policy. Custom evaluation functions can be passed arguments consisting of constants or names of other attributes, including dynamic attributes.

Custom Initialization/Shutdown Interface

This section describes the interface for writing custom evaluation functions.

The com.bea.security.providers.authorization.asi.InitializationShutdownFunction interface can be used to implement custom initialization and/or shutdown steps that are specific to your evaluation functions.

The init() method is invoked during the Authorization or Role Mapping provider initialization and can be used to initialize some plug-in specific data, such as a connection pool. The shutdown() method is invoked during the Authorization or Role Mapping provider shutdown and can be used to free data allocated in the "init()" method.

When the init() method is called, it is passed all configuration parameters for Authorization provider or Role Mapping provider. For the complete list of available parameters, see javadocs for InitializationShutdownFunction.

Table 7-2 lists and describes the methods provided by the InitializationShutdownFunction interface required to implement an Evaluation Function.

RequestHandle.appendReturnData() Method

The RequestHandle.appendReturnData() method can be used to create a named response attribute with a specified value. It is equivalent to using the report_as() function from inside a custom evaluation function.

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

RequestHandle.getAttribute() Method

When the evaluation function is called, the runtime system passes in the literal string as an argument to the function as part args[0]. To obtain the value of the attribute passed in, make use of the RequestHandle.getAttribute() method. This method gets the named attribute and its value, and optionally type-checks the value. It 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.

The following code fragment provides an example.

try {
AttributeElement strLength = requestHandle.getAttribute((String)args[0], true);
if(strLength != null) {
if(strLength.isList()) {
// string_longer_then: first argument not a single value
return false;
} 
intCompLength = Integer.parseInt((String)strLength.getValueAs(String.class));

} else {
// numerical constant will be passed in as is. 
try {
intCompLength = Integer.parseInt((String)args[0]);
} catch(NumberFormatException ne) {
//value format is an error, and there is no attribute in the requestHandle.
throw new MissingAttributeException("missing attribute: " + args[0], (String)args[0]);
}
}
} catch(Exception e) {
//caught exception while getting attribute
throw new RuntimeException("failed while getting attribute: " + (String)args[0] + ". Exception: " + e.getMessage());
}

It is also possible to use dynamic attributes as arguments to an evaluation function such that the dynamic attribute is handled by a Custom Attribute Retrievers. When the evaluation function calls requestHandle.getAttribute((String)args[0], true), the value will be returned after the custom attribute retriever is called.

Configuring a Custom Evaluation Function

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

Resource Converters

Resource converters are used by ASI Authorization and ASI Role Mapping providers to convert application-specific resources to an internal OES resource format that is recognized. Out-of-box resource types will convert WLS-style and OES-style resource types.

To add support for additional resource types, define a resource converter to allow the ASI Authorization provider to protect the new resource types. ResourceConverter is an interface in the com.bea.security.providers.authorization.asi package.

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

Configuring a Custom Resource Converter

To configure a custom resource converter, 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 Converters

Attribute converters are used by ASI Authorization and ASI Role Mapping providers to convert Java attribute types to the internal attribute types, and vice versa. Out-of-box attribute converters that convert between Java and internal types are provided. For a list of supported attribute types, see the Attribute Declarations in the Policy Managers guide.

To add new attribute types, implement a TypeConverter interface to handle the conversion. Attribute types are the also called ‘credential’ types. They are listed in the Administration Console integer, date, string etc. These are Java equivalents, but are represented as internal attribute types.

TypeConverter is an interface in the com.wles.util package.

Table 7-5 lists and describes 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:

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 7-6 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 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 want to implement a 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 7-7.

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

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

The options object is a map containing optional information for use by the plug-in. The most common options and keys for retrieval are: