Skip Headers
Oracle® Fusion Middleware Application Security Guide
11g Release 1 (11.1.1)

Part Number E10043-12
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

28 Developing with the Audit Service

This chapter explains how applications (also known as audit clients) can use the Oracle Fusion Middleware Audit Framework to provide auditing capabilities. 11g Release 1 (11.1.1.6) introduces an audit service that enables you to integrate with the audit framework programmatically to log audit events and generate compliance reports using the same capabilities available to Oracle components.

Using the audit service, applications can:

This chapter contains these topics:

28.1 Application Integration with Audit Flow

As Figure 28-1 shows, Java EE applications running on Oracle WebLogic Server can integrate with and leverage the audit framework seamlessly:

Figure 28-1 Integrating Applications with the Audit Framework

Surrounding text describes Figure 28-1 .

During application deployment or audit service start-up, a client such as a Java EE application or Oracle component registers with the audit service. The registration service updates the metadata store with the latest audit definitions contained in component_events.xml and related files.

See Also:

Section 12.3 for details about the audit flow.

The rest of this chapter explains the metadata model, and how you can integrate your applications with the audit flow to log audit events and create audit reports.

28.2 Audit Metadata Model

The audit framework supports a metadata model which enables applications to specify their audit artifacts in a flexible manner. Applications can dynamically define attribute groups, categories, and events.

28.2.1 Attribute Groups

Attribute groups provide broad classification of audit attributes and consist of three types:

  • The common attribute group contains all the system attributes common to all applications, such as component type, system IP address, hostname, and others.

    The IAU_COMMON database table contains attributes in this group.

  • Generic attribute groups contain attributes for audit application areas such as authentication and user provisioning.

  • Custom attribute groups are those defined by an application to meet its specific needs. Attributes in a custom group are limited to that component scope.

28.2.1.1 Audit Attribute Data Types

Table 28-1 shows the supported attribute data types and the corresponding Java object types:

Table 28-1 Audit Attribute Data Types

Attribute Data Type Java Object Type Notes

Integer

Integer

 

Long

Long

 

Float

Float

 

Double

Double

 

Boolean

Boolean

 

DateTime

java.util.Date

 

String

String

Maximum length 2048 bytes

LongString

String

Unlimited length

Binary

byte[]

 

28.2.1.2 Common Attribute Groups

The common attribute group is stored in the IAU_COMMON database table.

28.2.1.3 Generic Attribute Groups

A generic attribute group is defined with a namespace, a version number, and one or more attributes. This example defines an attribute group with namespace authorization and version 1.0:

<AuditConfig xmlns="http://xmlns.oracle.com/ias/audit/audit-2.0.xsd" >
    <Attributes ns="authorization" version="1.0">
        <Attribute displayName="CodeSource" maxLength="2048" name="CodeSource" type="string"/>
        <Attribute displayName="Principals" maxLength="1024" name="Principals" type="string"/>
        <Attribute displayName="InitiatorGUID" maxLength="1024" name="InitiatorGUID" type="string"/>
        <Attribute displayName="Subject" maxLength="1024" name="Subject" type="string">
          <HelpText>Used for subject in authorization</HelpText>
        </Attribute>
    </Attributes>
        ……

Your application can reference the CodeSource attribute like this:

<Attribute name="CodeSource" ns="authorization" version="1.0" />

Each generic attribute group is stored in a dedicated database table. The naming conventions are:

  • IAU_GENERIC_ATTRIBUTE_GROUP_NAME for table names

  • IAU_ATTRIBUTE_NAME for table columns

For example, the attribute group authorization is stored in database table IAU_AUTHORIZATION with these columns:

  • IAU_CODESOURCE as string

  • IAU_PRINCIPALS as string

  • IAU_INITIATORGUID as string

28.2.1.4 Custom Attribute Groups

A custom attribute group is defined with a namespace, a version number, and one or more attributes.

Attributes consist of:

  • attribute name

  • data type

  • attribute-database column mapping order, which specifies the order in which an attribute is mapped to a database column of a specific data type in the custom attribute table

  • help text (optional)

  • maximum length

  • display name

This example defines attribute group Accounting with namespace accounting and version 1.0:

<Attributes ns="accounting" version="1.0">
 
            <Attribute name="TransactionType" displayName="Transaction Type" type="string" order="1"/>
            <Attribute name="AccountNumber" displayName="Account Number" type="int" order="2">
                <HelpText>Account number.</HelpText>
            </Attribute>
            ……
        </Attributes>

Custom attribute groups and attributes are stored in the IAU_CUSTOM table.

28.2.2 Event Categories and Events

An audit event category contains related events in a functional area. For example, a session category could contain login and logout events that are significant in a user session's life cycle.

An event category does not itself define attributes. Instead, it references attributes in component and system attribute groups.

There are two types of event categories:

  • System Categories

  • Component and Application Categories

28.2.2.1 System Categories and Events

A system category references common and generic attribute groups and contains audit events. System categories are the base set of component event categories and events. Applications can reference them directly, log audit events, and set filter preset definitions.

The following example shows several elements of the metadata model:

  • common attribute group

  • generic attribute groups identity and authorization

  • system category UserSession with an attribute referencing to a common attribute AuthenticationMethod

  • audit events such as UserLogin and UserLogout

<SystemComponent major="1" minor="0">
+<Attributes ns="common" version ="1.0"></Attributes>
+<Attributes ns="identity" version ="1.0"></Attributes>
+<Attributes ns="authorization" version ="1.0"></Attributes>
-<Events>
 -<Category name="UserSession" displayName="User Sessions">
  -<Attributes>
     <Attribute name="AuthenticationMethod" ns="common" version ="1.0" />
   </Attributes>
  -<HelpText></HelpText>
  -<Event name="UserLogin" displayName="User Logins" shortName="uLogin"></Event>
  -<Event name="UserLogout" displayName="User Logouts" shortName="uLogout" 
    xdasName="terminateSession"></Event>
  -<Event name="Authentication" displayName="Authentication"></Event>
  -<Event name="InternalLogin" displayName="Internal Login" shortName="iLogin"
    xdasName="CreateSession"></Event>
  -<Event name="InternalLogout" displayName="Internal Logout" shortName="iLogout"
    xdasName="terminateSession"></Event>
  -<Event name="QuerySession" displayName="Query Session"     shortName="qSession"></Event>
  -<Event name="ModifySession" displayName="Modify Session"     shortName="mSession"></Event>
  </Category>
 +<Category displayName="Authorization" name="Authorization"></Category>
 +<Category displayName="ServiceManagement" name="ServiceManagement"></Category>
 </Events>
</SystemComponent>

28.2.2.2 Component/Application Categories

A component or application can define extend system categories or define new component event categories. In this example, a transaction category references attributes AccountNumber, Date, and Amount from the accounting attribute group, and includes events 'purchase' and 'deposit':

<Category displayName="Transaction" name="Transaction">
    <Attributes>
       <Attribute name="AccountNumber" ns="accounting" version="1.0"/>
       <Attribute name="Date" ns="accounting" version="1.0" />
       <Attribute name="Amount" ns="accounting" version="1.0" />
 </Attributes>
 
    <Event displayName="purchase" name="purchase"/>
    <Event displayName="deposit" name="deposit">
       <HelpText>depositing funds.</HelpText>
    </Event>
……
 </Category>

You extend system categories by creating category references in your application audit definitions. List the system events that the system category includes, and add new attribute references and events to it.

In this example, a new category references a system category ServiceManagement with a new attribute reference ServiceTime, and a new event restartService:

<CategoryRef name="ServiceManagement" componentType="SystemComponent">
                <Attributes>
                    <Attribute name="ServiceTime" ns="accounting" version="1.0" />
                </Attributes>
 
                <EventRef name="startService"/>
                <EventRef name="stopService"/>
 
                <Event displayName="restartService" name="restartService">
                    <HelpText>restart service</HelpText>
                </Event>
                
</CategoryRef>

28.3 The Audit Metadata Store

The audit metadata store provides the repository for the metadata model and contains component audit definitions, NLS translation entries, runtime policies, and database mapping tables.

Note:

The metadata store is separate from the audit data store.

The audit metadata store supports several critical auditing functions:

The audit framework supports three types of metadata store:

When a new application registers to the audit service, the following audit artifacts are stored in the audit store:

28.4 Integrating the Application with the Audit Framework

Take these steps to integrate your application with the audit framework:

  1. Create an audit definition file, component_events.xml.

  2. Package the component_events.xml file in the application EAR file.

  3. Add the audit event API to the application code to enable it to log audit events.

  4. Integrate with Oracle Business Intelligence Publisher for reporting.

  5. Update the audit event definition and redeploy as needed.

The following sections provide more details on these tasks:

28.5 Create Audit Definition Files

This task involves creating the following files:

component_events.xml File

The component_events.xml file includes these elements:

Here is an example component_events.xml file:

<?xml version="1.0"?>
<AuditConfig xmlns="http://xmlns.oracle.com/ias/audit/audit-2.0.xsd">
    <AuditComponent componentType="ApplicationAudit" major="1" minor="0">
        <Attributes ns="accounting" version="1.0">

            <Attribute name="TransactionType" displayName="Transaction Type" type="string" order="1">
               <HelpText>Transaction type.</HelpText>
           </Attribute>
            <Attribute name="AccountNumber" displayName="Account Number" type="int" order="2">
                <HelpText>Account number.</HelpText>
            </Attribute>
            <Attribute name="Date" displayName="Date" type="dateTime" order="3"/>
            <Attribute name="Amount" displayName="Amount" type="float" order="4">
                <HelpText>Transaction amount.</HelpText>
            </Attribute>
            <Attribute name="Status" displayName="Account Status" type="string" order="5">
                <HelpText>Account status.</HelpText>
            </Attribute>
 
        </Attributes>
 
        <Events>
            <Category displayName="Transaction" name="Transaction">
                <Attributes>
                    <Attribute name="AccountNumber" ns="accounting" version="1.0" />
                    <Attribute name="Date" ns="accounting" version="1.0" />
                    <Attribute name="Amount" ns="accounting" version="1.0" />
                </Attributes>
 
                <Event displayName="purchase" name="purchase">
                    <HelpText>direct purchase.</HelpText>
                </Event>
                <Event displayName="deposit" name="deposit">
                    <HelpText>depositing funds.</HelpText>
                </Event>
                <Event displayName="withdrawing" name="withdrawing">
                    <HelpText>withdrawing funds.</HelpText>
                </Event>
                <Event displayName="payment" name="payment">
                    <HelpText>paying bills.</HelpText>
                </Event>
            </Category>
            <Category displayName="Account" name="Account">
                <Attributes>
                    <Attribute name="AccountNumber" ns="accounting" version="1.0" />
                    <Attribute name="Status" ns="accounting" version="1.0" />
                </Attributes>
 
                <Event displayName="open" name="open">
                    <HelpText>Open a new account.</HelpText>
                </Event>
                <Event displayName="close" name="close">
                    <HelpText>Close an account.</HelpText>
                </Event>
                <Event displayName="suspend" name="suspend">
                    <HelpText>Suspend an account.</HelpText>
                </Event>
            </Category>
        </Events>
        <FilterPresetDefinitions>
            <FilterPresetDefinition displayName="Low" helpText="" name="Low">
                <FilterCategory enabled="partial" name="Transaction">deposit.SUCCESSESONLY(HostId -eq &quot;NorthEast&quot;),withdrawing</FilterCategory>
                <FilterCategory enabled="partial" name="Account">open.SUCCESSESONLY,close.FAILURESONLY</FilterCategory>
            </FilterPresetDefinition>
            <FilterPresetDefinition displayName="Medium" helpText="" name="Medium">
                <FilterCategory enabled="partial" name="Transaction">deposit,withdrawing</FilterCategory>
                <FilterCategory enabled="partial" name="Account">open,close</FilterCategory>
            </FilterPresetDefinition>
            <FilterPresetDefinition displayName="High" helpText="" name="High">
                <FilterCategory enabled="partial" name="Transaction">deposit,withdrawing,payment</FilterCategory>
                <FilterCategory enabled="true" name="Account"/>
            </FilterPresetDefinition>
        </FilterPresetDefinitions>
 
        <Policy filterPreset="Low">
            <CustomFilters>
                <FilterCategory enabled="partial" name="Transaction">purchase</FilterCategory>
            </CustomFilters>
 
        </Policy>
 
    </AuditComponent>
</AuditConfig>

Translation Files

Create the translation files required for your application.

Translation files are used to display audit definition in different languages. Generate the files in XLIFF format; during registration, this information is stored in the audit metadata store along with the component audit event definition.

28.5.1 Understand Mapping and Versioning Rules

When creating your audit definition file, you must be aware of certain rules that the registration service uses to create the audit metadata for the application. This metadata is used to maintain different versions of the audit definition, and to load audit data and generate reports.

28.5.1.1 Version Numbers

Each audit definition must have a major and a minor version number, which are integers, for example, major = 1 minor=3. Any change to an audit event definition requires that the version ID be modified by changing the minor and/or major number.

Version numbers are used by the audit registration service to determine the compatibility of event definitions and attribute mappings between versions.

Note:

These version numbers have no relation to Oracle Fusion Middleware version numbers.

Versioning for Oracle Components

When registering an Oracle component such as Oracle Virtual Directory, the audit registration service checks if this is a first-time registration or an upgrade.

For a new registration, the service:

  1. retrieves the component audit and translation information.

  2. parses and validates the definition, and stores it in the audit metadata store.

  3. generates the attribute-column mapping table, and saves this in the audit metadata store.

For upgrades, the current major and minor numbers for the component in the metadata store are compared to the new major and minor numbers to determine whether to proceed with the upgrade.

Versioning for JavaEE Applications

When modifying your application's audit definition, it is recommended that you set the major and minor numbers as follows:

  • Only increase the minor version number when making version-compatible changes, meaning changes in an audit definition such that the attribute database mapping table generated from the new audit definition should still work with the audit data created by the previous attribute database mapping table.

    For example, suppose the current definition version is major=2 and minor=1. When adding a new event that does not affect the attribute database mapping table, you can change the minor version to 2 (minor=2), while the major version remains unchanged (major=2).

  • Increase major version number when making version changes where the new mapping table is incompatible with the previous table.

28.5.1.2 Custom Attribute to Database Column Mappings

When registering a new component or application, the registration service creates an attribute-to-database column mapping table from the component's custom attributes, and then saves this table to the audit metadata store.

Attribute-database mapping tables are required to ensure unique mappings between your application's attribute definitions and database columns. The audit loader uses mapping tables to load data into the audit store; the tables are also used to generate audit reports from custom database table IAU_CUSTOM.

A custom attribute-database column mapping has properties of attribute name, database column name, and data type.

Each custom attribute must have a mapping order number in its definition. Attributes with the same data type are mapped to the database column in the sequence of attribute mapping order. For example, if the definition file looks like this:

<Attributes ns="accounting" version="1.1">
   <Attribute name="TransactionType" type="string" maxLength="0"     displayName="Transaction Type" order="1"/>
   <Attribute name="AccountNumber" type="int" displayName="Account Number"     order="2">
   <Attribute name="Date" type="dateTime" displayName="Date" order="3"/>
   <Attribute name="Amount" type="float" displayName="Amount" order="4"/>
   <Attribute name="Status" type="string" maxLength="0" displayName="Account     Status" order="5"/>
   <Attribute name="Balance" type="float" displayName="Account Balance"     order="6"/>
</Attributes>

then the mapping is as follows:

<AttributesMapping ns="accounting" tableName="IAU_CUSTOM" version="1.1">
   <AttributeColumn attribute="TransactionType" column="IAU_STRING_001"     datatype="string"/>
   <AttributeColumn attribute="AccountNumber" column="IAU_INT_001"     datatype="int"/>
   <AttributeColumn attribute="Date" column="IAU_DATETIME_001"     datatype="dateTime"/>
   <AttributeColumn attribute="Amount" column="IAU_FLOAT_001" datatype="float"/>
   <AttributeColumn attribute="Status" column="IAU_STRING_002" datatype="string"/>
   <AttributeColumn attribute="Balance" column="IAU_FLOAT_002" datatype="float"/>
</AttributesMapping>

The version ID of the attribute-database column mapping table matches the version ID of the custom attribute group. This allows your application to maintain the backward compatibility of attribute mappings across audit definition versions. For more information about versioning, see Section 28.5.1.1.

28.6 Register Application with the Registration Service

Java EE applications can be registered by packaging component_events.xml and component_events_xlf.jar in the META-INF folder of the application's EAR files. The audit registration service will process them automatically when the application is deployed.

Options include:

Registration parameters are set in the OPSS deployment descriptor opss-application.xml, which is also packaged in the META-INF folder of the application EAR files. Table 28-2 shows the parameters with their options:

Table 28-2 Parameters for Audit Registration Service

Parameter Option Description

opss.audit.registration

OVERWRITE

Register component audit definition whether or not it is registered.

 

UPGRADE

Register component audit definition according to versioning 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.


28.7 Add Application Code to Log Audit Events

Applications can programmatically access the run-time audit service to generate their own audit events using the client API.

28.7.1 Audit Client API

The audit client API is as follows:

Interface AuditService {
 
Auditor getAuditor(String componentType);
 
void register(AuditRegistration auditRegistration);
 
void unregister(AuditRegistration auditRegistration);
 
}
 
 
 
Interface Auditor {
 
                boolean log(AuditEvent ev);
 
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 setInitiator(String initiator);
   public void setAttributeBoolean(String attributeName, Boolean attributeValue);
   public void setAttributeDouble(String attributeName, double attributeValue);
   public void setAttributeDate(String attributeName, Date attributeValue);
   public void setAttributeByteArray(String attributeName, byte[] attributeValue);
   public void setAttributeFloat(String attributeName, float attributeValue);
   public void setAttributeLong(String attributeName, long attributeValue);
   public void setAttributeInt(String attributeName, int attributeValue);
   public void setAttributeString(String attributeName, String attributeValue);
   public void setAttribute(String attributeName, Object attributeValue)
 
}

Subsequent sections explain how to obtain permissions and a run-time auditor instance.

28.7.2 Set System Grants

You must have system grants to get auditor instances from the audit service. In this example, the grant allows application MyApp to call auditService.getAuditor("MyApp") in 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>MyApp</name>
       <actions>read</actions>
      </permission>
   </permissions>
 </grant>

28.7.3 Obtain Auditor Instance

After your application registers to the audit service, it can get its runtime auditor instance programmatically from the OPSS audit service, as shown in the following sample code fragment:

//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);
}

28.8 Integrate with Oracle Business Intelligence Publisher

You can leverage Oracle Business Intelligence Publisher to generate reports from your application's audit data, utilizing the same reporting capabilities available to Oracle components.

The basic steps are as follows:

  1. Use the mapping table to generate an Oracle BI Publisher report template.

  2. Set up the Oracle BI Publisher report service.

  3. Copy the report template into Oracle BI Publisher to view component audit events.

  4. Generate reports with Oracle BI Publisher.

28.9 Update and Maintain Audit Definitions

As the application's audit requirements evolve, you can update the integration to reflect the changes. The steps are as follows:

  1. Update the audit definition file. Be mindful of the versioning rules as you take this step.

  2. Redeploy the application EAR file with the updated event definition file. Alternatively, you can notify the audit registration service of the existence of a newer version.

  3. Verify your changes.