bea.com | products | dev2dev | support | askBEA |
|
e-docs > WebLogic Server > Developing Security Providers for WebLogic Server > Auditing Events From Custom Security Providers |
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 (to which they have legitimate access) in a bank account application, but attempts to withdraw an amount over the maximum that is allowable for such a transaction, the Authorization provider can request that both operations (the initial access and the exceeded limit error) be recorded. As this example also illustrates, security providers can specify which types of events they would like recorded, and the specific conditions under which these events should be recorded.
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 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:
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:
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 7.0 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:
Examples for each of these steps are provided in Example: Implementation of the AuditAtnEvent Interface and Example: Obtaining and Using the Auditor Service to Write Authentication 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).
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:
To implement the AuditEvent SSPI, provide implementations for the following methods:
For more information about the AuditEvent SSPI and these methods, see the WebLogic Server 7.0 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:
Note: It is recommended, but not required, that you implement one of the Audit Event convenience interfaces.
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:
Note: The AuditAtnEvent convenience interface extends both the AuditEvent and AuditContext interfaces. For more information about the AuditContext interface, see Audit Context.
For more information about the AuditAtnEvent convenience interface and these methods, see the WebLogic Server 7.0 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:
For more information about these convenience interfaces and methods, see the WebLogic Server 7.0 API Reference Javadoc for the AuditAtzEvent interface or the AuditPolicyEvent 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 AuditMgmtEventconvenience interface, see the WebLogic Server 7.0 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 7.0 API Reference Javadoc for the AuditRoleEvent interface or the AuditRoleDeploymentEvent interface.
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.
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:
Example: Implementation of the AuditAtnEvent Interface
Listing 11-1 shows the MyAuditAtnEventImpl.java class, which is a sample implementation of an Audit Event convenience interface (in this case, the AuditAtnEvent convenience interface). This class includes implementations for:
Note: The bold face code in Listing 11-1 highlights the class declaration and the method signatures.
Listing 11-1 MyAuditAtnEventImpl.java
import weblogic.security.spi.AuditAtnEvent;
import weblogic.security.spi.AuditSeverity;
public class MyAuditAtnEventImpl implements AuditAtnEvent
{
private AuditSeverity severity;
private String eventType;
private Exception exception;
private ContextHandler context;
private String myAuditText;
public MyAuditAtnEventImpl(AuditSeverity severity, String eventType)
{
this.severity = severity;
this.eventType = eventType;
}
public void setFailureException(Exception exception)
{
this.exception = exception;
}
public Exception getFailureException()
{
return exception;
}
public AuditSeverity getSeverity()
{
return severity;
}
public String getEventType()
{
return eventType;
}
public void setContext(ContextHandler context)
{
this.context = context;
}
public ContextHandler getContext()
{
return context;
}
public void setAuditData(String auditText)
{
this.myAuditText = auditText;
}
public String toString()
{
StringBufer buf = new StringBuffer();
buf.append("<");
buf.append("myAuditText");
buf.append(">");
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:
Notes: 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.
Example: Obtaining and Using the Auditor Service to Write Authentication Audit Events
Listing 11-2 illustrates how a custom Authentication provider's runtime class (called MyAuthenticationProviderImpl.java) would obtain the Auditor Service and use it to write out audit events.
Note: The MyAuthenticationProviderImpl.java class relies on the MyAuditAtnEventImpl.java class from Listing 11-1.
Listing 11-2 MyAuthenticationProviderImpl.java
import weblogic.security.spi.SecurityServices;
import weblogic.security.spi.AuditorService;
public class MyAuthenticationProviderImpl implements AuthenticationProvider
{
private AuditorService auditor = null;
public initialize (ProviderMBean mBean, SecurityServices securityServices)
{
// ...initialization information
auditor = securityServices.getAuditorService();
}
myAuthenticationMethod()
{
if (auditor != null)
// ...an Auditor object is configured
{
MyAuditAtnEventImpl myAuditEvent = new MyAuditAtnEventImpl(severity,
eventType);
myAuditEvent.setAuditData("myAtnAuditTextRecord");
auditor.providerAuditWriteEvent(myAuditEvent);
}
else
{
// handle Auditor not configured condition
}
}
}