Skip navigation.
Downloads | Product Documentation | Support

Developing Security Providers

# Auditing Events from Custom Security Providers

The sections covers the following topics:

- How Events are Audited
- Security Services and the Auditor Service
- Adding Auditing to a Custom Security Provider

# How Events are Audited

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. Auditing providers capture this electronic trail of computer activity.

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.

The following sections provide the background information you need to understand before adding auditing capability to your custom security providers, and provide step-by-step instructions for adding auditing capability to a custom security provider:

- Security Services and the Auditor Service
- Adding Auditing to a Custom Security Provider

# Security Services and the Auditor Service

The `SecurityServices` object passed to a provider during initialization allows providers to retrieve services from the Security Framework. One of these services is the auditor service which you can use in a custom provider to audit events.

The `SecurityServices` object implements the `weblogic.security.spi`.`SecurityServices` interface, which contains the `getAuditorService` method used to retrieve the auditor service.

The auditor service provides security providers with auditing capabilities, through the `providerAuditWriteEvent` method. The Security Framework forwards this event to the standard `writeEvent` of the audit channel. For more information about the `writeEvent` method, see Implement the AuditChannel SSPI. For more information about `AuditEvent` objects, see Creating an Audit Event on page 5-3.) The Auditor Service interface includes the `providerAuditWriteEvent` method, described in Table 5-1.

Table 5-1 providerAuditWriteEvent Method

Method | Description
--- | ---
providerAuditWriteEvent | The `providerAuditWriteEvent` method gives security providers write access to the object in the Security Framework that calls the configured Auditing providers. The `event` parameter is an `AuditEvent` object that contains the audit criteria, including the type of event to audit and the audit severity level. For more information about Audit Events and audit severity levels, see Creating an Audit Event on page 5-3 and Audit Severity and the AuditSeverity Class on page 5-7, respectively.

Security providers designed with auditing capabilities need to obtain the Auditor Service as described in Obtain and Use the Auditor Service to Write Audit Events on page 5-8.

# Adding Auditing to a Custom Security Provider

To add auditing capability to your custom security provider, perform the following tasks:

- Creating an Audit Event
- Obtain and Use the Auditor Service to Write Audit Events

Examples for each of these tasks are provided in Example: Implementation of the AuditRoleEvent Interface on page 6-21 and Example: Obtaining and Using the Auditor Service to Write Role Audit Events on page 6-23, respectively.

Note: If your custom security provider is to record audit events, be sure to include any classes created as a result of these steps in the MBean JAR File for the custom security provider (that is, in addition to the other files that are required).

## Creating an Audit Event

Security providers must provide information about the events you want audited, such as the type of event and the audit severity. Audit Events contain this information and other contextual data that is understandable to a configured Auditing provider. For information on how to create an Audit Event, see the following sections:

- Implementing the AuditEvent SSPI
- Implementing an AuditEvent Interface
- Implement the Provider Audit Record (described in Using the ProviderAuditRecord Interface on page 3-8)

In addition to the procedures for creating an audit event, the section covers the following topics:

- Audit Severity and the AuditSeverity Class
- AuditContext Interface

### Implementing the AuditEvent SSPI

To implement the AuditEvent SSPI, provide implementations for the methods described in Table 5-2.

Table 5-2 AuditEvent SSPI Methods

Method | Description
--- | ---
`getEventType` | The `getEventType` method returns a string representation of the event type being audited, as used by the Audit Channel (that is, the runtime class that implements the Audit Channel SSPI). For example, the event type for the BEA-provided implementation is "`Authentication Audit Event`". For more information, see Audit Channels on page 2-13 and Implement the AuditChannel SSPI on page 4-20.
`getFailureException` | The `getFailureException` method returns an `Exception` object used by the Audit Channel to obtain audit information, in addition to the information provided by toString on page 5-5.
`getSeverity` | The `getSeverity` method returns the severity level value associated with the event type being audited, as used by the Audit Channel. This allows the Audit Channel to make the decision about whether or not to audit. For more information, see Audit Severity and the AuditSeverity Class on page 5-7.
`toString` | The `toString` method returns pre-formatted audit information to the Audit Channel.

### Implementing an AuditEvent Interface

There are several sub-interfaces of the AuditEvent SSPI that are provided for your convenience, and that can assist you in structuring and creating Audit Events. An Audit Channel can use each of these interfaces (that is, a runtime class that implements the Audit Channel SSPI), to more effectively determine the instance types of extended event type objects for a certain type of security provider. For example, the an Audit Channel can use the `AuditAtnEvent` interface to determine the instance types of extended authentication event type objects. For more information, see Audit Channels on page 2-13 and Implement the AuditChannel SSPI on page 4-20. It is recommended, but not required, that you implement one of the Audit Event interfaces.The following sections provide information on how to implement the Audit Event interfaces:

- AuditAtnEvent Interface
- AuditAtzEvent and AuditPolicyEvent Interfaces
- AuditMgmtEvent Interface

#### AuditAtnEvent Interface

The `AuditAtnEvent` interface helps Audit Channels determine instance types of extended authentication event type objects. To implement the `AuditAtnEvent` interface, provide implementations for the methods described in Table 5-2 and the `AuditAtnEvent` interface methods, described in Table 5-3.

Table 5-3 AuditAtnEvent Interface Methods

Method | Description
--- | ---
`getUsername` | The `getUsername` method returns the username associated with the authentication event.
`AtnEventType` | The `AtnEventType` method returns an event type that represents the authentication event. The specific authentication event types are: `AUTHENTICATE`—simple authentication using a username and password occurred. `ASSERTIDENTITY`—perimeter authentication based on tokens occurred. `IMPERSONATEIDENTITY`—client identity was established using the supplied client username. `VALIDATEIDENTITY`—authenticity (trust) of the principals within the supplied subject was validated. `USERLOCKED`—a user account was locked because of invalid login attempts. `USERUNLOCKED`—a lock on a user account was cleared. `USERLOCKOUTEXPIRED`—a lock on a user account expired.
`toString` | The `toString` method returns the specific authentication information to audit, represented as a string.

Note: The `AuditAtnEvent` convenience interface extends both the `AuditEvent` and `AuditContext` interfaces. For more information about the `AuditContext` interface, see AuditContext Interface.

#### AuditAtzEvent and AuditPolicyEvent Interfaces

The `AuditAtzEvent` and `AuditPolicyEvent` interfaces help Audit Channels determine instance types of extended authorization event type objects.

Note: The difference between the `AuditAtzEvent` interface and the `AuditPolicyEvent` interface is that the latter only extends the `AuditEvent` interface. It does not extend the `AuditContext` interface. For more information about the `AuditContext` interface, see AuditContext Interface.

To implement the `AuditAtzEvent` or `AuditPolicyEvent` interface, provide implementations for the methods described in Table 5-2 and the `AuditPolicyEvent` interface methods, described in Table 5-4. To implement the AuditAtzEvent interface, you must also provide implementation for the methods defined by the AuditContext interface (see AuditContext Interface on page 5-8).

Table 5-4 AuditPolicyEvent interface Methods

Method | Description
--- | ---
`getSubject` | The `getSubject` method returns the subject associated with the authorization event (that is, the subject attempting to access the resource).
`getResource` | The `getResource` method returns the resource associated with the authorization event the subject is attempting to access.

#### AuditMgmtEvent Interface

The `AuditMgmtEvent` interface helps Audit Channels determine instance types of extended security management event type objects. You must implement the methods described in Table 5-2.

#### AuditRoleEvent Interface

The `AuditRoleEvent` interface helps Audit Channels determine instance types of extended role mapping event type objects. They contain no methods that you must implement, but maintain the best practice structure for an Audit Event implementation. You must implement the methods described in Table 5-2 and Table 5-6 as described in AuditContext Interface on page 5-8).

#### AuditCredentialMappingEvent

The `AuditCredentialMappingEvent` interface helps Audit Channels determine instance types of credential mapping event type objects. You must implement the methods described in Table 5-5.

Table 5-5 AuditCredentialMappingEvent Interface Methods

Method | Description
--- | ---
`getCredentialTypes` | Gets the string array of credential types requested in the getCredential operation associated with this AuditCredentialMappingEvent.
`getInitiatorString` | Gets the initiator of the getCredential operation associated with this AuditCredentialMappingEvent.
`getInitiatorSubject` | Gets the subject of the initiator of the getCredential operation associated with this AuditCredentialMappingEvent.
`getRequestorSubject` | Gets the requestor subject of the getCredential operation associated with this AuditCredentialMappingEvent.
`getResource` | Gets the resource of the getCredential operation associated with this AuditCredentialMappingEvent

#### AuditRoleDeploymentEvent

The `AuditRoleDeploymentEvent` provides a convenience interface for Auditing providers to determine the instance types of extended `AuditEvent` type objects. You must implement the methods described in Table 5-2.

### Audit Severity and the AuditSeverity Class

The audit severity is the level at which a security provider wants to record audit events. When a configured Auditing provider receive a request to audit, it examines the severity level of events taking place. If the severity level of an event is greater than or equal to the level an Auditing provider was configured with, that Auditing provider records the audit data.

The `AuditSeverity` class, which is part of the `weblogic.security.spi` package, provides audit severity levels as both numeric and text values to the Audit Channel (that is, the Audit Channel SSPI implementation) through the `AuditEvent` object. The numeric severity value is used in logic, and the text severity value is used in the composition of the audit record output. For more i

nformation about the Audit Channel SSPI and the `AuditEvent` object, see Implement the AuditChannel SSPI and Creating an Audit Event on page 5-3, respectively.

### AuditContext Interface

Some of the Audit Event interfaces extend the AuditContext interface to indicate that an implementation also contains contextual information. This contextual information can then be used by Audit Channels. For more information, see Audit Channels on page 2-13 and Implement the AuditChannel SSPI on page 4-20. The Audit Context interface includes the `getContext` method, described in Table 5-6.

Table 5-6 AuditContext Interface Method

Method | Description
--- | ---
`getContext` | The `getContext` method returns a `ContextHandler` object used by the runtime class (that is, the Audit Channel SSPI implementation) to obtain additional audit information. For more information about ContextHandlers, see ContextHandler Object on page 5-8.

## Obtain and Use the Auditor Service to Write Audit Events

To obtain and use the Auditor Service to write audit events from a custom security provider, follow these steps:

1. Use the `getAuditorService` method on the `SecurityServices` object to return the Audit Service.

Note: Recall that a `SecurityServices` object is passed into a security provider implementation of a "Provider" SSPI as part of the `initialize` method. (For more information, see Table 3-1.) An `AuditorService` object is only returned if an Auditing provider is configured.

2. Instantiate the Audit Event you created in Implementing the AuditEvent SSPI on page 5-3 and send it to the Auditor Service through the `AuditService.providerAuditWriteEvent` method.

## ContextHandler Object

A `ContexHandler` is a class interface that obtains additional context and container-specific information from a resource container, and provides that information to security providers making access or role mapping decisions. The `ContextHandler` interface provides a way for an internal 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 that a security provider 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 included with some event types to allow an audit provider to extract other information about the state of the application server at the time of the audit event. The auditing 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.