Skip navigation.
Downloads | Product Documentation | Support

Administration Reference

# Provider Extensions

The following topics are covered in this section:

- What is a Provider Extension?
- Authorization and Role Mapping Extensions
- Custom Audit Plug-ins
- Database Authentication Plug-in
- Configuring a Custom Attribute Retriever

# 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, Resource Deployment Audit, 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:

- You can use Java-based plug-ins to perform attribute retrieval, attribute conversion, and resource conversion. You can use attribute retrievers to retrieve embedded data from complex data objects or external data sources. You can use resource converters to convert WebLogic Server and AquaLogic Enterprise Security data to an internal resource format. You can use attribute converters to convert context data to an internal attribute format.
- You can use C++ language extensions plug-ins to add your own custom 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 as simply new evaluation functions or newly available dynamic attributes.
- You can use the audit plug-ins to help format audit events that are generated by the Security Framework, the runtime API, or custom implementations.
- You can use the database authentication plug-in with the Database Authentication provider to customize authentication features.

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

- Authorization and Role Mapping Extensions
- Custom Audit Plug-ins
- Database Authentication Plug-in

# 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, role mapping, and resource deployment auditing.

The following types of plug-ins are supported:

- Using Java-Based Plug-ins
- Using Language Extensions

## 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 1-1 shows the types of Java-based plug-ins that each security provider supports.

Table 1-1 Java-based Plug-in Support for Security Providers

Security Provider | Supports Resource Converter Plug-in | Supports Attribute Retrievers Plug-in | Supports Attribute Converter Plug-in
--- | --- | --- | ---
ASI Authorization provider | Yes | Yes | Yes
Resource Deployment Audit provider | Yes | No | Yes
ASI Role Mapping provider | Yes | Yes | Yes

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

1. Write a Java class that implements the plug-in interface.
2. Place the Java class in the appropriate directory of the Security Service Module with which you intend to use the plug-in. A single Java class may be used with more than one Security Service Module.
3. Use the Administration Console to register the Java class on the desired Security Service Module(s).

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

- Using the Java-based Plug-in Interfaces
- Resource Converter
- Attribute Retriever
- Attribute Converter

## Using the Java-based Plug-in Interfaces

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

1. Refer to the description of the plug-in interface you want to use and write a Java class to implement the interface. The following sections provide descriptions of each type of plug-in interface:

- Resource Converter
- Attribute Converter
- Attribute Retriever

2. Use the Java class to create a JAR file and place the JAR file in the `/lib/providers` directory in the installation directory for the Security Service Module on the machine on which the Security Service Module is installed. For example, the default location of this directory for the WebLogic Server 8.1 Security Service Module is `C:\bea\ales21-ssm\wls-ssm\lib\providers`.
3. Refer to the following topics in the Console Help and use the Administration Console to register the Java plug-ins in the desired security providers for the desired Security Service Modules:

- Cofiguring an ASI Authorization Provider
- Configuring an ASI Role Mapping Provider

## Resource Converter

Resource converters are used by ASI Authorization, ASI Role Mapping, and Resource Deployment Audit 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 1-2 lists and describes the methods provided by the `ResourceConverter` interface.

Table 1-2 ResourceConverter Interface Methods

Method | Description
--- | ---
`String[] getHandledTypes()` | This method is called when the plug-in is instantiated and is used to determine what resource types the converter knows how to handle. The Security Framework represents resource types internally as strings.
`AccessElement convertResource(Resource resource,ContextHandler contextHandler) throws ResourceConversion Exception` | This method extracts enough information from a `Resource` and `ContextHandler` to form an access query. The minimum amount of required information to be extracted is the resource object and privilege. Additional information that can be included is the application name and input attributes extracted from the Resource or `ContextHander`: If the application is not specified, then the provider uses the following rules for selecting one: If no application is specified, then the object is queried under the shared resource node as specified in the provider configuration. If an unqualified application is specified, the object is queried under the default deployment node, plus the application, plus the object. If a fully qualified application is specified, then the object is queried under that node. If the resource converter is unable to generate an access query from the information provided in the `Resource`, it throws a ResourceConversionException indicating to the provider and framework that this query cannot be answered by this provider.
`Object getAttributeValue (Resource resource, String name,ContextHandler contextHandler)` | This method finds the value of a missing attribute. It is left up to you as the developer of the ResourceConverter plug-in to determine how the `ResourceConverter` gets the required value. The plug-in may return null if the value is not found.

## 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.

Note: It is generally not necessary to write attribute retrievers for objects that appear directly in the `ContextHandler`; attribute retrievers are used to extract embedded or otherwise inaccessible data.

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

Table 1-3 AttributeRetriever Interface Methods

Method | Description
--- | ---
`String[] getHandledAttributeNames()` | This method returns the names of attributes handled by this object. An empty or `null` value indicates that the retriever is considered capable of handling any attribute name.
`Object getAttributeValue( String name, Subject subject, Map roles, Resource resource, ContextHandler contextHandler)` | This method retrieves the value of the named attribute. Additional authorization request data is made available to allow for more complex attribute retrieval. The parameters are as follows: name—name of the needed attribute subject—subject associated with the request roles—role membership of the subject, or `null` if this is a role mapping call resource—resource associated with the request contextHandler—context associated with the request; may be `null` if non-existent This method returns the attribute value, or `null` if the attribute is not found.

## Attribute Converter

Attribute converters are used by ASI Authorization, ASI Role Mapping, and Resource Deployment Audit 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 1-4 lists and describes methods provided by the `TypeConverter` interface.

Table 1-4 TypeConverter Interface Methods

Method | Description
--- | ---
`Class getType()` | This method returns the type which this converter converts.
String getASITypeName() | This method returns the ASI type name.
`String convertToASI(Object javaFormat) throws UnsupportedTypeException` | This method converts a java object into a ASI string.
Object convertFromASI(String asiFormat) throws TypeConversionException | This method converts a ASI string to a Java Object.

## Using Language Extensions

The ASI Authorization and ASI Role Mapping providers support the use of C++ plug-ins for custom rule extensions for evaluation and credential functions. The functions available for use are described in Policy Language Custom Extension Library API Reference.

This section contains a description of how to create an extension library for the ASI Authorization and ASI Role Mapper engine (ARME) used by the ASI Authorization provider. This example works with BEA AquaLogic Enterprise Security, Version 4.2.

The product installation includes an example of code and build commands for an extension library located in the `/examples` subdirectory in the Administration Application installation directory.

For instructions for building, deploying, and using extensions, see the following sections:

- Building an Extension
- Deploying the Extension
- Using the Extension

### Building an Extension

To build the extension library, you need to have the following header files, installed in the `asi` subdirectory:

- armeapi.h
- AttributeValue.h
- session.h
- defs.h
- exception.h

The extension needs to be linked with the following libraries, included with the ARME executable:

- utilmd.lib or libutil.so
- pluginmd.lib or libplugin.so

The compiler used must generate library binaries compatible with the compiler used to compile the ARME server.

- On Windows platform: Visual C++ 6.0 SP5
- On Linux Red Hat, AS 2.1 or 3.0: gcc 2.96
- On Solaris: Forte 7.0, or a binary compatible mode for later versions

### Deploying the Extension

To deploy the extension, do the following:

1. Place the compiled library (for example, `arme_extension.dll`) into the same path accessible by the ARME process.
2. Configure the initialization function in the ARME local configuration file, using the following syntax:

>     <ARME.tag>.plugin[1..4] <path>/<DLL plug_in filename>(initialize 'arg')

For example:

`ARME.alesadmin.plugin1 arme_extension.dll`(`initialize` '`test`')

This example assumes that the `arme_extension.dll` is in the path for the ARME process. In this example, `initialize` is the name of the routine in the extension library that is called when the library is loaded to perform initialization. <`ARME.tag`> is a parameter passed in the command line of the ARME process. This parameter defines the scope for the configuration parameters used from a local file. You may use an empty scope for these keywords; that is, just `plugin[1..4]`.

### Using the Extension

The extension library adds credential functions (custom dynamic attributes) and evaluation functions. To use them in your policy, you need to add declarations for them. For example, if an extension library defines the `custom-attribute` credential function, you need to add a declaration for a `custom-attribute` in the Administration Console with a dynamic type, and an appropriate data type (string, integer, and so on.). Then, you can use this attribute in policy constraints.

# 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
- Audit Plug-in Renderer Class

## Using the Custom Audit Plug-in

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

1. Refer to Audit Plug-in Renderer Class for a description of the audit plug-in renderer class and write a Java class to implement a new renderer class.
2. Use the Java class to create a JAR file and place the JAR file in the `/lib/providers` directory in the installation directory for the Security Service Module on the machine on which the Security Service Module is installed. For example, the default location of this directory for the WebLogic Server 8.1 Security Service Module is: `C:\bea\ales42-wls-ssm\lib\providers`.
3. For instructions on using the Administration Console to register the audit plug-in for the desired Log4j Audit Channel provider, refer to Configuring a Log4j Audit Channel Provider in the Console Help.

## 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 1-5 lists and describes a sample AuditEventRenderer class.

Table 1-5 AuditEventRenderer Class Method

Method | Description
--- | ---
`public class MyAuditAtnEventRenderer implements org.apache.log4j.or.ObjectRenderer {` `public String doRender(Object o) { String eventStr = null; if(o instanceof MyAuditEvent) { MyAuditEvent event = (MyAuditEvent) o; eventStr = event.getEventType()+" -- "+event.toString(); } return eventStr; } }` | In this sample, this method renders the AuditEvent object as a simple string. To render the Audit Event as something other than a simple string, modify this method to form your own string representation.

# 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 implement the `DBMSPlugin` Interface (located in the `com.bea.security.providers.authentication.dbms.DBMSPlugin` package). The `DBMSPlugin` Interface implementation must include the methods described in Table 1-6.

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 and use the Administration Console to configure the Database Authentication provider to use the plug-in.

Table 1-6 lists and describes the methods provided by `the DBMSPlugin` interface.

Table 1-6 DBMSPlugin Interface Methods

Method | Description
--- | ---
`public void initialize()` | This method is executed when the authorization provider is initialized on startup.
`public void shutdown()` | This method is executed when the authorization provider is shut down.
`public boolean authenticate( String user, char[] password, char[] databasePassword, Map options)` | When the Database Authentication provider attempts to authenticate a user, the authenticate method is called on the plug-in. This method may be called in one following two scenarios. If the provider is configured with the SQL Query to retrieve password, the password (`databasePassword`) is retrieved from the database using this query and is provided to this method. This authenticate method must determine if the user provides the correct password (password) and return true, if authenticated, or false. The options map contains a TRUE value for key = `"QueryPassword"`. If no SQL Query string is configured for retrieving the password, the Database Authentication provider assumes that the authentication plug-in retrieves the password and then authenticates the user. The options map contains values for these keys, "scope" and "connection", and a FALSE value for key = "QueryPassword". Also, databasePassword = null.
`public String formatUser(String user, Map options)` | This method is executed before any call to the database. The user string is the one passed into the login module. This method returns a formatted user name, which is later used as the input parameter in all the SQL queries to verify user, to retrieve password, and to retrieve groups. The options Map contains values for these keys, "scope" and "connection", and the configured string of the SQL query to verify user with key = "SQL_QUERY".
`public Vector formatGroups(String user, Vector groups, Map options)` | This method is executed after the call to retrieve groups from the database. A vector of strings containing the groups the user belongs to are passed in. Any formatting of group names that is required before inserting these into the Subject should be done and the resulting vector passed back. The options Map contains values for these keys, `scope` and `connection`, and the configured string of the SQL query to retrieve groups with key = "`SQL_QUERY`".

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:

- `key = scope`—the configured scope for the Database Authentication provider.
- `key = QueryPassword`—the `java.lang.Boolean` value that indicates whether the password SQL Query String was configured and executed. If it is false, then the password was not retrieved from the database. This key is only present for the authentication method.
- `key = connection`—an open JDBC `java.sql.Connection` object. Do not close this object; it is returned to the pool after authentication.

# Configuring a Custom Attribute Retriever

To configure a custom attribute retriever, you must implement the attribute retriever and register it with the configured ASI Authorization provider.

To configure an attribute retriever, perform the following steps:

1. Implement a custom attribute retriever and use the Java class to create a JAR file
2. Place the JAR file in the `/lib/providers` directory in the installation directory for the Security Service Module (SSM) on the machine on which the SSM is installed (either the WebLogic Server 8.1 SSM or the Java SSM). For example, the default directory for the WebLogic Server 8.1 SSM is `C:\bea\ales21-ssm\wls-ssm`.
3. In the left pane of the Administration Console, click the ASI Authorization provider configured for the SSM instance, select the Advanced tab in the right pane, type in the fully qualified name of your custom retriever in the Attribute Retrievers field, and click Apply.
4. Repeat step 3. to register the Attribute Retriever with the ASI Role Mapping provider.
5. In the left pane, click Deployment, select the Configuration tab, and deploy the configuration change to the SSM.
6. Restart the SSM ARME process.