Skip navigation.
Downloads | Product Documentation | Support

Developing Security Providers for WebLogic Server

# Auditing Events From Custom Security Providers

As described in Auditing 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 provide 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
- How to Audit From a Custom Security Provider

# Security Services and the Auditor Service

The `SecurityServices` interface, located in the `weblogic.security.spi` package, is a repository for security services (currently just the Auditor Service). As such, the `SecurityServices` interface is responsible for supplying callers with a reference to the Auditor Service via the following method:

  getAuditorService

  `public AuditorService getAuditorService`

  The `getAuditorService` method returns the `AuditService` if an Auditing provider is configured.

The `AuditorService` interface, also located in the `weblogic.security.spi` package, provides other types of security providers (for example, Authentication providers) with limited (write-only) auditing capabilities. In other words, the Auditor Service fans out invocations of each configured Auditing provider's `writeEvent` method, which simply writes an audit record based on the information specified in the `AuditEvent` object that is passed in. (For more information about the `writeEvent` method, see Implement the AuditChannel SSPI. For more information about `AuditEvent` objects, see Create an Audit Event.) The `AuditorService` interface includes the following method:

  providerAuditWriteEvent

  `public void providerAuditWriteEvent (AuditEvent event)`

  The `providerAuditWriteEvent` method gives security providers write access to the object in the WebLogic 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 Create an Audit Event and Audit Severity, respectively.

The Auditor Service can be called to write audit events before or after those events have taken place, but does not maintain context in between pre and post operations. Security providers designed with auditing capabilities will need to obtain the Auditor Service as described in Obtain and Use the Auditor Service to Write Audit Events.

Notes: Implementations for both the `SecurityServices` and `AuditorService` interfaces are created by the WebLogic Security Framework at boot time if an Auditing provider is configured. (For more information about configuring Auditing providers, see Configure the Custom Auditing Provider Using the Administration Console.) Therefore, you do not need to provide your own implementations of these interfaces.

Additionally, `SecurityServices` objects are specific to the security realm in which your security providers are configured. Your custom security provider's runtime class automatically obtains a reference to the realm-specific `SecurityServices` object as part of its `initialize` method. (For more information, see Understand the Purpose of the "Provider" SSPIs.)

For more information about these interfaces and their methods, see the WebLogic Server 8.1 API Reference Javadoc for the SecurityServices interface and the AuditorService interface.

# How to Audit From a Custom Security Provider

Add auditing capability to your custom security provider by following these steps:

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

Examples for each of these steps are provided in Example: Implementation of the AuditRoleEvent Interface and Example: Obtaining and Using the Auditor Service to Write Role Audit Events, 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 into the MBean JAR File (MJF) for the custom security provider (that is, in addition to the other files that are required).

## Create an Audit Event

Security providers must provide information about the events they want audited, such as the type of event (for example, an authentication event) and the audit severity (for example, "error"). Audit Events contain this information, and can also contain any other contextual data that is understandable to a configured Auditing provider. To create an Audit Event, either:

- Implement the AuditEvent SSPI or
- Implement an Audit Event Convenience Interface

### Implement the AuditEvent SSPI

To implement the `AuditEvent` SSPI, provide implementations for the following methods:

  getEventType

  `public java.lang.String getEventType()`

  The `getEventType` method returns a string representation of the event type that is to be audited, which is used by the Audit Channel (that is, the runtime class that implements the `AuditChannel` SSPI). For example, the event type for the BEA-provided implementation is `"Authentication Audit Event"`. For more information, see Audit Channels and Implement the AuditChannel SSPI.

  getFailureException

  `public java.lang.Exception getFailureException()`

  The `getFailureException` method returns an `Exception` object, which is used by the Audit Channel to obtain audit information, in addition to the information provided by the toString method.

  getSeverity

  `public AuditSeverity getSeverity()`

  The `getSeverity` method returns the severity level value associated with the event type that is to be audited, which is 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.

  toString

  `public java.lang.String toString()`

  The `toString` method returns preformatted audit information to the Audit Channel.

For more information about the `AuditEvent` SSPI and these methods, see the WebLogic Server 8.1 API Reference Javadoc.

### Implement an Audit Event Convenience Interface

There are several subinterfaces of the `AuditEvent` SSPI that are provided for your convenience, and that can assist you in structuring and creating Audit Events.

Each of these Audit Event convenience interfaces can be used by an Audit Channel (that is, a runtime class that implements the `AuditChannel` SSPI) to more effectively determine the instance types of extended event type objects, for a certain type of security provider. For example, the `AuditAtnEvent` convenience interface can be used by an Audit Channel that wants to determine the instance types of extended authentication event type objects. (For more information, see Audit Channels and Implement the AuditChannel SSPI.)

The Audit Event convenience interfaces are:

- The AuditAtnEvent Interface
- The AuditAtzEvent and AuditPolicyEvent Interfaces
- The AuditMgmtEvent Interface
- The AuditRoleEvent and AuditRoleDeploymentEvent Interfaces

Note: It is recommended, but not required, that you implement one of the Audit Event convenience interfaces.

#### The AuditAtnEvent Interface

The `AuditAtnEvent` convenience interface helps Audit Channels to determine instance types of extended authentication event type objects.

To implement the `AuditAtnEvent` interface, provide implementations for the methods described in Implement the AuditEvent SSPI and the following methods:

  getUsername

  `public String getUsername()`

  The `getUsername` method returns the username associated with the authentication event.

  AtnEventType

  `public AtnEventType getAtnEventType()`

  The `AtnEventType` method returns an event type that more specifically 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 has been established using the supplied client username (requires kernal identity).

  `VALIDATEIDENTITY`—authenticity (trust) of the principals within the supplied subject has been validated.

  `USERLOCKED`—a user account has been locked because of invalid login attempts.

  `USERUNLOCKED`—a lock on a user account has been cleared.

  `USERLOCKOUTEXPIRED`—a lock on a user account has expired.

  toString

  `public String toString()`

  The `toString` method returns the specific authentication information to audit, represented as a string.

For more information about the `AuditAtnEvent` convenience interface and these methods, see the WebLogic Server 8.1 API Reference Javadoc.

#### The AuditAtzEvent and AuditPolicyEvent Interfaces

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

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

To implement the `AuditAtzEvent` or `AuditPolicyEvent` interface, provide implementations for the methods described in Implement the AuditEvent SSPI and the following methods:

  getSubject

  `public Subject getSubject()`

  The `getSubject` method returns the subject associated with the authorization event (that is, the subject attempting to access the WebLogic resource).

  getResource

  `public Resource getResource()`

  The `getResource` method returns the WebLogic resource associated with the authorization event that the subject is attempting to access.

For more information about these convenience interfaces and methods, see the WebLogic Server 8.1 API Reference Javadoc for the AuditAtzEvent interface or the AuditPolicyEvent interface.

#### The AuditMgmtEvent Interface

The `AuditMgmtEvent` convenience interface helps Audit Channels to determine instance types of extended security management event type objects, such as a security provider's MBean. It contains no methods that you must implement, but maintains the best practice structure for an Audit Event implementation.

Note: For more information about MBeans, see Security Service Provider Interface (SSPI) MBeans.

For more information about the `AuditMgmtEvent`convenience interface, see the WebLogic Server 8.1 API Reference Javadoc.

#### The AuditRoleEvent and AuditRoleDeploymentEvent Interfaces

The `AuditRoleDeploymentEvent` and `AuditRoleEvent` convenience interfaces help Audit Channels to 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.

Note: The difference between the `AuditRoleEvent` convenience interface and the `AuditRoleDeploymentEvent` convenience interface is that the latter only extends the `AuditEvent` interface. (It does not also extend the `AuditContext` interface.) For more information about the `AuditContext` interface, see Audit Context.

For more information about these convenience interfaces, see the WebLogic Server 8.1 API Reference Javadoc for the AuditRoleEvent interface or the AuditRoleDeploymentEvent interface.

### Audit Severity

The audit severity is the level at which a security provider wants audit events to be recorded. When the configured Auditing providers receive a request to audit, each will examine 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 will record the audit data.

Note: Auditing providers are configured using the WebLogic Server Administration Console. For more information, see Configure the Custom Auditing Provider Using the Administration Console.

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 `AuditChannel` SSPI implementation) through the `AuditEvent` object. The numeric severity value is to be used in logic, and the text severity value is to be used in the composition of the audit record output. For more information about the `AuditChannel` SSPI and the `AuditEvent` object, see Implement the AuditChannel SSPI and Create an Audit Event, respectively.

### Audit Context

Some of the Audit Event convenience interfaces extend the `AuditContext` interface to indicate that an implementation will also contain contextual information. This contextual information can then be used by Audit Channels. For more information, see Audit Channels and Implement the AuditChannel SSPI.

The `AuditContext` interface includes the following method:

  getContext

  `public ContextHandler getContext()`

  The `getContext` method returns a `ContextHandler` object, which is used by the runtime class (that is, the `AuditChannel` SSPI implementation) to obtain additional audit information. For more information about ContextHandlers, see ContextHandlers and WebLogic Resources.

### Example: Implementation of the AuditRoleEvent Interface

Listing 11-1 shows the `MyAuditRoleEventImpl.java` class, which is a sample implementation of an Audit Event convenience interface (in this case, the `AuditRoleEvent` convenience interface). This class includes implementations for:

- The four methods inherited from the `AuditEvent` SSPI: `getEventType`, `getFailureException`, `getSeverity` and `toString` (as described in Implement the AuditEvent SSPI).
- One additional method: `getContext`, which returns additional contextual information via the ContextHandler. (For more information about ContextHandlers, see ContextHandlers and WebLogic Resources.)

Note: The bold face code in Listing 11-1 highlights the class declaration and the method signatures.

Listing 11-1 MyAuditRoleEventImpl.java

>     package mypackage;

>     import javax.security.auth.Subject;
>     import weblogic.security.SubjectUtils;
>     import weblogic.security.service.ContextHandler;
>     import weblogic.security.spi.AuditRoleEvent;
>     import weblogic.security.spi.AuditSeverity;
>     import weblogic.security.spi.Resource;

>     /*package*/ class MyAuditRoleEventImpl implements AuditRoleEvent
>     {
>        private Subject subject;
>        private Resource resource;
>        private ContextHandler context;
>        private String details;
>        private Exception failureException;

>        /*package*/ MyAuditRoleEventImpl(Subject subject, Resource resource,
>           ContextHandler context, String details, Exception
>           failureException) {

>              this.subject = subject;
>              this.resource = resource;
>              this.context = context;
>              this.details = details;
>              this.failureException = failureException;
>        }

>        public Exception getFailureException()
>        {
>           return failureException;
>        }

>        public AuditSeverity getSeverity()
>        {
>           return (failureException == null) ? AuditSeverity.SUCCESS :
>              AuditSeverity.FAILURE;
>        }

>        public String getEventType()
>        {
>           return "MyAuditRoleEventType";
>        }

>        public ContextHandler getContext()
>        {
>           return context;
>        }

>        public String toString()
>        {
>           StringBuffer buf = new StringBuffer();
>           buf.append("EventType:" + getEventType() + "\n");
>           buf.append("\tSeverity: " +
>              getSeverity().getSeverityString());
>           buf.append("\tSubject: " +
>              SubjectUtils.displaySubject(getSubject());
>           buf.append("\tResource: " + resource.toString());
>           buf.append("\tDetails: " + details);

>           if (getFailureException() != null) {
>              buf.append("\n\tFailureException:" +
>                 getFailureException());
>           }

>           return buf.toString();
>        }

>     }

## 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 to return the Audit Service.

Note: Recall that a `SecurityServices` object is passed into a security provider's implementation of a "Provider" SSPI as part of the `initialize` method. (For more information, see Understand the Purpose of the "Provider" SSPIs.) An `AuditorService` object will only be returned if an Auditing provider has been configured.

2. Instantiate the Audit Event you created in Implement the AuditEvent SSPI and send it to the Auditor Service through the `AuditService.providerAuditWriteEvent` method.

### Example: Obtaining and Using the Auditor Service to Write Role Audit Events

Listing 11-2 illustrates how a custom Role Mapping provider's runtime class (called `MyRoleMapperProviderImpl.java`) would obtain the Auditor Service and use it to write out audit events.

Note: The `MyRoleMapperProviderImpl.java` class relies on the `MyAuditRoleEventImpl.java` class from Listing 11-1.

Listing 11-2 MyRoleMapperProviderImpl.java

>     package mypackage;

>     import javax.security.auth.Subject;
>     import weblogic.management.security.ProviderMBean;
>     import weblogic.security.SubjectUtils;
>     import weblogic.security.service.ContextHandler;
>     import weblogic.security.spi.AuditorService;
>     import weblogic.security.spi.RoleMapper;
>     import weblogic.security.spi.RoleProvider;
>     import weblogic.security.spi.Resource;
>     import weblogic.security.spi.SecurityServices;

>     public final class MyRoleMapperProviderImpl implements RoleProvider, RoleMapper
>     {

>        private AuditorService auditor;

>        public void initialize(ProviderMBean mbean, SecurityServices
>           services)
>        {
>           auditor = services.getAuditorService();
>           ...
>        }

>        public Map getRoles(Subject subject, Resource resource,
>           ContextHandler handler)
>        {
>           ...
>           if (auditor != null)
>           {
>              auditor.providerAuditWriteEvent(
>                 new MyRoleEventImpl(subject, resource, context,
>                 "why logging this event",
>                 null);                // no exception occurred
>           }
>           ...
>        }

>     }

Note: The code in Listing 11-2 shows an example of how to post audit events from a security provider's runtime class. You can also post audit events from management methods. For an example of posting audit events from management methods, see the Manageable Sample Authentication Provider, one of the sample security providers available under Code Samples: WebLogic Server on the dev2dev Web site.