Developing Security Providers for WebLogic Server

Auditing Providers

Auditing is the process whereby information about operating requests and the outcome of those requests are collected, stored, and distributed for the purposes of non-repudiation. In WebLogic Server, an Auditing provider provides this electronic trail of computer activity.

The following sections describe Auditing provider concepts and functionality, and provide step-by-step instructions for developing a custom Auditing provider:

Auditing Concepts

Before you develop an Auditing provider, you need to understand the following concepts:

Audit Channels

An Audit Channel is the component of an Auditing provider that determines whether a security event should be audited, and performs the actual recording of audit information based on Quality of Service (QoS) policies.

Auditing Events From Custom Security Providers

Each type of security provider can call the configured Auditing providers with a request to write out information about security-related events, before or after these events take place. For example, if a user attempts to access a withdraw method in a bank account application (to which they should not have access), the Authorization provider can request that this operation be recorded. Security-related events are only recorded when they meet or exceed the severity level specified in the configuration of the Auditing providers.

For information about how to post audit events from a custom security provider, see Auditing Events From Custom Security Providers.

The Auditing Process

Figure 10-1 shows how Auditing providers interact with the WebLogic Security Framework and other types of security providers (using Authentication providers as an example) to audit selected events. An explanation follows.

Auditing providers interact with the WebLogic Security Framework and other types of security providers in the following manner:

Implementing the ContextHandler MBean

The ContextHandlerMBean, weblogic.management.security.audit.ContextHandler, provides a set of attributes for ContextHandler support. You use this interface to manage audit providers that support context handler entries in a standard way.

An Auditor provider MBean can optionally implement the ContextHandlerMBean MBean. The Auditor provider can then use the MBean to determine the supported and active ContextHandler entries.

The WebLogic Server Administration Console detects when an Auditor provider implements this MBean and automatically provides a tab for using these attributes.

ContextHandlerMBean Methods

The ContextHandlerMBean interface implements the following methods:

getActiveContextHandlerEntries

getSupportedContextHandlerEntries

setActiveContextHandlerEntries

Example: Implementing the ContextHandlerMBean

Listing 10-5 shows the SimpleSampleAuditProviderImpl.java class, which is the runtime class for the sample Auditing provider. This sample Auditing provider has been enhanced to implement the ContextHandlerMBean.

An MBean Definition File (MDF) is an XML file used by the WebLogic MBeanMaker utility to generate the Java files that comprise an MBean type. All MDFs must extend a required SSPI MBean that is specific to the type of the security provider you have created, and can implement optional SSPI MBeans.

Listing 10-1 shows the key sections of the MDF for the sample Auditing provider, which implements the optional ContexthandlerMBean.

<MBeanType
Name          = "SimpleSampleAuditor"
DisplayName   = "SimpleSampleAuditor"
Package       = "examples.security.providers.audit.simple"
Extends       = "weblogic.management.security.audit.Auditor"
Implements    = "weblogic.management.security.audit.ContextHandler"
PersistPolicy = "OnUpdate"
>

...

<MBeanAttribute
Name          = "SupportedContextHandlerEntries"
Type          = "java.lang.String[]"
Writeable     = "false"
Default       = "new String[] { 
&quot;com.bea.contextelement.servlet.HttpServletRequest&quot; }"
Description   = "List of all ContextHandler entries
supported by the auditor."
/>

Extend weblogic.management.security.audit.ContextHandlerImpl

The ContextHandlerMBean has an setActiveContextHandlerEntries attribute that sets the ContextHandler entries that the Audit provider is currently configured to process. The entries you specify must be listed in the Audit provider's SupportedContextHandlerEntries attribute. However, this requirement is not actually enforced by the MBean. Additional work is required to validate that this attribute can set only values from the SupportedContextHandlerEntries attribute.

You must also create an MBean customizer (for example, you might call it MyAuditorImpl.java) file that extends weblogic.management.security.audit.ContextHandlerImpl. Extending weblogic.management.security.audit.ContextHandlerImpl gives the provider access to the ActiveContextHandlerEntries attribute validator, which ensures that the entries include only SupportedContextHandlerEntries.

An example of extending ContextHandlerImpl is available in SimpleSampleAuditorImpl, which is shown in Listing 10-2.

package examples.security.providers.audit.simple;

import javax.management.MBeanException;
import javax.management.modelmbean.RequiredModelMBean;
import weblogic.management.security.audit.ContextHandlerImpl;

/**
* The simple sample auditor's mbean implementation.
* <p>
* It is needed to inherit the ContextHandlerMBean's ActiveContextHandlerEntries
* attribute validator that ensures that the ActiveContextHandlerEntries
* attribute only contains values from the SupportedContextHandlerEntries
* attribute.
*

* @author Copyright (c) 2005 by BEA Systems. All Rights Reserved.
*/

public class SimpleSampleAuditorImpl extends ContextHandlerImpl
// Note: extend ContextHandlerImpl instead of AuditorImpl to inherit
// the ActiveContextHandlerEntries attribute validator.
{

/**
* Standard mbean impl constructor.
*
* @throws MBeanException
*/
public SimpleSampleAuditorImpl(RequiredModelMBean base) throws MBeanException
{
super(base);
}
}

After you implement code similar to that in SimpleSampleAuditorImpl, add code to your Audit runtime provider to get the ActiveContextHandlerEntries. One possible way to do this is shown in Listing 10-3.

 String [] activeHandlerEntries = myMBean.getActiveContextHandlerEntries();

    if (activeHandlerEntries != null) {

      for (int i=0; i<activeHandlerEntries.length; i++) {

        if ((activeHandlerEntries[i] != null) &&

            (activeHandlerEntries[i].equalsIgnoreCase(HTTP_REQUEST_ELEMENT))) {

          handlerEnabled = true;

          break;

        }

      }

    }

Do You Need to Develop a Custom Auditing Provider?

The default (that is, active) security realm for WebLogic Server includes a WebLogic Auditing provider. The WebLogic Auditing provider records information from a number of security requests, which are determined internally by the WebLogic Security Framework. The WebLogic Auditing provider also records the event data associated with these security requests, and the outcome of the requests.

The WebLogic Auditing provider makes an audit decision in its writeEvent method, based on the audit severity level it has been configured with and the audit severity contained within the AuditEvent object that is passed into the method. (For more information about AuditEvent objects, see Create an Audit Event.

If there is a match, the WebLogic Auditing provider writes audit information to the DefaultAuditRecorder.log file, which is located in the WL_HOME\yourdomain\ yourserver\logs directory. Listing 10-4 is an excerpt from the DefaultAuditRecorder.log file.

When Authentication suceeds. [SUCCESS]

#### Audit Record Begin <Feb 23, 2005 11:42:17 AM>  <Severity=SUCCESS> 
<<<Event Type = Authentication Audit Event><TestUser><AUTHENTICATE>>> Audit 
Record End ####

When Authentication fails. [FAILURE]

#### Audit Record Begin <Feb 23, 2005 11:42:01 AM>  <Severity=FAILURE> 
<<<Event Type = Authentication Audit Event><TestUser><AUTHENTICATE>>> Audit
Record End ####When Operations are invoked.[SUCCESS]

When a user account is unlocked. [SUCCESS]

#### Audit Record Begin <Feb 23, 2005 11:42:17 AM>  <Severity=SUCCESS> 
<<<Event Type = Authentication Audit Event><TestUser><USERUNLOCKED>>> Audit 
Record End ####

When an Authorization request succeeds. [SUCCESS]

#### Audit Record Begin <Feb 23, 2005 11:42:17 AM>  <Severity=SUCCESS> 
<<<Event Type = Authorization Audit Event ><Subject: 1
Principal = class weblogic.security.principal.WLSUserImpl("TestUser")
><ONCE><<jndi>><type=<jndi>, application=, path={weblogic}, action=lookup>>>
Audit Record End ####

Specifically, Listing 10-4 shows the Role Manager (a component in the WebLogic Security Framework that deals specifically with security roles) recording an audit event to indicate that an authorized administrator has accessed a protected method in a certificate servlet.

Each time the WebLogic Server instance is booted, a new DefaultAuditRecorder.log file is created (the old DefaultAuditRecorder.log file is renamed to DefaultAuditRecorder.log.old).

You can specify a new directory location for the DefaultAuditRecorder.log file on the command line with the following Java startup option:

-Dweblogic.security.audit.auditLogDir=c:\foo

The new file location will be c:\foo\yourserver\DefaultAuditRecorder.log.

If you want to write audit information in addition to that which is specified by the WebLogic Security Framework, or to an output repository that is not the DefaultAuditRecorder.log (that is, to a simple file with a different name/location or to an existing database), then you need to develop a custom Auditing provider.

How to Develop a Custom Auditing Provider

If the WebLogic Auditing provider does not meet your needs, you can develop a custom Auditing provider by following these steps:

Create Runtime Classes Using the Appropriate SSPIs

Before you start creating runtime classes, you should first:

When you understand this information and have made your design decisions, create the runtime classes for your custom Auditing provider by following these steps:

For an example of how to create a runtime class for a custom Auditing provider, see Example: Creating the Runtime Class for the Sample Auditing Provider.

Implement the AuditProvider SSPI

To implement the AuditProvider SSPI, provide implementations for the methods described in Understand the Purpose of the Provider SSPIs and the following method:

getAuditChannel

For more information about the AuditProvider SSPI and the getAuditChannel method, see the WebLogic Server API Reference Javadoc.

Implement the AuditChannel SSPI

To implement the AuditChannel SSPI, provide an implementation for the following method:

writeEvent

For more information about the AuditChannel SSPI and the writeEvent method, see the WebLogic Server API Reference Javadoc.

Example: Creating the Runtime Class for the Sample Auditing Provider

Listing 10-5 shows the SimpleSampleAuditProviderImpl.java class, which is the runtime class for the sample Auditing provider. This runtime class includes implementations for:

package examples.security.providers.audit.simple;

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.PrintStream;

import javax.servlet.http.HttpServletRequest;

import weblogic.management.security.ProviderMBean;
import weblogic.security.service.ContextHandler;
import weblogic.security.spi.AuditChannel;
import weblogic.security.spi.AuditContext;
import weblogic.security.spi.AuditEvent;
import weblogic.security.spi.AuditProvider;
import weblogic.security.spi.SecurityServices;

public final class SimpleSampleAuditProviderImpl implements AuditProvider, AuditChannel

{
   private String      description; // a description of this provider
   private PrintStream log;         // the log file that events are written to
   private boolean     handlerEnabled = false;
   private final static String HTTP_REQUEST_ELEMENT = "com.bea.contextelement.servlet.HttpServletRequest";

   public void initialize(ProviderMBean mbean, SecurityServices services)
   {
     System.out.println("SimpleSampleAuditProviderImpl.initialize");

     SimpleSampleAuditorMBean myMBean = (SimpleSampleAuditorMBean)mbean;

     description = myMBean.getDescription() + "\n" + myMBean.getVersion();

     String [] activeHandlerEntries = myMBean.getActiveContextHandlerEntries();
     if (activeHandlerEntries != null) {
       for (int i=0; i<activeHandlerEntries.length; i++) {
         if ((activeHandlerEntries[i] != null) &&
             (activeHandlerEntries[i].equalsIgnoreCase(HTTP_REQUEST_ELEMENT))) {
           handlerEnabled = true;
           break;
        }
       }
     }

     File file = new File(myMBean.getLogFileName());
     System.out.println("\tlogging to " + file.getAbsolutePath());

     try {
       log = new PrintStream(new FileOutputStream(file), true);
     } catch (IOException e) {
       throw new RuntimeException(e.toString());
     }

   }

   public String getDescription()
   {
     return description;
   }

   public void shutdown()
   {
     System.out.println("SimpleSampleAuditProviderImpl.shutdown");
     log.close();
   }

   public AuditChannel getAuditChannel()
   {
     return this;
   }

   public void writeEvent(AuditEvent event)
   {
     log.println(event);

     if ((!handlerEnabled) || (!(event instanceof AuditContext)))
       return;

     AuditContext auditContext = (AuditContext)event;
     ContextHandler handler = auditContext.getContext();

     if ((handler == null) || (handler.size() == 0))
       return;

     Object requestValue = handler.getValue("com.bea.contextelement.servlet.HttpServletRequest");
     if ((requestValue == null) || (!(requestValue instanceof HttpServletRequest)))
       return;

     HttpServletRequest request = (HttpServletRequest) requestValue;
     log.println("    " + HTTP_REQUEST_ELEMENT + " method: " + request.getMethod());
     log.println("    " + HTTP_REQUEST_ELEMENT + " URL: " + request.getRequestURL());
     log.println("    " + HTTP_REQUEST_ELEMENT + " URI: " + request.getRequestURI());
     return;
   }
}

Generate an MBean Type Using the WebLogic MBeanMaker

Before you start generating an MBean type for your custom security provider, you should first:

When you understand this information and have made your design decisions, create the MBean type for your custom Auditing provider by following these steps:

Create an MBean Definition File (MDF)

To create an MBean Definition File (MDF), follow these steps:

Use the WebLogic MBeanMaker to Generate the MBean Type

Once you create your MDF, you are ready to run it through the WebLogic MBeanMaker. The WebLogic MBeanMaker is currently a command-line utility that takes as its input an MDF, and outputs some intermediate Java files, including an MBean interface, an MBean implementation, and an associated MBean information file. Together, these intermediate files form the MBean type for your custom security provider.

The instructions for generating an MBean type differ based on the design of your custom Auditing provider. Follow the instructions that are appropriate to your situation:

No Custom Operations

If the MDF for your custom Auditing provider does not include any custom operations, follow these steps:

Custom Operations

If the MDF for your custom Auditing provider does include custom operations, consider the following:

About the Generated MBean Interface File

The MBean interface file is the client-side API to the MBean that your runtime class or your MBean implementation will use to obtain configuration data. It is typically used in the initialize method as described in Understand the Purpose of the Provider SSPIs.

Because the WebLogic MBeanMaker generates MBean types from the MDF you created, the generated MBean interface file will have the name of the MDF, plus the text "MBean" appended to it. For example, the result of running the SampleAuditor MDF through the WebLogic MBeanMaker will yield an MBean interface file called SampleAuditorMBean.java.

Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF)

Once your have run your MDF through the WebLogic MBeanMaker to generate your intermediate files, and you have edited the MBean implementation file to supply implementations for the appropriate methods within it, you need to package the MBean files and the runtime classes for the custom Auditing provider into an MBean JAR File (MJF). The WebLogic MBeanMaker also automates this process.

To create an MJF for your custom Auditing provider, follow these steps:

The resulting MJF can be installed into your WebLogic Server environment, or distributed to your customers for installation into their WebLogic Server environments.

Install the MBean Type Into the WebLogic Server Environment

To install an MBean type into the WebLogic Server environment, copy the MJF into the WL_HOME\server\lib\mbeantypes directory, where WL_HOME is the top-level installation directory for WebLogic Server. This "deploys" your custom Auditing provider—that is, it makes the custom Auditing provider manageable from the WebLogic Server Administration Console.

You can create instances of the MBean type by configuring your custom Auditing provider (see Configure the Custom Auditing Provider Using the Administration Console), and then use those MBean instances from a GUI, from other Java code, or from APIs. For example, you can use the WebLogic Server Administration Console to get and set attributes and invoke operations, or you can develop other Java objects that instantiate MBeans and automatically respond to information that the MBeans supply. We recommend that you back up these MBean instances.

Configure the Custom Auditing Provider Using the Administration Console

Configuring a custom Auditing provider means that you are adding the custom Auditing provider to your security realm, where it can be accessed by security providers requiring audit services.

Configuring custom security providers is an administrative task, but it is a task that may also be performed by developers of custom security providers. This section contains information that is important for the person configuring your custom Auditing providers:

Configuring Audit Severity

During the configuration process, an Auditing provider's audit severity must be set to one of the following severity levels:

This severity represents the level at which the custom Auditing provider will initiate auditing.

Security Framework Audit Events

This section describes the audit events that are posted by the WebLogic Server Security Framework. If you write a custom audit provider, it should be prepared to handle these events. The following topics are covered in this section:

Passing Additional Audit Information

The WebLogic Security providers implement the appropriate AuditEvent interfaces and post those events to the Audit provider. The audit events that also implement the AuditContext interface can provide more information via a ContextHandler.

Table 10-1 lists the weblogic.security.spi subinterfaces that extend the AuditEvent SSPI, and indicates which subinterfaces implement the AuditContext interface.

Audit Event Interfaces and Audit Events

In the weblogic.security.spi package, WebLogic Security defines one top-level base interface (AuditEvent) with derived interfaces that represent the different types of audit events.

Subsequent sections describe when the security framework and security providers post the following audit events:

AuditApplicationVersionEvent

Application version audit events are posted by the security framework. You can use the getEventType method to get the type of the audit event. The actual audit string returned by getEventType is String = " Application Version Audit Event".

Table 10-2 describes the conditions under which the event is posted and severity level of the event.

AuditAtnEventV2

Authentication audit events are posted by the security framework. You can use the getEventType method to get the type of the audit event. The actual audit string returned by getEventType is String eventType = "Event Type = Authentication Audit Event".

Table 10-3 describes the conditions under which the event is posted and severity level of the event.

AuditAtzEvent

Authorization audit events are posted by the security framework. You can use the getEventType method to get the type of the audit event. The actual audit string returned by getEventType is String eventType = "Event Type = Authorization Audit Event V2 ".

Table 10-4 describes the conditions under which the events are posted and severity level of the event.

AuditCerPathBuilderEvent, AuditCertPathValidatorEvent

CertPath Builder and Validation audit events are posted by the security framework. You can use the getEventType method to get the type of the audit event. The actual audit strings returned by getEventType are as follows:

Table 10-5 describes the conditions under which the events are posted and severity level of the event.

AuditConfigurationEvent

Configuration audit events are posted by the security framework. The following events are posted:

Table 10-6 describes the conditions under which the events are posted and severity level of the events.

AuditCredentialMappingEvent

Credential Mapping audit events are posted by the security framework. You can use the getEventType method to get the type of the audit event. The actual audit string returned by getEventType is String EVENT_TYPE = "Event Type = Credential Mapping Audit Event".

Table 10-7 describes the condition under which the events are posted and severity level of the event.

AuditLifecycleEvent

The AuditLifecycleEvent interface is used to post audit lifecycle events. The WebLogic Security Framework implements this interface and may post audit events for the following security events:

The actual audit string returned by getEventType is String eventType = "Event Type = AuditLifecycle Audit Event".

The AuditLifecycleEventType class describes the audit service lifecycle event types that are supported. Possible values are START_AUDIT and STOP_AUDIT.

An Auditing provider can use this interface to get additional information about the audit lifecycle event. The AuditSeverity and AuditLifecycleEventType attributes can be used to determine which of the above audit events has been posted.

AuditMgmtEvent

Management audit events are not currently posted by either the Security Framework or by the supplied providers. However, a custom security provider may implement this interface and post different audit events for the various management operations performed by the custom security provider.

An Auditing provider can use this interface to get additional information about the management audit event. The AuditSeverity attribute can be used to determine whether the management operation succeeded or failed.

AuditPolicyEvent

AuditPolicyEvent is posted by the security framework and the WebLogic Authorization provider. The security framework posts audit policy events when policies are deployed to or undeployed from an authorization provider. The WebLogic Server authorization provider posts audit policy events when creating, deleting, or updating policies. You can use the getEventType method to get the type of the audit event. The audit events and the actual audit strings returned by getEventType are as follows:

For PolicyConsumerAuditEvent, which implements AuditPolicyEvent, the actual audit strings returned by getEventType are:

Table 10-8 describes the conditions under which the events are posted and lists the event severity level.

AuditRoleDeploymentEvent

The security framework posts audit role deployment events when roles are deployed to or undeployed from a role mapping provider. You can use the getEventType method to get the type of the audit event. The following events are posted:

Table 10-9 describes the conditions under which the events are posted and lists the event severity level.

AuditRoleEvent

The WebLogic Authorization provider posts audit role events when roles are created, deleted, or updated. You can use the getEventType method to get the type of the audit event. The actual audit strings returned by getEventType are as follows:

For RoleConsumerAuditEvent, which implements AuditRoleEvent, the actual audit strings returned by getEventType are:

Table 10-10 describes the conditions under which the events are posted and lists the event severity level.