Developing Security Providers

Auditing Events from Custom Security Providers

The sections covers the following topics:

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

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.

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:

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:

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

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.

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:

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.

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.