Auditing Events from Custom Security 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. 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

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 6-3.) The Auditor Service interface includes the providerAuditWriteEvent method, described in Table 6-1.

Table 6-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 6-3 and Audit Severity and the AuditSeverity Class on page 6-7, respectively.

Adding Auditing to a Custom Security Provider

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

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:

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

Implementing the AuditEvent SSPI

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

Table 6-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 3-15 and "Implement the AuditChannel SSPI" on page 5-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 6-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 6-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 3-15 and "Implement the AuditChannel SSPI" on page 5-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

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 6-2 and the AuditAtnEvent interface methods, described in Table 6-3.

Table 6-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.

AuditAtzEvent and AuditPolicyEvent Interfaces

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

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

Table 6-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 6-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 6-2 and Table 6-6 as described in AuditContext Interface on page 6-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 6-5.

Table 6-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 6-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

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 3-15 and "Implement the AuditChannel SSPI" on page 5-20. The Audit Context interface includes the getContext method, described in Table 6-6.

Table 6-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 6-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:

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 4-1.) An AuditorService object is only returned if an Auditing provider is configured.

Instantiate the Audit Event you created in Implementing the AuditEvent SSPI on page 6-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.

Best Practice: Posting Audit Events from a Provider's MBean

Provider's management operations that do writes (for example, create user, delete user, remove data) should post audit events, regardless of whether or not the operation succeeds.

If your provider audits MBean operations, you should keep the following Best Practice guidelines

If the write operation succeeds, post an INFORMATION audit event.
If the write operation fails because of a bad parameter (for example, because the user already exists, or due to a bad import format name, a non-existent file name, or the wrong file format), do not post an audit event.
If the write operation fails because of an error (for example, LDAPException, RuntimeException), post a FAILURE audit event.
Import operations can partially succeed. For example, some of the users are imported, but others are skipped because there are already users with that name in the provider.
If you can easily detect that the data you are skipping is identical to the data already in the provider (for example, the username, description, and password are the same) then consider posting a WARNING event.
If you are skipping data because there is a partial collision (for example, the username is the same but the password is different), you should post a FAILURE event.
If it is too difficult to distinguish the import data from the data already stored in theprovider, post a FAILURE event.

Developing Security Providers