Administration Application Guide
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 13-1. Table 13-1 also indicates which sub-interfaces implement the AuditContext
interface. These interfaces are documented in the BEA WebLogic Enterprise Security Provider SSPI 4.2 API Reference.
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 the security provider interface package, WebLogic Security defines one top-level base interface (AuditEvent
) with seven different derived interfaces that represent the different types of audit events. The following sections describe when the security framework and security providers post these 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 13-2 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 13-3 describes the conditions under which the events are posted and severity level of the event.
Posted if access is not allowed to resource (exception thrown by authorization provider). |
||
Credential Mapping audit events are posted by the security framework. Table 13-4. 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 13-5 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 13-6 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 13-7 describes the conditions under which the events are posted and lists the event severity level.
Table 13-8 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 13-9 describes the event properties.
Indicates that a user was locked because of a series of failed login attempts. |
|
Represents the identity assertion authentication token type. |
|
When this event is generated, the following information associated with this AuditAtnEvent
is available:
AuditAtnEvent
; that is, the username of the person who is attempting authentication. AuditAtnEvent
AuditAtzEvent
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 8.1, 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 13-10 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 13-11 describes the event subtypes.
When an AuditRoleEvent
is generated, the following information is available:
AuditRoleEvent
AuditRoleEvent
ContextHandler
objectThe resource container that handles the type of resource being requested (for example, with WebLogic Server 8.1, 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 13-12 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 WebLogic Enterprise Security policy is modified or deployed using the WebLogic 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.