Administration Application Guide
The following topics are covered in this section:
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 WebLogic 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.
WebLogic 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:
WebLogic Enterprise Security providers support three types of Java-based plug-ins: resource converters, attribute retrievers, and attribute converters. Table 12-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:
To implement a Java-based plug-in interface, you must perform the following steps:
/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\wles42-wls-ssm\lib\providers
.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 WebLogic Enterprise Security. For a description of the policy data formats, see the BEA WebLogic 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 WebLogic Enterprise Resource type. Table 12-2 lists and describes the methods provided by the ResourceConverter
interface.
Attribute retrievers are used by ASI Authorization and ASI Role Mapping providers to retrieve attributes for use by WebLogic 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 12-3 lists and describes the methods provided by the AttributeRetriever
interface.
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 WebLogic 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 12-4 lists and describes methods provided by the TypeConverter
interface.
|
|
Object convertFromASI(String asiFormat) throws TypeConversionException |
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 Function 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 WebLogic 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:
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.
To deploy the extension, do the following:
arme_extension.dll
) into the same path accessible by the ARME process.<ARME.tag>.plugin[1..4] <path>/<DLL plug_in filename>(initialize 'arg')
ARME.wlesadmin.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]
.
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 rule constraints.
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:
To implement an audit plug-in interface, you must perform the following steps:
/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\wles42-wls-ssm\lib\providers
.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 12-5 lists and describes a sample AuditEventRenderer class.
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 WebLogic 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 12-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 12-6 lists and describes the methods provided by the DBMSPlugin
interface.
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.