> Administration Reference > Provider Extensions

Administration Reference

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

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

Table 3-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
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

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:
  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 Security Service Module is C:\bea\ales22-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:
    • Configuring an ASI Authorization Provider
    • Configuring an ASI Role Mapping Provider

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 3-2 lists and describes the methods provided by the ResourceConverter interface.

Table 3-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.

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:

  1. Implement a custom resource converter and use the Java class to create a JAR file.

    2. The com.bea.security.providers.authorization.asi.ResourceConverter class is in the BEA_HOME\ales22-ssm\<ssm-type>\lib\providers\ASIAuthorizer.jar. Include this file, and the BEA_HOME\ales22-ssm\<ssm-type>\lib\asi_classes.jar, in the classpath when compiling the custom resource converter.

  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 SSM or the Java SSM). For example, the default directory for the WebLogic Server SSM is C:\bea\ales22-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 converter in the Resource Converters field, and click Apply.
  4. Repeat step 3. to register the Resource Converter 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 process.

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

Table 3-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.

Configuring a Custom Attribute Retriever

Note: This release of AquaLogic Enterprise Security includes an attribute retriever example, in BEA_HOME\ales22-ssm\java-ssm\examples\AttributeRetriever.

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

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. The com.bea.security.providers.authorization.asi.AttributeRetriever class is in the BEA_HOME\ales22-ssm\<ssm-type>\lib\providers\ASIAuthorizer.jar. Include this file, and the BEA_HOME\ales22-ssm\<ssm-type>\lib\asi_classes.jar, in the classpath when compiling the custom attribute retriever.

  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 SSM or the Java SSM). For example, the default directory for the WebLogic Server SSM is C:\bea\ales22-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 process.

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 3-4 lists and describes methods provided by the TypeConverter interface.

Table 3-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.

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:

  1. Implement a custom attribute converter 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 SSM or the Java SSM). For example, the default directory for the WebLogic Server SSM is C:\bea\ales22-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 converter in the Attribute Converters field, and click Apply.
  4. Repeat step 3. to register the Attribute Converter 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 process.

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

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

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

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

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:
    3. <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

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 Security Service Module is: C:\bea\ales22-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 3-5 lists and describes a sample AuditEventRenderer class.

Table 3-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 3-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 3-6 lists and describes the methods provided by the DBMSPlugin interface.

Table 3-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:


  Back to Top       Previous  Next