22 Developing with Oracle Fusion Middleware Audit Framework

This chapter explains how to use Oracle Fusion Middleware Audit Framework to audit application events. Using this framework, you create event definitions, register the application with the service at deployment, modify audit configuration at runtime, and generate reports.

This chapter includes the following topics:

Integrating Applications with the Oracle Fusion Middleware Audit Framework

To integrate your application with the Audit Framework, perform the tasks explained in the following sections:

Creating Audit Definition Files

The following sections explain how to create the component-event.xml and translation files:

The component-events.xml File

When you create the component-events.xml audit definition file, keep in mind the following points:

  • Any change to an audit event definition requires that the version ID be modified by changing the minor or major numbers.

  • There must be a 1-to-1 correspondence between tables for your application attribute definitions and database columns. Each custom attribute must have a corresponding order number in its definition.

Translation Files

The following procedure explains how to generate the XLIFF (XML Localization Interchange File Format) translations files and pack them in the component_events_xlf.jar file. At deployment and during registration, this information is stored in the audit store along with the component event definition.

  1. Run a command like the following to generate XLIFF files:
    java -cp $MW_HOME/oracle_common/modules/oracle.jps_12.2.1/jpsaudit.jar:
    $MW_HOME/oracle_common/modules/oracle.jps_12.2.1/jps-api.jar oracle.security.audit.tools.NewXlfGenerator 
    -s /tmp/comp_events.xml 
    -t /tmp/comp_events.xlf
    
  2. Translate the generated xlf file for the supported languages. This xlf file contains translation units as well as help texts for all categories, events, and attributes. The prefixes for these are Category_, Event_ and Attribute_.
  3. Package the translated files in a JAR file.

Registering the Application with the Audit Service

The following sections explain the various mechanisms by which applications can register with audit:

Note:

The use of domain extension templates is the preferred approach to registration. For information about templates, see Using Domain Extension Templates for Audit Artifacts.

Performing Declarative Audit Registration

This section explains the two methods by which declarative registration of audit definitions occurs:

  • Default Audit Registration

  • Custom Audit Registration

Application Audit Registration

By default, the following registration activity occurs when you deploy, redeploy or undeploy the application:

  • Deployment - Registers the audit event definition to the audit store if the application is not yet registered.

  • Redeployment - Upgrades the component event definition if the component is already registered.

  • Undeployment - Removes the application's audit event definition from the audit store.

A simple database view to query audit records is created in the IAU schema at registration. This occurs for all except the component, for which Oracle Fusion Middleware Repository Creation Utility creates the view.

Custom Audit Registration

The parameters to customize audit registration are set in the weblogic-application.xml WebLogic Server deployment descriptor. This file is packaged in the META-INF directory of the application Enterprise ARchive (EAR) file. For information about packaging requirements, see Packaging a Java EE Application Manually.

A simple database view to query audit records is created in the IAU schema by audit registration, unless view creation is explicitly disabled.

Table 22-1 shows the parameters with their options:

Table 22-1 Parameters for Audit Registration

Parameter Option Description

opss.audit.registration

OVERWRITE

Register component audit definition whether or not it is registered.

UPGRADE (default option)

Register component audit definition according to version support.

DISABLE

Do not register component audit definition.

opss.audit.deregistration

DELETE (default option)

Delete component audit definition from audit store when undeploying applications.

DISABLE

Keep component audit definition in audit store when undeploying applications.

opss.audit.componentType

-

Set the custom component type. (Optional)

opss.audit.iauview

SIMPLE

INDEXABLE

DISABLE

  • Creates a simple IAU view (default behavior)

  • Creates an indexable IAU view if indexes are specified in the component_events.xmlapplication file.

  • Disables view creation.

The following example illustrates the use of registration and deregistration options:

<wls:application-param>
     <wls:param-name>opss.audit.registration</wls:param-name>
     <wls:param-value>DISABLE</wls:param-value>
</wls:application-param>
 
<wls:application-param>
     <wls:param-name>opss.audit.registration</wls:param-name>
     <wls:param-value>OVERWRITE</wls:param-value>
</wls:application-param>
 
<wls:application-param>
     <wls:param-name>opss.audit.unregistration</wls:param-name>
     <wls:param-value>DELETE</wls:param-value>
</wls:application-param>
 
<wls:application-param>
     <wls:param-name>opss.audit.unregistration</wls:param-name>
     <wls:param-value>DISABLE</wls:param-value>
</wls:application-param>

Programmatic Registration

The following example shoes how to register an application with audit programmatically:

AuditService auditService = JpsServiceLocator.getServiceLocator().lookup(AuditService.class);
AuditRegistration auditReg = <instance of AuditRegistration implementation>;
AccessController.doPrivileged(new PrivilegedExceptionAction<Object>() {
            public Object run() throws AuditException, IOException {
                auditService.register(auditReg);
                return null;
            }
        });

Calling the auditService.register method requires that the application be granted the AuditStoreAccessPermission permission with create, upgrade actions. For information about specifying grants, see Setting System Grants.

Here is a programmatic registration example:

JpsContextFactory ctxFactory = JpsContextFactory.getContextFactory();
JpsContext ctx = ctxFactory.getContext();
//get audit service
final AuditService auditService = ctx.getServiceInstance(AuditService.class);

//create an audit registration instance
final AuditRegistration auditReg = new SampleRegistration();
 
//call API to register audit event definition
AccessController.doPrivileged(new PrivilegedExceptionAction<Object>() {
      public Object run() throws AuditException, IOException {
      auditService.register(auditReg);
      return null;
   }
});

Registration creates a database view to query audit records from the database. To add logic to manage view creation or to disable this feature, implement the interface oracle.security.jps.service.audit.AuditRegistrationExt, an interface that extends AuditRegistration:

SampleRegistration.java
class SampleRegistration implements AuditRegistrationExt {
  /* 
    methods from Audit Registration go here
   */
  public AuditRegistrationExt.TYPE getIAUViewSupportType() {
     // add app specific logic here to determine the type
    return AuditRegistrationExt.TYPE.<type>;  // where type is SIMPLE, INDEXABLE, DISABLE
  }
} 

Registering the Application with Audit Using WLST

To register your application with audit, use the registerAudit WebLogic Scripting Tool (WLST) command. This command also allows you to create an audit view with the registration:

registerAudit(xmlFile, [xlfFile], componentType, [mode=OVERWRITE|UPGRADE], [createView=SIMPLE|INDEXABLE|DISABLE]) 

where SIMPLE is the default if no value is provided for createView.

See registerAudit in the WLST Command Reference for Infrastructure Security.

Using Domain Extension Templates for Audit Artifacts

When a domain is created or extended, applications can specify the seeding of application-specific security data in the security store. For information about artifact seeding, see How Security Artifacts Are Seeded.

Java EE applications can register with audit by means of domain extension templates containing the component_events.xml and component_events_xlf.jar files. Audit registration processes them automatically when you deploy the application. For information about the files included in the template, see Layered Component Security Artifacts.

Managing Audit Policies Programmatically

The Audit Framework allows you to query audit data, and get and set audit policies programmatically. First use the following method to obtain an AuditService instance:

AuditService auditService = JpsContextFactory.getContextFactory().getContext().getServiceInstance(AuditService.class);
    AuditAdminService auditAdminService = auditService.getAdminService();

The following sections explain how to use this instance to query and view audit data:

Querying Audit Data

To query audit data, use any of the following methods:

Set<String> getComponentNames() throws AuditException;
Map<String, ? extends AttributeGroup> getGenericAttributeGroups() throws AuditException;
    Collection<? extends EventCategory> getSystemEvents() throws AuditException;
    ComponentDefinition getComponentDef(String componentType) throws AuditException;
    AttributesDatabaseMap getAttributesMap(String componentType) throws AuditException;
    AttributesDatabaseMap getSystemAttributesMap() throws AuditException;

The following example demonstrates how to query audit data:

 //search events and attributes for a component
    Set<String> components = auditAdminService.getComponentNames();
    for (String componentType : components) {
        ComponentDefinition componentDef = auditAdminService.getComponentDef(componentType);
        //get attributes of a component
        AttributeGroup attrGroup = componentDef.getAttributes();
        for (AuditAttribute attr : attrGroup.getAttributes()) {
            AuditAttribute.DataType type = attr.getAttributeType();
            String attrName = attr.getName();
        }
        //get events of a component
        Collection<? extends EventCategory> events = componentDef.getEvents();
        for (EventCategory category : events) {
            if (category.isComponentSpecific()) { // isComponentSpecific() is true means the category is belong to a component, otherwise is system category
                Collection<? extends Event> categoryEvents = category.getAllEvents();
 
            }
        }
    }

Viewing and Setting Audit Policies

To retrieve and set an audit policy, use the following methods:

AuditPolicy getAuditPolicy(String componentType) throws AuditException;
void setAuditPolicy(String componentType, AuditPolicy auditPolicy) throws AuditException;

The following example shows how to use these methods to obtain and set the audit policy for a component:

 //get runtime policy for component JPS
    final String componentType = "JPS";
    AuditPolicy policy = auditAdminService.getAuditPolicy(componentType);
    String filterLevel = policy.getFilterLevel();
 
    //set runtim policy for component JPS
    final AuditPolicy newPolicy = new AuditPolicy("None", null, null);
    //setAuditPolicy() requires AuditStoreAccessPermission(<componentType>, "modify");
    AccessController.doPrivileged(new PrivilegedExceptionAction<Object>(){
        public Object run() throws AuditException {
            auditAdminService.setAuditPolicy(componentType, newPolicy);
            return null;
        }
    });

Logging Audit Events Programmatically

The following sections illustrate how applications can use the Oracle Fusion Middleware Audit Framework to access audit programmatically and generate their own audit events:

Oracle Fusion Middleware Audit Framework Interfaces

The Audit Framework provides the following class and interfaces:

Interface AuditService {
Auditor getAuditor(String componentType);
void register(AuditRegistration auditRegistration);
void unregister(AuditRegistration auditRegistration);
}
Interface Auditor {
boolean log(AuditEvent ev);
boolean isEnabled();
boolean isEnabled(String categoryName, String eventType, boolean eventStatus, Map<String, Object> properties);
}
public class oracle.security.jps.service.audit.AuditEvent {
   public AuditEvent(AuditContext ctx, String eventType, 
    String eventCategory, boolean eventStatus, String messageText);
   public void setApplicationName(String applicationName)   public void setAttribute(String attributeName, Object attributeValue)   public void setAttributeBoolean(String attributeName, boolean attributeValue)   public void setAttributeBoolean(String attributeName, Boolean attributeValue)   public void setAttributeBooleans(String attributeName, boolean[] values)   public void setAttributeByteArray(String attributeName, byte[] attributeValue)   public void setAttributeDate(String attributeName, Date attributeValue)   public void setAttributeDates(String attributeName, Date[] values)   public void setAttributeDouble(String attributeName, double attributeValue)   public void setAttributeDoubles(String attributeName, double[] values)   public void setAttributeFloat(String attributeName, float attributeValue)   public void setAttributeFloats(String attributeName, float[] values)   public void setAttributeInt(String attributeName, int attributeValue)   public void setAttributeInts(String attributeName, int[] values)   public void setAttributeLong(String attributeName, long attributeValue)   public void setAttributeLongs(String attributeName, long[] values)   public void setAttributeString(String attributeName, String attributeValue)   public void setAttributeStrings(String attributeName, String[] values)   public void setComponentName(String componentName)   public void setComponentType(String componentType)   public void setContextFields(String contextFields)   public void setECID(String ecid)   public void setEventCategory(String category)   public void setEventDefinition(Object
eventDefinition)   public void setEventStatus(boolean status)   public void setEventTimestamp(long eventTimestamp)   public void setEventType(String eventType)   public void setFailureCode(String failureCode)   public void setHostId(String hostId)   public void setHostNetworkAddr(String hostNetworkAddr)   public void setInitiator(String initiator)   public void setInstanceId(String instanceId)   public void setMessageText(String messageText)   public void setModuleId(String moduleId)   public void setOracleHome(String oracleHome)   public void setOracleInstance(String oracleInstance)   public void setProcessId(String processId)   public void setRemoteIP(String value)              public void setResource(String value)             public void setRID(String rid)             public void setRoles(String value)            public void setTarget(String value)           public void setTargetComponentType(String targetComponentType)            public void setThreadId(String threadId)   public void setTransactionId(String transactionId)
}

To set permissions and to obtain an auditor instance, see Setting System Grants, and Obtaining the Auditor Instance.

Setting System Grants

Applications must have the AuditStoreAccessPermission permission to use methods provided by the Audit Framework. In this example, the grant allows the MyApp application to call the auditService.getAuditor method in an AccessController.doPrivileged block:

<grant>
  <grantee>
    <codesource>
      <url>file:${oracle.deployed.app.dir}/MyApp${oracle.deployed.app.ext}</url>
    </codesource>
  </grantee>
 <permissions>
  <permission>
    <class>oracle.security.jps.service.audit.AuditStoreAccessPermission</class>
    <name>comp1</name>
    <actions>action1,action2,action3</actions>
  </permission>
 </permissions>
</grant>

where the <actions> is the comma-separated list of actions that the application can carry out. The following table lists the available actions:

Action Authorizes Client to

create

Call AuditService.register to register a new audit component.

upgrade

Call AuditService.register to upgrade a component event definition.

delete

Call AuditService.unregister to deregister an audit component.

read

Call AuditService.getAuditor to get an instance of component auditor.

modify

Call AuditAdminService.setAuditPolicy to modify audit policy.

Obtaining the Auditor Instance

After your application registers to audit, it can get its auditor instance programmatically:

//Gets audit service instance
final AuditService auditService = JpsServiceLocator.getServiceLocator().lookup(AuditService.class);
 
//Gets Auditor instance for application 'MyApp'
Auditor auditor = AccessController.doPrivileged(
                            new PrivilegedExceptionAction<Auditor>() {
                                public Auditor run() throws AuditException {
                                    return auditService.getAuditor("MyApp");
                                }
                            });
 
final String category = "Transaction";
final String eventName = "deposit";
 
//Check if event 'deposit' is enabled in filtering.
boolean enabled = auditor.isEnabled(category, eventName, "true", null);
if (enabled) {
        AuditContext ctx = new AuditContext();
        String message = "deposit transaction";
        //Creates an audit event
        AuditEvent ev = new AuditEvent(ctx, eventName, category, "true", message);
 
        //Sets event attributes
        ev.setInitiator("johnsmith");
        ev.setAttributeInt("accounting:AccountNumber", 2134567);
        ev.setAttributeDate("accounting:Date", new Date());
        ev.setAttributeFloat("accounting:Amount", 100.00);
 
        //Logs audit event
        boolean ret = auditor.log(event);
}

Updating and Maintaining Audit Definitions

As the application's audit requirements evolve, you typically update audit definitions to reflect those changes. Specifically, you:

  1. Update the audit definition file. For information about versions, see About Mapping and Version Rules.
  2. Redeploy the application EAR file with the updated event definition file. Alternatively, notify audit registration about the newer version.
  3. Verify your changes.

Note:

When you create or extend a WebLogic Server domain, you can specify audit artifacts in the domain template to facilitate audit definition upgrades. For information about files in component templates, see Layered Component Security Artifacts.