|
|
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 8-1. This table also indicates the sub-interfaces that implement the AuditContext interface. These interfaces are documented in the
Security Provider SSPI API Reference.
Table 8-2 lists WebLogic 9.x audit events.
Typically, the audit providers implement the weblogic.security.spi.AuditChannel interface and the weblogic.security.spi.AuditProvider interface, and post events
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 ASIAuthorizer 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.
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 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) 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.
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 some prominent types of audit events:
For a list of the events that are audited for the default Admin policy, see BLM Management Events.
Authentication audit events are posted by the security framework. Table 8-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 8-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 8-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 8-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 8-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 8-8 describes the conditions under which the events are posted and lists the event severity level.
Table 8-9 lists and describes the BLM management events that are audited.
Table 8-10 indicates the Auditbase events posted by the PD during policy distribution.
As indicated in Table 8-11, the adminstration console posts distribution status request events after user distributes policy from console and distribution result page is rendered.
As indicated in Table 8-12, the administration console posts distribution events when user distributes structural change from console.
When OOTB ALES log4j Audit Provider is configured, following message can be found in secure_audit.log, text in bold is event type:
2008-08-26 11:16:46,712 [JettySSLListener1-1] SUCCESS ASI_AUDIT -
BLMManagementEvent -- BLMManagementEvent/SUCCESS/Created, grant,
//role/Admin, //app/policy/ASIRecovery, //user/asi/bbb/, , true,
R...
2008-08-26 11:17:10,368 [[ACTIVE] ExecuteThread: '0' for queue:
'weblogic.kernel.Default (self-tuning)'] INFORMATION ASI_AUDIT - Policy
Distribution -- Policy was distributed for the following resources
2008-08-26 11:17:10,384 [[ACTIVE] ExecuteThread: '0' for queue:
'weblogic.kernel.Default (self-tuning)'] INFORMATION ASI_AUDIT -
Policy Distribution -- //app/policy
2008-08-26 11:17:10,415 [[ACTIVE] ExecuteThread: '0' for queue:
'weblogic.kernel.Default (self-tuning)'] INFORMATION ASI_AUDIT -
Distribution Status Request -- Distribution Status :
10,//user/asi/system/,10,computing update,Tue Aug 26 11:17:10 CST 2008
2008-08-26 11:17:10,493 [[ACTIVE] ExecuteThread: '0' for queue:
'weblogic.kernel.Default (self-tuning)'] INFORMATION ASI_AUDIT -
Distribution Status Request -- Distribution Status :
8,//user/asi/system/,100,distribution done,Tue Aug 26 10:44:07 CST 2008
Distribution Result(ARME.admin.server.asi.cding02, //bind/asiadmin,
cding02, true)
2008-08-26 11:17:10,509 [[ACTIVE] ExecuteThread: '0' for queue:
'weblogic.kernel.Default (self-tuning)'] INFORMATION ASI_AUDIT -
Distribution Status Request -- Distribution Status :
7,//user/asi/system/,100,distribution done,Tue Aug 26 10:41:18
CST 2008
...
2008-08-26 11:17:12,493 [Thread-28] SUCCESS ASI_AUDIT - AUDITBASE --
AUDITBASE/SUCCESS/PD, performing sendBeginPolicyUpdate operation to
ARME.admin.server.asi.cding02 with policy id 9 succeeded.
2008-08-26 11:17:12,493 [Thread-28] SUCCESS ASI_AUDIT - AUDITBASE --
AUDITBASE/SUCCESS/PD, performing prepareToCommit operation to
ARME.admin.server.asi.cding02 with policy id 10 succeeded.
2008-08-26 11:17:12,493 [Thread-28] SUCCESS ASI_AUDIT - AUDITBASE --
AUDITBASE/SUCCESS/PD, performing commit operation to
ARME.admin.server.asi.cding02 with policy id 10 succeeded.
2011-03-30 12:19:12,877 [JettySSLListener1-1] SUCCESS AUDITBASE -
AUDITBASE -- AUDITBASE/SUCCESS/PD, accepting the initial policy request
from ARME.admin.server.asi.VPOPIC-LAP with policy id 2 succeeded.
2011-03-30 14:35:00,717 [JettySSLListener1-1] SUCCESS AUDITBASE -
AUDITBASE -- AUDITBASE/SUCCESS/PD, processing async policy distribution
request with distribution tracking id 4201 succeeded.
2011-03-30 14:42:19,581 [JettySSLListener1-1] FAILURE AUDITBASE -
AUDITBASE -- AUDITBASE/FAILURE/PD, processing async policy distribution
request failed.
2011-03-30 14:35:07,748 [JettySSLListener1-1] FAILURE AUDITBASE -
AUDITBASE -- AUDITBASE/FAILURE/PD, processing async structural change
distribution request failed.
2011-03-30 14:48:40,648 [JettySSLListener1-1] SUCCESS AUDITBASE -
AUDITBASE -- AUDITBASE/SUCCESS/PD, enqueuing distribution request with
distribution tracking id 4214 succeeded.
This interface is defined in the Security Provider SSPI package and provides an extended version of the AuditEvent. Refer to Security Provider SSPI API Reference for full documentation of this interface. The SSPI package includes specific interfaces, classes, and exceptions for developing security providers.
Providers written to work in both the WLS Security Framework and the Security Providers environments must handle both WebLogic audit records and extended AuditEvents. Examples of extended AuditEvents are subinterfaces and implementations of ProviderAuditRecord interface.
In the providers, the instanceof operator can be used to distinguish between the WLS Security Framework interfaces and Oracle Entitlements Server interfaces. For example:
if ( myauditrecord instanceof com.bea.security.spi.ProviderAuditRecord){// This is an audit record that uses the enhanced SSPI.
} else {
// This is a WLS audit record. You must test further for more object
// types and handle them explicitly.
}
A simple audit provider can use the toString() method to render the audit record as a string; the provider does not require specific knowledge of the audit record type. A more complex auditing provider that tracks events by many keys and needs to distinguish messages by various types and attributes requires a data-driven method of event introspection. The complex auditing provider can get an enumeration of com.bea.security.spi.NameValueTypes that contain this audit record's name fields using the ProviderAuditRecord.getEnumeration() and ProviderAuditRecord.getDeepEnumeration() methods.
Additionally, the ProviderAuditRecord interface can associate an application context with an audit event. This allows the auditing provider to select some context elements to audit when events occur. For example, when an audit event occurs, you may choose to audit the number of concurrent sessions, the time the user logged on, or some other application-specific value propagated by the application context.
The following code fragment shows how a custom provider can access the context added by a client application. The modification is primarily in the writeEvent method, as shown.
public void writeEvent(AuditEvent event){
// write the event out to the sample auditor's
// log file using the event's "toString" method.
// followed by the string version of the application
// context name value pairs.
ProviderAuditRecord par = (ProviderAuditRecord) event;
ContextHandler ch = par.getContext();
String[] names = ch.getNames();
StringBuffer ctxReader = new StringBuffer();
for ( int i=0; i < names.length; i++ ) {
String value = (String) ch.getValue(names[i]);
ctxReader.append(names[i]).append("=").append(value);
}
log.println(event + “Context = “ + ctxReader.toString());
}
This section describes some of the other AuditEvents used by the security framework and security providers.
Table 8-13 describes the conditions under which the event is posted and severity level of the event.
These events are posted by the CertPathBuilder providers.
Life cycle audit events are posted by the WLS framework, as follows:
Some implementations of the AuditEvent interface contain additional information that can be accessed by the providers and security framework. All interfaces that extend the weblogic.security.spi.AuditEvent interface or all the implementations of that interface have the following information available:
The following sections provide additional information about specific audit events:
The AuditAtnEvent interface provides an interface for audit providers to determine the instance types of the extended authentication event type objects. Table 8-15 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 to a resource. The Audit Channel provider is called both prior to and after the authorization operation.
This event has the following information available:
ContextHandler object. 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 for making the access decisions.
The AuditCredentialMappingEvent interface is used to post credential mapping audit events when credentials for a WebLogic Server user are requested, or when credentials for any subject are requested. The following information is available with this event:
The AuditPolicyEvent interface determines the instance types of extended Authorization event type objects. Table 8-16 describes the event subtypes.
The AuditPolicyDeployEvent is type of a AuditPolicyEvent used when the Authorization Manager deployPolicy method is called. When this event is generated, the following information is available:
The AuditPolicyUndeployEvent is type of a AuditPolicyEvent used when the Authorization Manager undeployPolicy method is called. When this event is generated, the same information as listed for the AuditPolicyEvent is available.
The AuditRoleEvent event provides an interface for auditing providers to determine the instance types of extended Role Mapping event type objects.
When an AuditRoleEvent is generated, the following information is available:
AuditRoleEvent. AuditRoleEvent.
The AuditRoleDeploymentEvent provides an interface for auditing providers to determine the instance types of extended Role deployment event type objects. Table 8-17 describes the event subtypes.
The AuditRoleDeployEvent event is used by the role mapping service to determine the instance types of extended Role Mapping deployment event type objects. In addition to the information listed by the AuditEvent interface, this event also has following additional information:
The AuditRoleUndeployEvent event is used by the role mapping service to determine the instance types of extended Role Mapping undeployment event type objects. In addition to the information listed by the AuditEvent interface, this event also has the following additional information:
In addition to the information listed by the AuditEvent interface, this event also provides the following additional information:
In addition to the information listed by the AuditEvent interface, this event also provides the following additional information:
The AuditPredicateEvent event is used by 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 8-18 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 ContextHandler 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.
When a policy is modified or deployed using the Entitlements Administration Application or BLM Java API, informative messages are audited. The following information is available in these messages:
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 system.
|