Skip navigation.
Downloads | Product Documentation | Support

Administration Reference

# Audit Events

The following topics are covered in this section:

- What is an AuditEvent?
- What Events are Audited?
- Custom Audit Context Extensions
- Audit Event Interfaces and Audit Events
- Additional Audit Event Interfaces
- Using Custom Audit Providers

# 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 2-1. Table 2-1 also indicates which sub-interfaces implement the `AuditContext` interface. These interfaces are documented in the BEA AquaLogic Enterprise Security Provider SSPI 4.2 API Reference.

Table 2-1 Audit Events

Audit Event Name | Interface Class | Interfaces Implemented
--- | --- | ---
|  | AuditEvent | AuditContext
Authentication Audit Event | weblogic.security.spi.AuditAtnEvent | Yes | No
Authentication Audit Event V2 | weblogic.security.spi.AuditAtnEventV2 | Yes | Yes
Authorization Audit Event | weblogic.security.spi.AuditAtzEvent | Yes | Yes
Role Mapping Audit Event | weblogic.security.spi.AuditRoleEvent | Yes | Yes
Credential Mapping Audit Event | weblogic.security.spi.AuditCredentialMappingEvent | Yes | Yes
Management Audit Event | weblogic.security.spi.AuditMgmtEvent | Yes | No
Policy Audit Event | weblogic.security.spi.AuditPolicyEvent | Yes | No
Role Deployment Audit Event | weblogic.security.spi.AuditRoleDeploymentEvent | Yes | No
Provider Audit Record | com.bea.security.spi.ProviderAuditRecord | Yes | Yes

The providers implement the appropriate `AuditEvent` interfaces and post those events to the Audit provider. 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.

Note: Printing the entire context by enabling `WITH_CONTEXT` can be an expensive task and is proportional to the number of context elements contained in the `ContextHandler`.

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 ARME 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:

- `DISABLE`—No auditing occurs.
- `WITHOUT_CONTEXT`—Audits what is in the event message.
- `WITH_REQUEST_CONTEXT`—Audits the event message plus the request context.
- `WITH_RESPONSE_CONTEXTS`—Audits the event message plus all the response contexts. Only contains the context that was populated with responses from the ASI Authorization provider. There can be many contexts returned for a single query and hence the `CONTEXTS`.
- `WITH_ALL_CONTEXTS`—Audits the event message plus all the contexts (request as well as response contexts).

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

- Audit events are structured to have a two-tier model. There is a `weblogic.security.spi.AuditEvent` interface that defines the minimum requirements for an audit event. This interface includes `type`, `severity`, `toString()`, and, if there was an exception associated with the event, a reference to the exception.
- In addition to the core `AuditEvent` interface, several additional interfaces are defined to further elaborate on the audit types, and, for providers that need to retrieve audit properties that are specific to the audit type, interfaces exist that allow the providers to extract these values.
- A provider that is not reporting specific event properties can be coded to only recognize the core `AuditEvent` class and to use `toString` to output its representation of the event as a String.
- Audit providers that need to do other things (such as selectively log events based on event properties) must be specifically coded to the interfaces described so that they know how to extract these event values from the audit event.

# Audit Event Interfaces and Audit Events

In the security provider interface package, WebLogic Security defines one top-level base interface (`AuditEvent`) with seven different derived interfaces that represent the different types of audit events. The following sections describe when the security framework and security providers post these audit events.

- AuditAtnEvent
- AuditAtzEvent
- AuditMgmtEvent
- AuditCredentialMappingEvent
- AuditPolicyEvent
- AuditRoleDeploymentEvent
- AuditRoleEvent

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

## AuditAtnEvent

Authentication audit events are posted by the security framework. Table 2-2 describes the conditions under which the event is posted and severity level of the event.

####

Table 2-2 Authentication Audit Events

Component | Description | Severity
--- | --- | ---
Security Framework | Posted after successful authentication of a user. | Success
Security Framework | Posted after unsuccessful authentication (a LoginException thrown from JAAS login method). This LoginException can be thrown by either JAAS framework or by JAAS LoginModule of WebLogic Server authentication provider. | Failure
Security Framework | Posted after an identity assertion to an anonymous user. | Success
Security Framework | Posted after an unsuccessful identity assertion (IdentityAssertionException thrown from identity assertion method). | Failure
Security Framework | Posted after an unsuccessful identity assertion (IOException is thrown by identity assertion callback handler when retrieving username from callback). | Failure
Security Framework | Posted after an unsuccessful identity assertion (UnsupportedCallbackException is thrown by identity assertion callback handler when retrieving username from callback). | Failure
Security Framework | Posted after an unsuccessful identity assertion (when username returned from identity assertion callback handler is null or zero length). | Failure
Security Framework | Posted after a successful identity assertion. | Success
Security Framework | Posted after an unsuccessful identity assertion. | Failure
Security Framework | Posted after a successful impersonate identity (anonymous identity). | Success
Security Framework | Posted after a successful impersonate identity. | Success
Security Framework | Posted after an unsuccessful impersonate identity. | Failure
Security Framework | Posted after a failure of principal validation. | Failure

## AuditAtzEvent

Authorization audit events are posted by the security framework. Table 2-3 describes the conditions under which the events are posted and severity level of the event.

####

Table 2-3 Authorization Audit Events

Component | Description | Severity
--- | --- | ---
Security Framework | Posted if access is not allowed to resource (exception thrown by authorization provider). | Failure
Security Framework | Posted if access is allowed to resource. | Success
Security Framework | Posted if access is not allowed to resource. | Failure

## AuditCredentialMappingEvent

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

####

Table 2-4 Credential Mapping Audit Events

Component | Description | Severity
--- | --- | ---
Security Framework | Posted after each successful get of credentials. | Success

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

####

Table 2-5 Audit Policy Events

Component | Description | Severity
--- | --- | ---
Security Framework | Posted after successful deploy of policy. | Success
Security Framework | Posted after unsuccessful deploy of policy. | Failure
Security Framework | Posted after successful undeploy of policy. | Success
Security Framework | Posted after an unsuccessful undeploy of policy. | Failure
WebLogic Authorization Provider | Posted after the following events occur: A successful create of policy from console An unsuccessful create of policy from console (various exceptions) A successful remove of policy from console An unsuccessful remove of policy from console (various exceptions) A successful update of policy from console An unsuccessful update of policy from console (various exceptions) | Success

## AuditRoleDeploymentEvent

The security framework posts audit role deployment events when roles are deployed to or undeployed from a role mapping provider. Table 2-6 describes the conditions under which the events are posted and lists the event severity level.

####

Table 2-6 Audit Role Deployment Events

Component | Description | Severity
--- | --- | ---
Security Framework | Posted after each successful role deployment to a role mapping provider. | Success
Security Framework | Posted after each unsuccessful role deployment to a role mapping provider. | Failure
Security Framework | Posted after each successful role undeployment from a role mapping provider. | Success
Security Framework | Posted after each unsuccessful role undeployment from a role mapping provider. | Failure

## AuditRoleEvent

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

####

Table 2-7 Audit Role Events

Component | Description | Severity
--- | --- | ---
WebLogic Role Mapping Provider | Posted after the following events occur: A successful create of role from console An unsuccessful create of role from console (various exceptions) A successful remove of role from console An unsuccessful remove of role from console (various exceptions) A successful update of role from console An unsuccessful update of role from console (various exceptions) | Success

## Admin Policy Audit Events

Table 2-8 lists and describes the administration policy events that are audited.

Table 2-8 Admin Policy Audit Events

Policy Element | Action | Type | Event Description
--- | --- | --- | ---
Declaration/Attribute | create | declaration | Create a new attribute declaration.
delete | declaration | Delete an attribute declaration.
rename | declaration, new_name | Rename an attribute declaration.
modify | declaration | Modify an attribute declaration.
Declaration/Constant | create | declaration, value | Create a new constant.
delete | declaration, value | Delete a constant.
rename | declaration, value, new_name | Rename a constant.
modify | declaration, value, new_value | Modify a constant.
Declaration/Enumeration | create | declaration, value | Create a new enumeration.
delete | declaration, value | Delete an enumeration.
rename | declaration, value, new_name | Rename an enumeration.
modify | declaration, value, new_value | Modify an enumeration.
Declaration/Evaluation Function | create | declaration | Create an evaluation function.
delete | declaration | Delete an evaluation function.
rename | declaration, new_name | Rename an evaluation function.
Identity/Directory/Instance | create | directory | Create a directory.
delete | directory | Delete a directory.
cascade Delete | directory | Delete a directory and all its users.
rename | directory, new_name | Rename a directory.
Identity/Directory/ AttributeMapping/ Single | create | attribute, default_value, directory | Add a scalar attribute to a directory attribute schema.
delete | attribute, default_value, directory | Delete a scalar attribute from a directory attribute schema.
modify | attribute, default_value, directory, new_default_value | Modify a scalar attribute in a directory attribute schema.
Identity/Directory/ AttributeMapping/ List | create | attribute, default_value, directory | Add a vector attribute to a directory attribute schema.
delete | attribute, default_value directory | Delete a vector attribute from a directory attribute schema.
modify | attribute, default_value, directory, new_default_value | Modify a vector attribute in a directory attribute schema.
Identity/Subject/ User | create | subject_name | Create a new user.
copy | subject_name, new_subject_name | Copy a user.
delete | subject_name | Delete a user.
cascade Delete | subject_name | Cascade a user and all policies associated with the user.
rename | subject_name, new_subject_name | Rename a user.
Identity/Subject/ Group | create | subject_name | Create a new group.
delete | subject_name | Delete a group.
rename | subject_name, new_subject_name | Rename a group.
addMember | subject_name, member_subject | Add a member to a group.
remove Member | subject_name, member_subject | Remove a member from a group.
Identity/Subject/ Attribute Assignment/ Single | create | attribute, value, subject_name | Set a value to a currently unset scalar subject attribute.
delete | attribute, value, subject_name | Unset a currently set scalar subject attribute.
modify | attribute, value, subject_name, new_value | Modify the value of a currently set scalar subject attribute.
Identity/Subject/ Attribute Assignment/List | create | attribute, value, subject_name | Set a value to a currently unset vector subject attribute.
delete | attribute, value, subject_name | Unset a currently set vector subject attribute.
modify | attribute, value, subject_name, new_value | Modify the value of a currently set vector subject attribute.
Identity/Subject/ Password | modify | subject_name | Modify the user password. The "subject_name" attribute contains the name of the user with which the password is associated.
Resource/Instance | create | resource, resource_type | Create a new resource.
delete | resource | Delete a resource.
cascade Delete | resource | Cascade delete of a resource. This includes deletion of all child resources and associated policies.
rename | resource, new_name | Rename a resource.
Resource/Attribute Assignment/Single | create | attribute, resource, value | Set a value to a currently unset scalar resource attribute.
delete | attribute, resource, value | Unset a currently set scalar resource attribute.
modify | attribute, resource, value, new_value | Modify the value of a currently set scalar resource attribute.
Resource/Attribute Assignment/List | create | attribute, resource, value | Set a value to a currently unset vector resource attribute.
delete | attribute, resource, value | Unset a currently set vector resource attribute.
modify | attribute, resource, value, new_value | Modify the value of a currently set vector resource attribute
Resource/Metadata/ IsApplication | modify | resource, value, new_value | Toggle the "is application" resource metadata.
Resource/Metadata/ IsDistributionPoint | modify | resource, value, new_value | Toggle the "is distribution point" resource metadata.
Resource/Metadata/ Logical Name | create | logical_name, resource | Create a logical name for a resource.
delete | logical_name, resource | Delete the logical name of a resource.
rename | logical_name, resource, new_name | Rename the logical name of a resource.
Policy/Rule/Grant | create | action, resource, subject_name, constraint | Create a new grant policy. The "action", "resource", and "subject_name" attributes are lists.
delete | action, resource, subject_name, constraint | Delete a grant policy. The "action", "resource", and "subject_name" attributes are lists.
modify | action, resource, subject_name, constraint, new_action, new_resource, new_subject_name, new_constraint | Modify a grant policy. The "action", "resource", and "subject_name" attributes are lists.
Policy/Rule/Deny | create | action, resource, subject_name, constraint | Create a new deny policy. The "action", "resource", and "subject_name" attributes are lists.
delete | action, resource, subject_name, constraint | Delete a deny policy. The "action", "resource", and "subject_name" attributes are lists.
modify | action, action_type, resource, subject_name, subject_type, constraint, new_effect, new_action, new_action_type, new_resource, new_subject_name, new_subject_type, new_constraint | Modify a deny policy. The "action", "resource", and "subject_name" attributes are lists.
Policy/Rule/Delegate | create | action, resource, subject_name, delegator, constraint | Create a new delegate policy. The "action", "resource", and "subject_name" attributes are lists.
delete | action, resource, subject_name, delegator, constraint | Delete a delegate policy. The "action", "resource", and "subject_name" attributes are lists.
modify | action, resource, subject_name, delegator, constraint, new_action, new_resource, new_subject_name, new_delegator, new_constraint | Modify a delegate policy. The "action", "resource", and "subject_name" attributes are lists.
Policy/Action/Role/ Instance | create | action | Create a new role.
delete | action | Delete a role.
rename | action, new_name | Rename a role.
Policy/Action/ Privilege/Instance | create | action | Create a privilege.
delete | action | Delete a privilege.
rename | action, new_name | Rename a privilege.
Policy/Action/ Privilege/Group | create | action_group | Create a privilege group.
delete | action_group | Delete a privilege group.
rename | action_group, new_name | Rename a privilege group.
addMember | action_group, action | Add a privilege to a privilege group.
remove Member | action_group, action | Remove a privilege from a privilege group.
Policy/Analysis/ Inquiry Query | create | title, owner, effect_type, subjects, actions, resources, delegator | Create a new policy query.
delete | title, owner | Delete a policy query.
modify | title, owner, effect_type, subjects, actions, resources, delegator | Modify a policy query.
execute | title, owner, effect_type, subjects, actions, resources, delegator | Execute a policy query. If this is an unsaved query "title" and "owner" is set to an emptystring.
Policy/Analysis/ Verification Query | create | title, owner, actions, resources | Create a new policy verification query.
delete | title, owner | Delete a policy verification query.
modify | title, owner, actions, resources | Modify a policy verification query.
execute | title, owner, actions, resources | Execute a policy verification query. If this is an unsaved query "title" and "owner" is set to an emptystring.
Policy/Repository | deploy Update | resource, directory | Deploy a policy update. The "resource" is the distribution node; all nodes below it may be effected. This check is made for each chosen distribution point
deploy Structural Change | deleted_directories, deployed_engines, deleted_engines, deleted_bindings, deleted_applications | Deploy a structural change.
Infrastructure/Engines/ARME | create | engine | Create a new SSM.
delete | engine | Delete an SSM.
rename | engine, new_name | Rename an SSM.
bind | engine, resource | Bind a resource to an SSM.
unbind | engine, resource | Unbind a resource from an SSM.
Infrastructure/Engines/SCM | create | engine | Create an SCM.
delete | engine | Delete an SCM.
rename | engine, new_name | Rename an SCM.
bind | engine, resource | Bind an SSM to an SCM. A "resource" contains the name of the SSM.
unbind | engine, resource | Unbind an SSM from an SCM. A "resource" contains the name of the SSM.
Infrastructure/ Management/Console | login |  | Login to the ALES administration console.
Infrastructure/ Management/BulkManager | login |  | Login to the ALES policy loader.

# Additional Audit Event Interfaces

The following sections describe additional audit event interfaces:

- Authentication - AuditAtnEvent
- Policy Deployment - AuditPolicyDeployEvent
- Policy Undeployment - AuditPolicyUndeployEvent
- Policy Events - AuditPolicyEvent
- Role Mapping - AuditRoleEvent
- Role Deployment - AuditRoleDeployEvent
- Role Undeployment - AuditRoleUndeployEvent
- Predicate Events - AuditPredicateEvent
- ContextHandler Object
- PolicyAdministrationEvent

### Authentication - AuditAtnEvent

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

Table 2-9 Authentication - AuditAtnEvent

Event Property | Description
--- | ---
AUTHENTICATE | Represents the "simple authentication" authentication type.
USERLOCKED | Indicates that a user was locked because of a series of failed login attempts.
USERLOCKOUTEXPIRED | Indicates that a lock on a user has expired.
USERUNLOCKED | Indicates that a lock on a user was cleared.
ASSERTIDENTITY | Represents the identity assertion authentication token type.
IMPERSONATEIDENITY | Represents the impersonate identity authentication type.

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

- The username associated with this `AuditAtnEvent`; that is, the username of the person who is attempting authentication.
- The event type associated with this `AuditAtnEvent`
- Authorization - `AuditAtzEvent`

There are both pre- and post-authorization access control checks; each of which generates pre- and post-operation audit write events. The `AuditAtzEvent` event interface is used to report events that result when access is allowed on a resource. The Audit Channel provider is called on both the pre- and post-operation cases. The exceptions reported using this event must derive from the `java.security.GeneralSecurityException`.

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

- The name of the resource
- The name of the subject
- The ContextHandler object

The resource container that handles the type of resource requested (for example, in WebLogic Server 8.1, the EJB container receives the request for an EJB resource) constructs a ContextHandler object that may be used by an authorization provider Access Decision to obtain information associated with the context of the request. This ContextHandler object is also available with this AuditAtzEvent. For more information about the ContextHandler object, see ContextHandler Object.

### Policy Deployment - AuditPolicyDeployEvent

The `AuditPolicyDeployEvent` event interface is used when the Authorization Manager `deployPolicy` method is called. When this event is generated, the following information is available:

- The subject whose action is being audited
- The severity of this event
- The resource that is the target of action being audited
- A string array of role names for this policy
- 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.

### Policy Undeployment - AuditPolicyUndeployEvent

The `AuditPolicyUndeployEvent` event interface is used when the Authorization Manager `undeployPolicy` method is called. When this event is generated, the following information is available:

- The subject whose action is being audited
- The severity of this event
- The resource that is the target of action being audited
- A string array of role names for this policy

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

### Policy Events - AuditPolicyEvent

The `AuditPolicyEvent` event interface determines the instance types of extended Authorization event type objects. Table 2-10 describes the event subtypes.

Table 2-10 Policy Event- AuditPolicyEvent

Event Subtype | Description
--- | ---
DEPLOY | Indicates that a policy deployment event occurred.
UNDEPLOY | Indicates that a policy undeployment event occurred.
UPDATE | Indicates that a policy was updated.

### Role Mapping - AuditRoleEvent

The `AuditRoleEvent` event provides an interface for auditing providers to determine the instance types of extended Role Mapping event type objects. Table 2-11 describes the event subtypes.

Table 2-11 Role Mapping - AuditRoleEvent

Event Subtype | Description
--- | ---
DEPLOY | Indicates that a role mapping deployment event occurred.
UNDEPLOY | Indicates that a role mapping undeployment event occurred.
UPDATE | Indicates that a role mapping was updated.

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

- The Subject that is attempting to access the resource associated with this `AuditRoleEvent`
- The resource attempting to be accessed by the subject associated with this `AuditRoleEvent`
- The `ContextHandler` object

The resource container that handles the type of resource being requested (for example, with WebLogic Server 8.1, the EJB container receives the request for an EJB resource) constructs a `ContextHandler` object that may be used by an Authorization provider Access Decision to obtain information associated with the context of the request. This `ContextHandler` object is also available with this `AuditAtzEvent`. For more information about the `ContextHandler` object, see ContextHandler Object.

### Role Deployment - AuditRoleDeployEvent

The `AuditRoleDeployEvent` event provides a interface used by the role mapping service to determine the instance types of extended Role Mapping deployment event type objects.

### Role Undeployment - AuditRoleUndeployEvent

The AuditRoleUndeployEvent event provides a interface used by the role mapping service to determine the instance types of extended Role Mapping undeployment event type objects.

### Predicate Events - AuditPredicateEvent

The AuditPredicateEvent event provides a interface for 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 2-12 describes the event subtypes.

Table 2-12 Predicate Events - AuditPredicateEvent

Event Subtype | Description
--- | ---
REGISTER | Occurs when a policy expression is registered.
UNREGISTER | Occurs when a policy expression is registered.

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

### PolicyAdministrationEvent

The PolicyAdministrationEvent event is used when AquaLogic Enterprise Security policy is modified or deployed using the AquaLogic Enterprise Security Administration console or bulk loader. When this event is generated, the following information is available:

- The subject whose action is being audited
- The severity of this event
- The resource that is the target of action being audited
- Detailed information regarding the change being made

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.