Auditing Events From Custom Security Providers 12-3
12.2.1 Create an Audit Event
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:
■
Section 12.2.1.1, Implement the AuditEvent SSPI or
■
Section 12.2.1.2, Implement an Audit Event Convenience Interface
12.2.1.1 Implement the AuditEvent SSPI
To implement the AuditEvent SSPI, provide implementations for the following methods:
■
getEventType public java.lang.String getEventType
The getEventType method returns a string representation of the event type that is to be audited, which is used by the Audit Channel that is, the runtime class that
implements the AuditChannel SSPI. For example, the event type for the Oracle-provided implementation is Authentication Audit Event. For
more information, see
Section 10.1.1, Audit Channels and
Section 10.5.1.2, Implement the AuditChannel SSPI.
■
getFailureException public java.lang.Exception getFailureException
The getFailureException method returns an Exception object, which is used by the Audit Channel to obtain audit information, in addition to the
information provided by the tostring method.
■
getSeverity public AuditSeverity getSeverity
The getSeverity method returns the severity level value associated with the event type that is to be audited, which is used by the Audit Channel. This allows
the Audit Channel to make the decision about whether or not to audit. For more information, see
Section 12.2.1.3, Audit Severity.
■
toString public java.lang.String toString
The toString method returns preformatted audit information to the Audit Channel.
For more information about the AuditEvent SSPI and these methods, see the WebLogic Server API Reference Javadoc.
Note: The toString method can produce any character and no
escaping is used. If your Audit provider is writing the toString value into a format that uses characters for syntax, escape the
toString value before writing it.
12-4 Developing Security Providers for Oracle WebLogic Server
12.2.1.2 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 AuditAtnEventV2 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
Section 10.1.1, Audit Channels
and Section 10.5.1.2, Implement the AuditChannel SSPI.
The Audit Event convenience interfaces are:
■
Section 12.2.1.2.1, The AuditAtnEventV2 Interface
■
Section 12.2.1.2.2, The AuditAtzEvent and AuditPolicyEvent Interfaces
■
Section 12.2.1.2.3, The AuditMgmtEvent Interface
■
Section 12.2.1.2.4, The AuditRoleEvent and AuditRoleDeploymentEvent Interfaces
12.2.1.2.1 The AuditAtnEventV2 Interface The AuditAtnEventV2 convenience interface
helps Audit Channels to determine instance types of extended authentication event type objects.
To implement the AuditAtnEventV2 interface, provide implementations for the methods described in
Section 12.2.1.1, Implement the AuditEvent SSPI and the
following methods:
■
getUsername public String getUsername
The getUsername method returns the username associated with the authentication event.
■
getAtnEventType public AuditAtnEventV2.AtnEventTypeV2 getAtnEventType
The getAtnEventType method returns an event type that more specifically represents the authentication event. The specific authentication event types are:
AUTHENTICATE: simple authentication using a username and password occurred. ASSERTIDENTITY: perimeter authentication based on tokens occurred.
CREATEDERIVEDKEY: represents the creation of the Derived key. CREATEPASSWORDDIGEST: represents the creation of the Password Digest.
Note: It is recommended, but not required, that you implement one
of the Audit Event convenience interfaces.
Note:
The AuditAtnEvent interface is deprecated in this release of WebLogic Server.
Auditing Events From Custom Security Providers 12-5
IMPERSONATEIDENTITY: client identity has been established using the supplied client username requires kernel identity.
USERLOCKED: a user account has been locked because of invalid login attempts. USERUNLOCKED: a lock on a user account has been cleared.
USERLOCKOUTEXPIRED: a lock on a user account has expired. VALIDATEIDENTITY: authenticity trust of the principals within the supplied
subject has been validated.
■
toString public String toString
The toString method returns the specific authentication information to audit, represented as a string.
For more information about the AuditAtnEventV2 convenience interface and these methods, see the WebLogic Server API Reference Javadoc.
12.2.1.2.2 The AuditAtzEvent and AuditPolicyEvent Interfaces The AuditAtzEvent and
AuditPolicyEvent convenience interfaces help Audit Channels to determine instance types of extended authorization event type objects.
To implement the AuditAtzEvent or AuditPolicyEvent interface, provide implementations for the methods described in
Section 12.2.1.1, Implement the AuditEvent SSPI
and the following methods:
■
getSubject public Subject getSubject
The getSubject method returns the subject associated with the authorization event that is, the subject attempting to access the WebLogic resource.
■
getResource public Resource getResource
The getResource method returns the WebLogic resource associated with the authorization event that the subject is attempting to access.
Note: The toString method can produce any character and no
escaping is used. If your Audit provider is writing the toString value into a format that uses characters for syntax, escape the
toString value before writing it.
The AuditAtnEventV2 convenience interface extends both the AuditEvent and AuditContext interfaces. For more information
about the AuditContext interface, see Section 12.2.1.4, Audit
Context.
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
Section 12.2.1.4, Audit Context.
12-6 Developing Security Providers for Oracle WebLogic Server
For more information about these convenience interfaces and methods, see the WebLogic Server API Reference Javadoc for the AuditAtzEvent interface or the
AuditPolicyEvent interface.
12.2.1.2.3 The AuditMgmtEvent Interface The AuditMgmtEvent convenience interface
helps Audit Channels to determine instance types of extended security management event type objects, such as a security providers MBean. It contains no methods that
you must implement, but maintains the best practice structure for an Audit Event implementation.
For more information about the AuditMgmtEvent convenience interface, see the WebLogic Server API Reference Javadoc.
12.2.1.2.4 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.
For more information about these convenience interfaces, see the WebLogic Server API Reference Javadoc for the AuditRoleEvent interface or the AuditRoleDeploymentEvent
interface.
12.2.1.3 Audit Severity
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.
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
Note: For more information about MBeans, see
Section 3.3, Security Service Provider Interface SSPI MBeans.
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
Section 12.2.1.4, Audit Context.
Note: Auditing providers are configured using the WebLogic Server
Administration Console. For more information, see Section 10.5.3,
Configure the Custom Auditing Provider Using the Administration Console.
Auditing Events From Custom Security Providers 12-7
AuditChannel SSPI and the AuditEvent object, see Section 10.5.1.2, Implement the
AuditChannel SSPI and
Section 12.2.1, Create an Audit Event, respectively.
12.2.1.4 Audit Context
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 Section 10.1.1, Audit Channels
and Section 10.5.1.2, Implement the AuditChannel
SSPI. The AuditContext interface includes the following method:
■
getContext public ContextHandler getContext
The getContext method returns a ContextHandler object, which is used by the runtime class that is, the AuditChannel SSPI implementation to obtain
additional audit information. For more information about ContextHandlers, see Section 3.6.9, ContextHandlers and WebLogic Resources.
12.2.1.5 Example: Implementation of the AuditRoleEvent Interface
Example 12–1 shows the MyAuditRoleEventImpl.java class, which is a sample
implementation of an Audit Event convenience interface in this case, the AuditRoleEvent convenience interface. This class includes implementations for:
■
The four methods inherited from the AuditEvent SSPI: getEventType, getFailureException, getSeverity and toString as described in
Section 12.2.1.1, Implement the AuditEvent SSPI .
■
One additional method: getContext, which returns additional contextual information via the ContextHandler. For more information about
ContextHandlers, see Section 3.6.9, ContextHandlers and WebLogic Resources.
Example 12–1 MyAuditRoleEventImpl.java
package mypackage; import javax.security.auth.Subject;
import weblogic.security.SubjectUtils; import weblogic.security.service.ContextHandler;
import weblogic.security.spi.AuditRoleEvent; import weblogic.security.spi.AuditSeverity;
import weblogic.security.spi.Resource; package class MyAuditRoleEventImpl implements AuditRoleEvent
{ private Subject subject;
private Resource resource; private ContextHandler context;
private String details; private Exception failureException;
package MyAuditRoleEventImplSubject subject, Resource resource,
ContextHandler context, String details, Exception failureException {
this.subject = subject; this.resource = resource;
Note: The bold face code in
Example 12–1 highlights the class
declaration and the method signatures.
12-8 Developing Security Providers for Oracle WebLogic Server
this.context = context; this.details = details;
this.failureException = failureException; }
public Exception getFailureException {
return failureException; }
public AuditSeverity getSeverity {
return failureException == null ? AuditSeverity.SUCCESS : AuditSeverity.FAILURE;
} public String getEventType
{ return MyAuditRoleEventType;
} public ContextHandler getContext
{ return context;
} public String toString
{ StringBuffer buf = new StringBuffer;
buf.appendEventType: + getEventType + \n; buf.append\tSeverity: +
getSeverity.getSeverityString; buf.append\tSubject: +
SubjectUtils.displaySubjectgetSubject; buf.append\tResource: + resource.toString;
buf.append\tDetails: + details; if getFailureException = null {
buf.append\n\tFailureException: + getFailureException;
} return buf.toString;
} }
12.2.2 Obtain and Use the Auditor Service to Write Audit Events
Kategori