|
|
The following topics are covered in this section:
The AuditEvent interface provides a mechanism for passing additional audit information to Auditing providers during a writeEvent operation. This is the base interface that is extended by components in the Security Framework to compose specific audit event types. Extending this interface helps auditing providers determine the calling security component.
If you implement this interface and you expect to receive a ContextHandler argument from a caller, you can extend the AuditContext interface to provide more information.
Some of the sub-interfaces defined by the security SPI are listed in Table 4-1. Table 4-1 also indicates which sub-interfaces implement the AuditContext interface. These interfaces are documented in the BEA AquaLogic Enterprise Security Provider SSPI API Reference.
Table 4-2 lists WebLogic 9.x audit events.
The providers implement the appropriate AuditEvent interfaces and post those events to the Audit provider. The AuditEvents that also implement the AuditContext interface can provide more information via a ContextHandler.
The ContextHandler interface provides a way for an internal WebLogic container to pass additional information to a WebLogic Security Framework call, so that a security provider can obtain additional context information beyond what is provided by the arguments to a particular method. A ContextHandler is essentially a name/value list. The name/value list is also called a context element, and is represented by a ContextElement object.
Depending on the interface that the AuditEvent has implemented, different information is audited. For all audit events, the toString() method is called on the event and that string is audited. Some audit events have a ContextHandler, such as the AuditAtzEvent and AuditRoleEvent, in which case the context is audited in addition to calling the toString() method on the AuditEvent. You can have many ContextElements, but each NAME/VALUE pair must be iterated over and audited.
The Log4j Audit Channel provider ships with Log4j renderers that are aware of these interfaces and know how to extract the appropriate audit information. You can change this behavior by writing custom renderers and updating the Custom Log4j Renderer Properties text box on the Advanced tab for the Log4j Auditor page in the Administration Console. A custom renderer is useful if only a particular subset of context elements are required or if the default style of audit events needs to be changed.
Each audit record has the following format:
2004-04-22 12:21:55,833 [Thread-27] SUCCESS ASI_AUDIT-My Custom Event-Custom Event msg -- <attr1 = value1><attr2 = value2>
A custom renderer may require square brackets [] instead of angle brackets <>.
To be audited, you can select which severity the audit event must equal or be greater than; and you can select the types of AuditEvents by setting the Custom Audit Events attribute. If an AuditEvent implements or is an instance of any of the classes listed, then you can audit it. Only new custom events need to be listed here. The default events already exist and are controlled by selecting either: DISABLED, WITH_CONTEXT, or WITHOUT_CONTEXT on the Details tab for the Log4j Auditor page in the Administration Console. For a list of audit events, see Audit Events.
| Note: | Printing the entire context by enabling WITH_CONTEXT can be an expensive task and is proportional to the number of context elements contained in the ContextHandler. |
All audit events generated through the Java API are called through the Provider Audit Records interface using the AuditRecord method. This includes PolicyAdministrationEvent and ARMEAuthorizationEvent. A PolicyAdministrationEvent is generated when a policy change is made through the Administration Console. An ARMEAuthorizationEvent is generated when the ARME makes a authorization request for a policy change.
All audit events can be DISABLED or WITHOUT_CONTEXT. For those that have context, you can select WITH_CONTEXT. The AuditAtzEvents have more options then all the other types, you can select the events to audit based on the following options:
DISABLE—No auditing occurs. WITHOUT_CONTEXT—Audits what is in the event message.WITH_REQUEST_CONTEXT—Audits the event message plus the request context.WITH_RESPONSE_CONTEXTS—Audits the event message plus all the response contexts. Only contains the context that was populated with responses from the ASI Authorization provider. There can be many contexts returned for a single query and hence the CONTEXTS.WITH_ALL_CONTEXTS—Audits the event message plus all the contexts (request as well as response contexts).
The Log4J Audit Channel provider is used to audit events that are generated by the Security Framework, the runtime API, or custom implementations based on the weblogic.security.spi.AuditEvent interface AuditEvent class.
Audit plug-ins can be used to audit with minimal awareness of the audit data formats being passed in by the calling Security Framework component. Additionally, Log4j plug-ins written or supplied by third parties can implement actions (such as paging security personal) based on audit severity/criteria you set in the Log4j Audit Channel provider Details tab in the Administration Console. Some general descriptions or suggestions for the information suitable for auditing by AuditEvent are as follows:
weblogic.security.spi.AuditEvent interface that defines the minimum requirements for an audit event. This interface includes type, severity, toString(), and, if there was an exception associated with the event, a reference to the exception.AuditEvent interface, several additional interfaces are defined to further elaborate on the audit types, and, for providers that need to retrieve audit properties that are specific to the audit type, interfaces exist that allow the providers to extract these values.AuditEvent class and to use toString to output its representation of the event as a String.
In this release of AquaLogic Enterprise Security, the BLM API has been enhanced to allow you to send an Application Context to the auditing service.
An Audit Context is a name=value pair data structure that contains additional audit data that is made available to the Audit provider. Like the Audit Context, the Application Context is also a name=value pair data structure, and it contains additional application-specific audit data that is appended to the Audit Context when audit messages are written.
This additional information can be used by a custom Audit provider. Note, however, that the default Log4j Audit provider does not use this additional context.
When you create the Application Context, it is reused for each audit message associated with this BLM Context until it is overwritten by a call to set it, or you clear it.
The following BLM API methods have been added to provide for the Application Context:
BLMManager.create(java.util.Hashtable credentials, java.util.Hashtable appCtx). This method creates an instance of the BLMContextManager and initializes the BLMContextManager with an Application Context. The BLM then adds the Application Context data to all auditing messages associated with this BLM Context sent to the Audit provider.
BLMContextManager.setApplicationContext(Hashtable appCtx). This method replaces an existing application context with the new one provided. (You must have called BLMManager.create(java.util.Hashtable credentials, java.util.Hashtable appCtx) method prior to calling setApplicationContext(Hashtable appCtx). All subsequent audit messages associated with this BLM Context have the Application Context added to them when they are sent to the Audit provider.
BLMContextManager.clearApplicationContext(). This method clears the Application Context associated with this BLM Context so that it is no longer included with audit messages sent to the Audit provider.
In the security provider interface package, WebLogic Security defines one top-level base interface (AuditEvent) with different derived interfaces that represent the different types of audit events.
The following sections describe when the security framework and security providers post seven major types of audit events:
For a list of the events that are audited for the default Admin policy, see Admin Policy Audit Events.
Authentication audit events are posted by the security framework. Table 4-3 describes the conditions under which the event is posted and severity level of the event.
Authorization audit events are posted by the security framework. Table 4-4 describes the conditions under which the events are posted and severity level of the event.
Credential Mapping audit events are posted by the security framework. Table 4-5. describes the condition under which the events are posted and severity level of the event.
Management audit events are not currently posted by either the security framework or by the supplied providers.
AuditPolicyEvent are posted by the security framework and the WebLogic Authorization provider. The security framework posts audit policy events when policies are deployed to or undeployed from an authorization provider. The WebLogic Server authorization provider posts audit policy events when creating, deleting, or updating policies. Table 4-6 describes the conditions under which the events are posted and lists the event severity level.
The security framework posts audit role deployment events when roles are deployed to or undeployed from a role mapping provider. Table 4-7 describes the conditions under which the events are posted and lists the event severity level.
The WebLogic Role Mapping provider posts audit role events when roles are created, deleted, or updated. Table 4-8 describes the conditions under which the events are posted and lists the event severity level.
Table 4-9 lists and describes the administration policy events that are audited.
The following sections describe additional audit event interfaces:
The AuditAtnEvent interface provides an interface for audit providers to determine the instance types of the extended authentication event type objects. Table 4-10 describes the event properties.
When this event is generated, the following information associated with this AuditAtnEvent is available:
There are both pre- and post-authorization access control checks; each of which generates pre- and post-operation audit write events. The AuditAtzEvent event interface is used to report events that result when access is allowed on a resource. The Audit Channel provider is called on both the pre- and post-operation cases. The exceptions reported using this event must derive from the java.security.GeneralSecurityException.
When this event is generated, the following information associated with this AuditAtzEvent is available:
The resource container that handles the type of resource requested (for example, in WebLogic Server, the EJB container receives the request for an EJB resource) constructs a ContextHandler object that may be used by an authorization provider Access Decision to obtain information associated with the context of the request. This ContextHandler object is also available with this AuditAtzEvent. For more information about the ContextHandler object, see ContextHandler Object.
The AuditPolicyDeployEvent event interface is used when the Authorization Manager deployPolicy method is called. When this event is generated, the following information is available:
The AuditPolicyUndeployEvent event interface is used when the Authorization Manager undeployPolicy method is called. When this event is generated, the following information is available:
The exception that occurred (if any) while attempting to carry out this action. Typically, there is only an exception if the severity is error or failure.
The AuditPolicyEvent event interface determines the instance types of extended Authorization event type objects. Table 4-11 describes the event subtypes.
The AuditRoleEvent event provides an interface for auditing providers to determine the instance types of extended Role Mapping event type objects. Table 4-12 describes the event subtypes.
When an AuditRoleEvent is generated, the following information is available:
The resource container that handles the type of resource being requested (for example, with WebLogic Server, the EJB container receives the request for an EJB resource) constructs a ContextHandler object that may be used by an Authorization provider Access Decision to obtain information associated with the context of the request. This ContextHandler object is also available with this AuditAtzEvent. For more information about the ContextHandler object, see ContextHandler Object.
The AuditRoleDeployEvent event provides a interface used by the role mapping service to determine the instance types of extended Role Mapping deployment event type objects.
The AuditRoleUndeployEvent event provides a interface used by the role mapping service to determine the instance types of extended Role Mapping undeployment event type objects.
The AuditPredicateEvent event provides a interface for auditing providers to determine the instance type of extended predicate event type objects. A predicate event occurs when a policy expression is either registered or unregistered in the Administration Console. Table 4-13 describes the event subtypes.
A ContextHandler is a class that obtains additional context and container-specific information from the resource container, and provides that information to security providers making access or role mapping decisions. The ContextHandler interface provides a way for an application or 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 a security provider to 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 an object that is included with some event types that allows an audit provider to extract other information about the state of the application server at the time of the audit event. The audit 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.
The PolicyAdministrationEvent event is used when AquaLogic Enterprise Security policy is modified or deployed using the AquaLogic Enterprise Security Administration console or bulk loader. When this event is generated, the following information is available:
The exception that occurred (if any) while attempting to carry out this action. Typically, there will only be an exception if the severity is error or failure.
You can use a custom auditing provider instead of the Log4j Audit Channel provider. For a custom auditing provider to be configurable through the Administration Console, the MBean JAR file for the provider must be installed into the BEA_HOME..//lib/providers directory on both the machine on which the Administration Application is installed and on the machine on which the Security Service Module is installed. For complete instructions for configuring a custom security provider, see Configuring a Custom Security Provider in the Console Help.
|