Administration Reference

Audit Events

The following topics are covered in this section:

What is an AuditEvent?

The AuditEvent interface provides a mechanism for passing additional audit information to Auditing providers during a writeEvent operation. This is the base interface that is extended by components in the Security Framework to compose specific audit event types. Extending this interface helps auditing providers determine the calling security component.

If you implement this interface and you expect to receive a ContextHandler argument from a caller, you can extend the AuditContext interface to provide more information.

Some of the sub-interfaces defined by the security SPI are listed in Table 5-1. Table 5-1 also indicates which sub-interfaces implement the AuditContext interface. These interfaces are documented in the BEA AquaLogic Enterprise Security Provider SSPI API Reference.

Table 5-2 lists WebLogic 9.x audit events.

Typically, the audit providers implement the weblogic.security.spi.AuditChannel interface and the weblogic.security.spi.AuditProvider interface, and post events

The AuditEvents that also implement the AuditContext interface can provide more information via a ContextHandler. The ContextHandler interface provides a way for an internal WebLogic container to pass additional information to a WebLogic Security Framework call, so that a security provider can obtain additional context information beyond what is provided by the arguments to a particular method. A ContextHandler is essentially a name/value list. The name/value list is also called a context element, and is represented by a ContextElement object.

What Events are Audited?

Depending on the interface that the AuditEvent has implemented, different information is audited. For all audit events, the toString() method is called on the event and that string is audited. Some audit events have a ContextHandler, such as the AuditAtzEvent and AuditRoleEvent, in which case the context is audited in addition to calling the toString() method on the AuditEvent. You can have many ContextElements, but each NAME/VALUE pair must be iterated over and audited.

The Log4j Audit Channel provider ships with Log4j renderers that are aware of these interfaces and know how to extract the appropriate audit information. You can change this behavior by writing custom renderers and updating the Custom Log4j Renderer Properties text box on the Advanced tab for the Log4j Auditor page in the Administration Console. A custom renderer is useful if only a particular subset of context elements are required or if the default style of audit events needs to be changed.

Each audit record has the following format:

2004-04-22 12:21:55,833 [Thread-27] SUCCESS ASI_AUDIT –  My Custom Event –  Custom Event msg -- <attr1 = value1><attr2 = value2>

A custom renderer may require square brackets [] instead of angle brackets <>.

To be audited, you can select which severity the audit event must equal or be greater than; and you can select the types of AuditEvents by setting the Custom Audit Events attribute. If an AuditEvent implements or is an instance of any of the classes listed, then you can audit it. Only new custom events need to be listed here. The default events already exist and are controlled by selecting either: DISABLED, WITH_CONTEXT, or WITHOUT_CONTEXT on the Details tab for the Log4j Auditor page in the Administration Console. For a list of audit events, see Audit Events.

All audit events generated through the Java API are called through the Provider Audit Records interface using the AuditRecord method. This includes PolicyAdministrationEvent and ARMEAuthorizationEvent. A PolicyAdministrationEvent is generated when a policy change is made through the Administration Console. An ARMEAuthorizationEvent is generated when the ASIAuthorizer makes a authorization request for a policy change.

All audit events can be DISABLED or WITHOUT_CONTEXT. For those that have context, you can select WITH_CONTEXT. The AuditAtzEvents have more options then all the other types, you can select the events to audit based on the following options:

Custom Audit Context Extensions

The Log4J Audit Channel provider is used to audit events that are generated by the Security Framework, the runtime API, or custom implementations based on the weblogic.security.spi.AuditEvent interface AuditEvent class.

Audit plug-ins can be used to audit with minimal awareness of the audit data formats being passed in by the calling Security Framework component. Additionally, Log4j plug-ins written or supplied by third parties can implement actions (such as paging security personal) based on audit severity/criteria you set in the Log4j Audit Channel provider Details tab in the Administration Console. Some general descriptions or suggestions for the information suitable for auditing by AuditEvent are as follows:

Adding Application Context from the BLM API

The BLM API has been enhanced to allow you to send an Application Context to the auditing service.

An Audit Context is a name=value pair that contains additional audit data that is made available to the Audit provider. Like the Audit Context, the Application Context is also a name=value pair data structure, and it contains additional application-specific audit data that is appended to the Audit Context when audit messages are written.

This additional information can be used by a custom Audit provider. Note, however, that the default Log4j Audit provider does not use this additional context.

When you create the Application Context, it is reused for each audit message associated with this BLM Context until it is overwritten by a call to set it, or you clear it.

The following BLM API methods have been added to provide for the Application Context:

Audit Event Interfaces and Audit Events

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

The following sections describe when the security framework and security providers post some prominent types of audit events:

For a list of the events that are audited for the default Admin policy, see BLM Management Events.

AuditAtnEvent

Authentication audit events are posted by the security framework. Table 5-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. Table 5-4 describes the conditions under which the events are posted and severity level of the event.

AuditCredentialMappingEvent

Credential Mapping audit events are posted by the security framework. Table 5-5. describes the condition under which the events are posted and severity level of the event.

AuditMgmtEvent

Management audit events are not currently posted by either the security framework or by the supplied providers.

AuditPolicyEvent

AuditPolicyEvent are 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. Table 5-6 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. Table 5-7 describes the conditions under which the events are posted and lists the event severity level.

AuditRoleEvent

The WebLogic Role Mapping provider posts audit role events when roles are created, deleted, or updated. Table 5-8 describes the conditions under which the events are posted and lists the event severity level.

BLM Management Events

Table 5-9 lists and describes BLM management events that are audited.

AUDITBASE

Table 5-10 indicates the Auditbase events posted by the PD during policy distribution.

Distribution Status Request

As indicated in Table 5-11, the adminstration console posts distribution status request events after user distributes policy from console and distribution result page is rendered.

Distribution

As indicated in Table 5-12, the administration console posts distribution events when user distributes structural change from console.

Examples

When OOTB ALES log4j Audit Provider is configured, following message can be found in secure_audit.log, text in bold is event type:

ProviderAuditRecord

This interface is defined in the SSPI package and provides an extended version of the AuditEvent. Refer to BEA AquaLogic Enterprise Security Provider SSPI API Reference for full documentation of this interface. The SSPI package includes ALES-specific interfaces, classes, and exceptions for developing ALES security providers.

Providers written to work in both the WLS Security Framework and the ALES Security Providers environments must handle both WebLogic audit records and extended AuditEvents. Examples of extended AuditEvents are subinterfaces and implementations of ProviderAuditRecord interface.

In the providers, the instanceof operator can be used to distinguish between the WLS Security Framework interfaces and ALES Enterprise Security Provider interfaces. For example:

if ( myauditrecord instanceof com.bea.security.spi.ProviderAuditRecord){
// This is a ALES audit record that uses the enhanced SSPI.
} else {
// This is a WLS audit record. You must test further for more object
// types and handle them explicitly.
}

A simple audit provider can use the toString() method to render the audit record as a string; the provider does not require specific knowledge of the audit record type. A more complex auditing provider that tracks events by many keys and needs to distinguish messages by various types and attributes requires a data-driven method of event introspection. The complex auditing provider can get an enumeration of com.bea.security.spi.NameValueTypes that contain this audit record's name fields using the ProviderAuditRecord.getEnumeration() and ProviderAuditRecord.getDeepEnumeration() methods.

Additionally, the ProviderAuditRecord interface can associate an application context with an audit event. This allows the auditing provider to select some context elements to audit when events occur. For example, when an audit event occurs, you may choose to audit the number of concurrent sessions, the time the user logged on, or some other application-specific value propagated by the application context.

The following code fragment shows how a custom provider can access the context added by a client application. The modification is primarily in the writeEvent method, as shown.

public void writeEvent(AuditEvent event){
    // write the event out to the sample auditor's
    // log file using the event's "toString" method.
    // followed by the string version of the application 
    // context name value pairs.
    ProviderAuditRecord par = (ProviderAuditRecord) event;
    ContextHandler ch = par.getContext();
    String[] names = ch.getNames();
    StringBuffer ctxReader = new StringBuffer();
    for ( int i=0; i < names.length; i++ ) {
         String value = (String) ch.getValue(names[i]);
         ctxReader.append(names[i]).append("=").append(value); 
    }
    log.println(event + “Context = “ + ctxReader.toString());
}

Other Audit Events

This section describes some of the other AuditEvents used by the security framework and security providers.

AuditApplicationVersionEvent

Table 5-13 describes the conditions under which the event is posted and severity level of the event.

AuditCertPathBuilderEvent and AuditCertPathValidatorEvent

These events are posted by the CertPathBuilder providers.

AuditLifecycleEvent

Life cycle audit events are posted by the WLS framework, as follows:

Additional Audit Event Information

Some implementations of the AuditEvent interface contain additional information that can be accessed by the providers and security framework. All interfaces that extend the weblogic.security.spi.AuditEvent interface or all the implementations of that interface have the following information available:

The following sections provide additional information about specific audit events:

Authentication - AuditAtnEvent

The AuditAtnEvent interface provides an interface for audit providers to determine the instance types of the extended authentication event type objects. Table 5-15 describes the event properties.

When this event is generated, the following information associated with this AuditAtnEvent is available:

There are both pre- and post-authorization access control checks; each of which generates pre- and post-operation audit write events.

Authorization - AuditAtzEvent

The AuditAtzEvent event interface is used to report events that result when access is allowed to a resource. The Audit Channel provider is called both prior to and after the authorization operation.

This event has the following information available:

AuditCredentialMappingEvent

The AuditCredentialMappingEvent interface is used to post credential mapping audit events when credentials for a WebLogic Server user are requested, or when credentials for any subject are requested. The following information is available with this event:

Policy Events - AuditPolicyEvent

The AuditPolicyEvent interface determines the instance types of extended Authorization event type objects. Table 5-16 describes the event subtypes.

All AuditPolicyEvents have:

Policy Deployment - AuditPolicyDeployEvent

The AuditPolicyDeployEvent is type of a AuditPolicyEvent used when the Authorization Manager deployPolicy method is called. When this event is generated, the following information is available:

Policy Undeployment - AuditPolicyUndeployEvent

The AuditPolicyUndeployEvent is type of a AuditPolicyEvent used when the Authorization Manager undeployPolicy method is called. When this event is generated, the same information as listed for the AuditPolicyEvent is available.

Role Mapping - AuditRoleEvent

The AuditRoleEvent event provides an interface for auditing providers to determine the instance types of extended Role Mapping event type objects.

When an AuditRoleEvent is generated, the following information is available:

AuditRoleDeploymentEvent

The AuditRoleDeploymentEvent provides an interface for auditing providers to determine the instance types of extended Role deployment event type objects. Table 5-17 describes the event subtypes.

Role Deployment - AuditRoleDeployEvent

The AuditRoleDeployEvent event is used by the role mapping service to determine the instance types of extended Role Mapping deployment event type objects. In addition to the information listed by the AuditEvent interface, this event also has following additional information:

Role Undeployment - AuditRoleUndeployEvent

The AuditRoleUndeployEvent event is used by the role mapping service to determine the instance types of extended Role Mapping undeployment event type objects. In addition to the information listed by the AuditEvent interface, this event also has the following additional information:

Role Delete App Event

In addition to the information listed by the AuditEvent interface, this event also provides the following additional information:

Role Deployment Start and End Events

In addition to the information listed by the AuditEvent interface, this event also provides the following additional information:

Predicate Events - AuditPredicateEvent

The AuditPredicateEvent event is used by Auditing providers to determine the instance type of extended predicate event type objects. A predicate event occurs when a policy expression is either registered or unregistered in the Administration Console. Table 5-18 describes the event subtypes.

ContextHandler Object

A ContextHandler is a class that obtains additional context and container-specific information from the resource container, and provides that information to security providers making access or role mapping decisions. The ContextHandler interface provides a way for an application or container to pass additional information to a Security Framework call, so that a security provider can obtain contextual information beyond what is provided by the arguments to a particular method. A ContextHandler is essentially a name/value list and as such, it requires a security provider to know what names to look for. In other words, use of a ContextHandler requires close cooperation between the resource container and the security provider. Each name/value pair in a ContextHandler is known as a context element, and is represented by a ContextHandler object.

A context handler is an object that is included with some event types that allows an audit provider to extract other information about the state of the application server at the time of the audit event. The audit provider may log this other contextual information as a way to elaborate on the event and provide other useful information about the causes of the event.

ALES Policy Administration Messages

When AquaLogic Enterprise Security policy is modified or deployed using the AquaLogic Enterprise Security Administration console or BLM Java API, informative messages are audited. The following information is available in these messages:

The exception that occurred (if any) while attempting to carry out this action. Typically, there will only be an exception if the severity is error or failure.

Using Custom Audit Providers

You can use a custom auditing provider instead of the Log4j Audit Channel provider. For a custom auditing provider to be configurable through the Administration Console, the MBean JAR file for the provider must be installed into the BEA_HOME..//lib/providers directory on both the machine on which the Administration Application is installed and on the machine on which the Security Service Module is installed. For complete instructions for configuring a custom security provider, see Configuring a Custom Security Provider in the Console Help.