Configuring the WebLogic Auditing Provider

Auditing Provider Overview

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. In other words, Auditing providers produce an electronic trail of computer activity.

Configuring an Auditing provider is optional. The default security realm (myrealm) does not have an Auditing provider configured. WebLogic Server includes a provider named the WebLogic Auditing provider (referred to as DefaultAuditor in the WebLogic Server Administration Console). You can also develop custom Auditing providers, as described in Auditing Providers in Developing Security Providers for Oracle WebLogic Server.

Events Logged by the WebLogic Auditing Provider

If the WebLogic Auditing Provider is enabled, then it can log events such as authentication, authorization, user account status, and more. The WebLogic Auditing provider can log the events described in Table 7-1.

Table 7-1 WebLogic Auditing Provider Events

The following audit event . . .	Indicates . . .
`AUTHENTICATE`	A simple authentication (username and password) occurred.
`ASSERTIDENTITY`	A perimeter authentication (based on tokens) occurred.
`USERLOCKED`	A user account is locked because of invalid login attempts.
`USERUNLOCKED`	The lock on a user account is cleared.
`USERLOCKOUTEXPIRED`	The lock on a user account expired.
`ISAUTHORIZED`	An authorization attempt occurred.
`ROLEEVENT`	A `getRoles` event occurred.
`ROLEDEPLOY`	A `deployRole` event occurred.
`ROLEUNDEPLOY`	An `undeployRole` event occurred.
`POLICYDEPLOY`	A `deploy`Policy event occurred.
`POLICYUNDEPLOY`	An `undeploy`Policy event occurred.
`START_AUDIT`	An Auditing provider has been started.
`STOP_AUDIT`	An Auditing provider has been stopped.

Configuration Options

By default, most configuration options for the WebLogic Auditing provider are already defined and, once it is added to the active security realm, the WebLogic Auditing provider will begin to record audit events. However, you need to define the following settings, which you can do in the WebLogic Server Administration Console by selecting the Configuration > Provider Specific page for the provider. You can also use WebLogic Scripting tool or the Java Management Extensions (JMX) APIs to configure the Auditing provider:

Rotation Minutes—Specifies how many minutes to wait before creating a new DefaultAuditRecorder.log file. At the specified time, the audit file is closed and a new one is created. A backup file named DefaultAuditRecorder.YYYYMMDDHHMM.log (for example, DefaultAuditRecorder.200405130110.log) is created in the same directory.

Severity—Severity level appropriate for your WebLogic Server deployment. The WebLogic Auditing provider audits security events of the specified severity, as well as all events with a higher numeric severity rank. For example, if you set the severity level to ERROR, the WebLogic Auditing provider audits security events of severity level ERROR, SUCCESS, and FAILURE. You can also set the severity level to CUSTOM, and then enable the specific severity levels you want to audit, such as ERROR and FAILURE events only. Audit events include both the severity name and numeric rank; therefore, a custom Auditing provider can filter events by either the name or the numeric rank. Auditing can be initiated when the following levels of security events occur.

Table 7-2 Event Severity

Event Severity	Rank
INFORMATION	1
WARNING	2
ERROR	3
SUCCESS	4
FAILURE	5

All auditing information recorded by the WebLogic Auditing provider is saved in WL_HOME\yourdomain\yourserver\logs\DefaultAuditRecorder.log by default. Although an Auditing provider is configured per security realm, each server writes auditing data to its own log file in the server directory. You can specify a new directory location for the DefaultAuditRecorder.log file on the command line with the following Java startup option:

-Dweblogic.security.audit.auditLogDir=c:\foo

The new file location will be c:\foo\yourserver\logs\DefaultAuditRecorder.log.

See Security in the Command Reference for Oracle WebLogic Server.

Note:

Using an Auditing provider affects the performance of WebLogic Server even if only a few events are logged.

See Configure Auditing providers in the Oracle WebLogic Server Administration Console Online Help.

Auditing ContextHandler Elements

The ContextHandler interface is used to manage audit providers that support context handler entries. Set the ContextHandler Entries attribute to specify which ContextElement entries are recorded by the Auditing provider.

An Audit Event includes a ContextHandler that can hold a variety of information or objects. Set the WebLogic Auditing provider's Active ContextHandler Entries attribute to specify which ContextElement entries in the ContextHandler are recorded by the Auditing provider. By default, none of the ContextElements are audited. Objects in the ContextHandler are in most cases logged using the toString method. Table 7-3 lists the available ContextHandler entries.

Note:

The WebLogic Auditing provider can audit only the attributes for the specific functionality that is being implemented. It does not audit all of the context handler elements by default. For example, if you log into the WebLogic Server Administration Console using HTTP, the authentication is performed in the context of an HTTP servlet request, and the Auditing provider audits HTTP servlet elements. Alternatively, authentication from WLST uses t3 protocol. For t3 authentication, the auditing provider audits the channel context elements such as com.bea.contextelement.channel.Protocol and com.bea.contextelement.channel.RemoteAddress. In both cases, the Auditing provider only audits the functionality being implemented, either HTTP or t3.

Table 7-3 Context Handler Entries for Auditing

Context Element Name	Description and Type
`com.bea.contextelement.servlet.HttpServletRequest`	A servlet access request or SOAP message via HTTP `javax.http.servlet.HttpServletRequest`
`com.bea.contextelement.servlet.HttpServletResponse`	A servlet access response or SOAP message via HTTP `javax.http.servlet.HttpServletResponse`
`com.bea.contextelement.wli.Message`	An Oracle WebLogic Integration message. The message is streamed to the audit log. `java.io.InputStream`
`com.bea.contextelement.channel.Port`	Internal listen port of the network channel accepting or processing the request `java.lang.Integer`
`com.bea.contextelement.channel.PublicPort`	External listen port of the network channel accepting or processing the request `java.lang.Integer`
`com.bea.contextelement.channel.RemotePort`	Port of the remote end of the TCP/IP connection of the network channel accepting or processing the request `java.lang.Integer`
`com.bea.contextelement.channel.Protocol`	Protocol used to make the request of the network channel accepting or processing the request `java.lang.String`
`com.bea.contextelement.channel.Address`	The internal listen address of the network channel accepting or processing the request `java.lang.String`
`com.bea.contextelement.channel.PublicAddress`	The external listen address of the network channel accepting or processing the request `java.lang.String`
`com.bea.contextelement.channel.RemoteAddress`	Remote address of the TCP/IP connection of the network channel accepting or processing the request `java.lang.String`
`com.bea.contextelement.channel.ChannelName`	Name of the network channel accepting or processing the request `java.lang.String`
`com.bea.contextelement.channel.Secure`	Whether the network channel is accepting or processing the request using SSL `java.lang.Boolean`
`com.bea.contextelement.ejb20.Parameter[1-N]`	Object based on parameter
`com.bea.contextelement.wsee.SOAPMessage`	`javax.xml.rpc.handler.MessageContext`
`com.bea.contextelement.entitlement.EAuxiliaryID`	Used by a WebLogic Server internal process. `weblogic.entitlement.expression.EAuxiliary`
`com.bea.contextelement.security.ChainPrevalidatedBySSL`	SSL framework has validated the certificate chain, meaning that the certificates in the chain have signed each other properly; the chain terminates in a certificate that is one of the server's trusted CAs; the chain honors the basic constraints rules; and the certificates in the chain have not expired. `java.lang.Boolean`
`com.bea.contextelement.xml.SecurityToken`	Not used in this release of WebLogic Server. `weblogic.xml.crypto.wss.provider.SecurityToken`
`com.bea.contextelement.xml.SecurityTokenAssertion`	Not used in this release of WebLogic Server. `java.util.Map`
`com.bea.contextelement.webservice.Integrity{id:XXXXX}`	`javax.security.auth.Subject`
`com.bea.contextelement.saml.SSLClientCertificateChain`	SSL client certificate chain obtained from the SSL connection over which a sender-vouches SAML assertion was received. `java.security.cert.X509Certificate[]`
`com.bea.contextelement.saml.MessageSignerCertificate`	Certificate used to sign a Web services message. `java.security.cert.X509Certificate`
`com.bea.contextelement.saml.subject.ConfirmationMethod`	Type of SAML assertion: bearer, artifact, sender-vouches, or holder-of-key. `java.lang.String`
`com.bea.contextelement.saml.subject.dom.KeyInfo`	`<ds:KeyInfo>` element to be used for subject confirmation with holder-of-key SAML assertions. `org.w3c.dom.Element`

Configuration Auditing

You can configure the Administration Server to emit log messages and generate audit events when a user changes the configuration of any resource within a domain or invokes management operations on any resource within a domain. For example, if a user disables SSL on a Managed Server in a domain, the Administration Server emits log messages. If you have enabled the WebLogic Auditing provider, it writes the audit events to an additional security log. These messages and audit events provide an audit trail of changes within a domain's configuration (configuration auditing).

The Administration Server writes configuration auditing messages to its local log file. They are not written to the domain-wide message log by default.

Note that configuration audit information is contained in Authorization Events. As a result, another approach to configuration auditing is to consume Authorization Events. Note, however, that the information in an Authorization Event tells you whether access was allowed to perform a configuration change; it does not tell you whether the configuration change actually succeeded (for instance, it might have failed because it was invalid).

To enable configuration auditing, see Enabling Configuration Auditing.

Enabling Configuration Auditing

Learn the different methods to enable configuration auditing.

Enable configuration auditing by one of these methods:

Use the WebLogic Server Administration Console. Select the Configuration > General page for your domain and set the Configuration Audit Type. See Enable configuration auditing in the Oracle WebLogic Server Administration Console Online Help.
When you start the Administration Server, include one of the following Java options in the weblogic.Server command:
- -Dweblogic.domain.ConfigurationAuditType="audit"
  
  Causes the domain to emit Audit Events only.
- -Dweblogic.domain.ConfigurationAuditType="log"
  
  Causes the domain to write configuration auditing messages to the Administration Server log file only.
- -Dweblogic.domain.ConfigurationAuditType="logaudit"
  
  Causes the domain to emit Audit Events and write configuration auditing messages to the Administration Server log file.
See weblogic.Server Command-Line Reference in Command Reference for Oracle WebLogic Server.
Use the WebLogic Scripting Tool to change the value of the ConfigurationAuditType attribute of the DomainMBean. See Understanding the WebLogic Scripting Tool.

Configuration Auditing Messages

The configuration auditing severity levels are SUCCESS, FAILURE, and ERROR.

Table 7-4 Configuration Auditing Message Severities

Severity	Description
SUCCESS	A successful configuration change occurred.
FAILURE	An attempt to modify the configuration failed due to insufficient user credentials.
ERROR	An attempt to modify the configuration failed due to an internal error.

Configuration auditing messages are identified by message IDs that fall within the range of 159900-159910.

The messages use MBean object names to identify resources. Object names for WebLogic Server MBeans reflect the location of the MBean within the hierarchical data model. To reflect the location, object names contain name/value pairs from the parent MBean. For example, the object name for a server's LogMBean is: mydomain:Name=myserverlog,Type=Log,Server=myserver. See WebLogic Server MBean Data Model in Developing Custom Management Utilities Using JMX for Oracle WebLogic Server.

Table 7-5 summarizes the messages.

Table 7-5 Summary of Configuration Auditing Messages

When this event occurs . . .	WebLogic Server generates a message with this ID . . .	And this message text . . .
Authorized user creates a resource.	`159900`	`USER username CREATED MBean-name` where `username` identifies the WebLogic Server user who logged in and created a resource.
Unauthorized user attempts to create a resource.	`159901`	`USER username CREATED MBean-name FAILED weblogic.management. NoAccessRuntimeException: exception-text stack-trace` where `username` identifies the unauthorized WebLogic Server user.
Authorized user deletes a resource.	`159902`	`USER username REMOVED MBean-name` where `username` identifies the WebLogic Server user who logged in and deleted a resource.
Unauthorized user attempts to delete a resource.	`159903`	`USER username REMOVE MBean-name FAILED weblogic.management. NoAccessRuntimeException: exception-text stack-trace` where `username` identifies the unauthorized WebLogic Server user.
Authorized user changes a resource's configuration.	`159904`	`USER username MODIFIED MBean-name ATTRIBUTE attribute-name FROM old-value TO new-value` where `username` identifies the WebLogic Server user who logged in and changed the resource's configuration.
Unauthorized user attempts to change a resource's configuration.	`159905`	`USER username MODIFY MBean-name ATTRIBUTE attribute-name FROM old-value TO new-value FAILED weblogic.management. NoAccessRuntimeException: exception-text stack-trace` where `username` identifies the unauthorized WebLogic Server user.
Authorized user invokes an operation on a resource. For example, a user deploys an application or starts a server instance.	`159907`	`USER username INVOKED ON MBean-name METHOD operation-name PARAMS specified-parameters` where `username` identifies the WebLogic Server user who logged in and invoked a resource operation.
Unauthorized user attempts to invoke an operation on a resource.	`159908`	`USER username INVOKED ON MBean-name METHOD operation-name PARAMS specified-parameters FAILED weblogic.management. NoAccessRuntimeException: exception-text stack-trace` where `username` identifies the unauthorized WebLogic Server user.
Authorized user enables configuration auditing.	`159909`	`USER username, Configuration Auditing is enabled` where `username` identifies the WebLogic Server user who enabled configuration auditing.
Authorized user disables configuration auditing.	`159910`	`USER username, Configuration Auditing is disabled` where username identifies the WebLogic Server user who disabled configuration auditing.

Note:

Each time an authorized user adds, modifies, or deletes a resource, the Management subsystem also generates an Info message with the ID 140009 regardless of whether configuration auditing is enabled. For example:

<Sep 15, 2005 11:54:47 AM EDT> <Info> <Management> <140009> <Configuration changes for domain saved to the repository.>

While the message informs you that the domain's configuration has changed, it does not provide the detailed information that configuration auditing messages provide. Nor does the Management subsystem generate this message when you invoke operations on resources.

Table 7-6 lists additional message attributes for configuration auditing messages. All configuration auditing messages specify the same values for these attributes.

Table 7-6 Common Message Attributes and Values

Message Attribute	Attribute Value
Severity	`Info`
Subsystem	`Configuration Audit`
User ID	`kernel identity` This value is always `kernel` identity, regardless of which user modified the resource or invoked the resource operation.
Server Name	`AdminServerName` Because the Administration Server maintains the configuration data for all resources in a domain, this value is always the name of the Administration Server.
Machine Name	`AdminServerHostName` Because the Administration Server maintains the configuration data for all resources in a domain, this value is always the name of the Administration Server's host machine.
Thread ID	`execute-thread` The value depends on the number of execute threads that are currently running on the Administration Server.
Timestamp	`timeStamp` at which the message is generated.

Audit Events and Auditing Providers

An audit event is an object that Auditing providers can read and process in specific ways. An Auditing provider is a pluggable component that the security realm uses to collect, store, and distribute information about operating requests and the outcome of those requests for the purposes of non-repudiation.

If you enable a domain to emit Audit Events, the domain emits the events described in Table 7-7. All Auditing providers that are configured for the domain can handle these events.

All of the events are of severity level SUCCESS and describe the security principal who initiated the action, whether permission was granted, and the object (MBean or MBean attribute) of the requested action.

Table 7-7 Summary of Audit Events for Configuration Auditing

When this event occurs . . .	WebLogic Server generates this Audit Event object . . .
A request to create a new configuration artifact has been allowed or prevented.	`weblogic.security.spi.AuditCreateConfigurationEvent`
A request to delete an existing configuration artifact has been allowed or prevented.	`weblogic.security.spi.AuditDeleteConfigurationEvent`
A request to modify an existing configuration artifact has been allowed or prevented.	`weblogic.security.spi.AuditInvokeConfigurationEvent`
A invoke an operation on an existing configuration artifact has been allowed or prevented.	`weblogic.security.spi.AuditSetAttributeConfigurationEvent`

If you enable the default WebLogic Server Auditing provider, it writes all Audit Events as log messages in its own log file.

Other Auditing providers that you create or purchase can filter these events and write them to output repositories such as an LDAP server, database, or a simple file. In addition, other types of security providers can request audit services from an Auditing provider. See Auditing Providers in Developing Security Providers for Oracle WebLogic Server.