12 Introduction to Oracle Fusion Middleware Audit Service

In Oracle Fusion Middleware 11g Release 1 (11.1.1), auditing provides a measure of accountability and answers the "who has done what and when" types of questions. This chapter introduces the audit service in Oracle Fusion Middleware. It contains the following topics:

12.1 Benefits and Features of the Oracle Fusion Middleware Audit Framework

This section contains these topics:

12.1.1 Objectives of Auditing

With compliance becoming an integral part of any business requirement, audit support is also becoming a focus in enterprise deployments. Customers are looking for application vendors to provide out-of-the-box audit support. In addition, middleware customers who are deploying custom applications would like to centralize the auditing of their deployed applications wherever audit is appropriate.

IT organizations are looking for several key audit features driven by compliance, monitoring, and analytics requirements.

Compliance

Compliance is obviously a major requirement in the enterprise. With regulations such as Sarbanes-Oxley (financial) and Health Insurance Portability and Accountability Act (healthcare), many customers must now be able to audit on identity information and user access on applications and devices. These include events like:

  • User profile change

  • Access rights changes

  • User access activity

  • Operational activities like starting and stopping applications, upgrades, and backups

This allows compliance officers to perform periodic reviews of compliance policies.

Monitoring

The audit data naturally provides a rich set of data for monitoring purpose. In addition to any log data and component metrics that are exposed, audit data can be used to create dashboards and to build Key Performance Indicators (KPIs) for alerts to monitor the health of the various systems on an ongoing basis.

Analytics

Audit data can also be used in assessing the efficacy of controls through analysis on the audit data. The data can also be used for risk analysis. Based on historical data, a risk score can be calculated and assigned to any user. Any runtime evaluation of user access can include the various risk scores as additional criteria to protect access to the systems.

12.1.2 Today's Audit Challenges

To satisfy the audit requirements, IT organizations often battle with the deficiencies in audit support for their deployed applications. There is no reliable standard for:

  • Audit Record Generation

  • Audit Record Format and Storage

  • Audit Policy Definition

As a result, today's audit solutions suffer from a number of key drawbacks:

  • There is no centralized audit framework.

  • The quality of audit support is inconsistent from application to application.

  • Audit data is scattered across the enterprise.

  • Complex data correlation is required before any meaningful cross-component analysis can be conducted.

  • Audit policies and their configurations are also scattered.

These factors are costing IT organization considerable amount of time and resources to build and maintain any reasonable audit solutions. With the data scattered among individual silos, and the lack of consistency and centralization, the audit solutions also tend to be fragile with idiosyncrasies among applications from different vendors with their current audit capabilities.

12.1.3 Oracle Fusion Middleware Audit Framework in 11g

Oracle Fusion Middleware Audit Framework, introduced in 11g Release 1 (11.1.1), is designed to provide a centralized audit framework for the middleware family of products. The framework provides an audit service for the following:

  • Middleware Platform - This includes Java components such as Oracle Platform Security Services (OPSS) and Oracle Web Services. These are components that are leveraged by applications deployed on the middleware. Indirectly, all the deployed applications leveraging these Java components will benefit from the audit framework auditing events that are happening at the platform level.

  • Java EE applications - The objective is to provide a service for Java EE applications, including Oracle's own Java EE-based components. Java EE applications are able to create application-specific audit events.

  • System Components - For system components in the middleware that are managed by Oracle Process Manager and Notification Server, the audit service also provides an end-to-end structure similar to that for Java components.

  • C Components - the framework provides audit C API for C/C++ based applications to integrate with the audit service.

See Also:

Understanding Key Oracle Fusion Middleware Concepts in the Oracle Fusion Middleware Administrator's Guide.

12.2 Overview of Audit Features

Key features of the Oracle Fusion Middleware Audit Framework and audit service include:

  • A uniform system for administering audits across a range of Java components, system components, and applications

  • Extensive support for Java component auditing, which includes:

    • support for Oracle Platform Security Services auditing for non-audit-aware applications

    • the ability to search for audit data at any application level

  • Capturing authentication history/failures, authorization history, user management, and other common transaction data

  • Flexible audit policies

    • pre-seeded audit policies, capturing customers' most common audit events, are available for ease of configuration

    • tree-like policy structure simplifies policy setup

  • Prebuilt compliance reporting features

    • Oracle Fusion Middleware Audit Framework provides out-of-the-box analytical reporting capabilities within Oracle BI Publisher; data can be analyzed on multiple dimensions (Execution Context ID (ECID), user ID, and so on) across multiple components. These reports can also be customized according to your preferences.

    • Reports are based on centralized audit data.

    • Customers can customize the reports or write their own based on the published audit schema.

      See Chapter 14, "Using Audit Analysis and Reporting" for details.

  • Audit record storage

    Audit data store (database) and files (bus-stop) are available. Maintaining a common location for all audit records simplifies maintenance.

    Using an audit data store lets you generate reports with Oracle Business Intelligence Publisher.

  • Common audit record format

    Highlights of the audit trail include:

    • baseline attributes like outcome (status), event date-time, user, and so on

    • event-specific attributes like authentication method, source IP address, target user, resource, and so on

    • contextual attributes like the execution context ID (ECID), session ID, and others

  • Common mechanism for audit policy configuration

    Oracle Fusion Middleware Audit Framework offers a unified method for configuring audit policies in the domain.

  • Leverages the Oracle Fusion Middleware 11g infrastructure

    • is usable across Oracle Fusion Middleware 11g components and services such as Oracle Web Services Manager, Oracle Internet Directory, Oracle Virtual Directory, and Oracle Directory Integration and Provisioning

    • integrates with Oracle Enterprise Manager Fusion Middleware Control for UI-based configuration and management

    • integrates with wlst for command-line, script-based configuration

    • leverages the SPI infrastructure of Oracle Platform Security Services

  • Utilizes a dynamic metadata model to enable applications to integrate with the audit framework:

    • applications can register with the audit service at any time

    • simplifies the ability of applications to leverage the audit framework to define and log audit events

    • provides versioning of event definitions and enables audit clients to upgrade definitions independent of release cycles.

12.3 Oracle Fusion Middleware Audit Framework Concepts

This section introduces basic concepts of the Oracle Fusion Middleware Audit Framework:

12.3.1 The Audit Architecture

Figure 12-1 shows the architecture of the Oracle Fusion Middleware Audit Framework:

Figure 12-1 Audit Architecture

Surrounding text describes Figure 12-1 .

The figure illustrates essential elements of the architecture, including development and run-time services, the audit event flow, and key features, which are described below.

12.3.1.1 The Audit Service Model

At the heart of the framework is the audit service model, which like other OPSS services, provides a standards-based, integrated framework for Java EE and SE applications and Oracle components alike.

Used across Oracle Fusion Middleware, this model enables you to conveniently leverage the platform's audit features, and includes:

  • A dynamic audit matadata model that allows audit clients to manage audit event definitions and make version changes independent of build and release cycles. Audit event definitions can be dynamically updated at redeployment.

  • Support for all aspects of the application lifecycle from design to development to deployment.

  • A registration service to register your applications to the audit service

    • declaratively; Java EE applications do so by packaging an XML configuration in ear files in the META-INF directory at deployment.

    • programatically , by invoking the audit registration API.

    • at the command line, through OPSS scripts.

12.3.1.2 Audit APIs

These APIs are provided by the audit framework for any audit-aware components integrating with the Oracle Fusion Middleware Audit Framework. During runtime, applications may call these APIs where appropriate to manage audit policies and to audit the necessary information about a particular event happening in the application code. The interface allows applications to specify event details such as username and other attributes needed to provide the context of the event being audited.

The audit framework provides these APIs:

  • audit service API

  • audit client API

  • audit administration service API

See Chapter 28 for details.

12.3.1.3 Run-time Support and Audit Event Flow

The process can be illustrated by looking at the actions taken in the framework when an auditable event (say, login) occurs within an application server instance:

Note:

The architecture shown in Figure 12-1 contains an audit data store; if your site did not configure an audit data store, the audit records reside in the bus-stop files.

  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.

  2. The service reads the application's pre-configured audit definition file and updates the metadata store with the audit definitions.

  3. When a user accesses the component or application, an audit API function is called to audit the event.

  4. The audit framework checks if events of this type, status, and with certain attributes need to be audited.

  5. If so, the audit function is invoked to create the audit event structure and collect event information like the status, initiator, resource, ECID, and so on.

  6. The event is stored on a local file in an intermediate location known as the bus-stop; each component has its own bus-stop.

  7. If a database is configured for an audit store, the audit loader pulls the events from the bus-stops, uses the application's metadata to format the data, and moves the data to the audit store.

  8. Reports can also be generated from the audit data using Oracle BI Publisher. A set of pre-defined reports are available. (See Chapter 14, "Using Audit Analysis and Reporting".)

Application Behavior in Case of Audit Failure

It is important to note that an application does not stop execution if it is unable to record an audit event for any reason.

12.3.2 Key Technical Concepts

This section introduces key concepts in the Oracle Fusion Middleware Audit Framework.

Audit-Aware Components

The term "audit-aware" refers to components that are integrated with the Oracle Fusion Middleware Audit Framework so that audit policies can be configured and events can be audited for those components. Oracle Internet Directory is an example of an audit-aware component.

Stand-alone applications can integrate with the Oracle Fusion Middleware Audit Framework through configuration with the jps-config.xml file. For details, see see Chapter 28.

Audit Metadata Store

The audit metadata store contains audit event definitions for components and for applications integrated with the audit framework.

For details, see Section 12.3.3.

Audit Data Store

The audit data store is the repository of audit event records. It is a database that contains a pre-defined Oracle Fusion Middleware Audit Framework schema, created by Repository Creation Utility (RCU). Once the audit data store is configured, all the audit loaders are aware of the store and upload data to it periodically. The audit data in the store is expected to be cumulative and will grow overtime. Ideally, this should not be an operational database used by any other applications - rather, it should be a standalone database used for audit purposes only.

The audit database can store audit events generated by Oracle components as well as user applications integrated with the audit framework.

Note:

The metadata store is separate from the audit data store.

For details about the data store, see Section 12.3.4.

Audit Definition Files

Applications use audit definition files to specify to the audit service the auditing rules (events, filters, and so on) that will govern audit actions.

For details, see Section 12.5.

Audit Events

The Oracle Fusion Middleware Audit Framework provides a set of generic events for convenient mapping to application audit events. Some of these include common events such as authentication. The framework also allows applications to define application-specific events.

These event definitions and configurations are implemented as part of the audit service in Oracle Platform Security Services. Configurations can be updated through Enterprise Manager (UI) and WLST (command-line tool)

Audit Loader

The Audit Loader is a module of the Oracle WebLogic Server instance and supports audit activity in that instance. When an audit data store is configured, audit loader is responsible for collecting the audit records for all components running in that instance and loading them to the data store.

For Java components, the audit loader is started as part of the container start-up. For system components, the audit loader is a periodically spawned process that is invoked by OPMN.

Audit Policy

An audit policy is a declaration of the type of events to be captured by the audit framework for a particular component. For Java components, the audit policy is defined at the domain level. For system components, the audit policy is managed at the component instance level.

Oracle Fusion Middleware Audit Framework provides several pre-defined policy types:

  • None (audit is disabled for the component)

  • Low (definition is component-dependent)

  • Medium (definition is component-dependent)

  • High (definition is component-dependent)

  • Custom (implements filters to narrow the scope of audited events)

Audit Policy Component Type

This refers to the component type to be audited; for example, Oracle Internet Directory is a source of auditable events during authentication.

For lists of the events that can be audited for each component, see Section C.1, "Audit Events".

Audit Service

The audit service model provides a standards-based, integrated framework for Java EE and SE applications to leverage audit features.

Bus-stop

Bus-stops are local files containing audit data records before they are pushed to the audit data store. In the event that no audit data store is configured, audit data remains in these bus-stop files. The bus-stop files are simple text files that can be queried easily to look up specific audit events. When an audit data store is in place, the bus-stop acts as an intermediary between the component and the audit data store. The local files are periodically uploaded to the audit data store based on a configurable time interval.

A key advantage of the audit data store is that audit data from multiple components can be correlated and combined in reports, for example, authentication failures in all middleware components, instances and so on.

Event Filters

Certain audit events implement filters to control when the event is logged. For example, a successful login event for the Oracle Internet Directory component may be filtered for specific users.

For details, see Section 13.3, "Managing Audit Policies".

Configuration MBeans

All audit configuration is managed through audit configuration MBeans. For Java components and applications, these MBeans are present in the domain administration server and the audit configuration is centrally managed. For system components, separate MBean instances are present for every component instance. Enterprise Manager UI and command-line tools manage Audit configuration using these MBeans.

Oracle Business Intelligence Publisher

The data in the audit data store is exposed through pre-defined reports in Oracle Business Intelligence Publisher. The reports allow users to drill down the audit data based on various criteria. For example:

  • Username

  • Time Range

  • Application Type

  • Execution Context Identifier (ECID)

You can also use Oracle Business Intelligence Publisher to create your own audit reports.

Oracle Platform Security Services

Oracle Platform Security Services, a key component of the Oracle Fusion Middleware 11g, is the Oracle Fusion Middleware security implementation for Java features such as Java Authentication and Authorization Service (JAAS) and Java EE security.

For more information about OPSS, see Section 1.1, "What is Oracle Platform Security Services?".

12.3.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 which contains the actual .

The audit metadata store supports several critical auditing functions:

  • The audit registration service creates, modifies, and deletes event definition entries.

  • The audit runtime service retrieves event definitions and runtime policies.

  • The audit data loader creates attribute database mappings to store audit data.

  • Audit MBean commands look up and modify component audit definitions and runtime policies.

The audit framework supports three types of metadata store:

  • XML file-based

  • database

  • LDAP

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

  • audit event definitions including custom attribute group, categories, events, and filter preset definitions

  • localized translation entries

  • custom attribute-database column mapping table

  • run-time audit policies

12.3.4 Audit Data Storage

As shown in Figure 12-1, audit data can reside in two types of storage:

  • bus-stop files for intermediate storage of audit data. Each component instance writes to its own bus-stop.

    Bus-stop files are the default out-of-the-box storage mechanism for audit records:

    • For Java components, there is one bus-stop for each Oracle WebLogic Server instance. Audit records generated for all Java EE components running in a given Oracle WebLogic Server instance are stored in the same bus-stop.

    • For system components, there is a separate bus-stop for each component; thus, for example, each instance of Oracle Internet Directory has its own bus-stop.

    Bus-stop files are text-based and easy to query. For further details, see Section 12.3.1, "The Audit Architecture"

  • permanent storage in a database; this is known as the audit data store.

    If using a database, audit records generated by all components in all Oracle Fusion Middleware 11g instances in the domain are stored in the same store. You must use an audit data store to utilize Oracle Business Intelligence Publisher reports.

You can move from file-based storage to an audit data store. This requires a specific configuration procedure. See Section 13.2.3, "Configure a Database Audit Data Store for Java Components" for details.

Advantages of Using a Database Store

Having the audit records in the bus-stop files has some practical limitations:

  • you cannot view domain-level audit data

  • reports cannot be run on Oracle BI Publisher

Thus, there are certain advantages to using a database audit data store:

  • You can use Oracle Business Intelligence Publisher for reporting.

  • The database store centralizes records from all components in the domain, whereas the bus-stop stores audit records on a per-instance basis.

  • performance may be improved compared to file-based storage

For these reasons, Oracle recommends that customers switch to a database store for enhanced auditing capabilities.

12.3.5 Analytics

With Oracle Fusion Middleware 11g, you can utilize Oracle Business Intelligence Publisher as a full-featured tool for structured reporting. You can also use your own reporting application.

A large number of pre-defined reports are available in Oracle Business Intelligence Publisher, such as:

  • Users created/deleted

  • User transactions

  • Authentication and authorization failures

  • Policy violations

With Oracle Business Intelligence:

  • You can select records based on criteria like username, date-time range, and so on.

    Note that Oracle Business Intelligence works with the database audit store only, and is not usable with bus-stop files.

BI Publisher page
Description of the illustration cafintro1.gif

The pre-defined audit report types available with Oracle Business Intelligence include:

  • errors and exceptions

  • operational

  • user activity

  • authentication and authorization history

  • transaction history

For further details, see Section C.2, "Pre-built Audit Reports." You can also use the audit schema details to create custom audit reports as needed.

12.3.6 Understanding the Audit Lifecycle

From the standpoint of an administrator auditing into an environment consisting of Oracle Fusion Middleware components and applications, the key phases of implementing a functional audit system are as follows:

  • Understand the architecture of the Common Audit Framework.

    For a review of the essential elements of the framework, the flow of actions, and the features of the audit service model, see Section 12.3.1.

  • Integrate applications with the audit framework.

    For details about integration steps, see Section 28.2.

  • Create the audit definition files that describe your application's audit events and how they map to the audit schema.

    For details on this topic, see Section 28.3.

  • Register the application with the audit service.

    There are various ways to enable registration. For details, see Section 28.4.

  • Migrate audit information from test to production.

    See Section 6.6.3.

  • Generate audit reports.

    Descriptions of the tools and techniques of audit reporting appear in Chapter 14 and Section 28.7.

12.4 The 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.

Topics include:

12.4.1 Naming Conventions for Audit Artifacts

The following naming restrictions apply to category, event and attribute names:

  • They must be in English only

  • They must be less than 26 characters

  • They can contain only the characters a through z, A through Z, and numbers 0 through 9

  • They must start with a letter.

12.4.2 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.

12.4.2.1 Audit Attribute Data Types

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

Table 12-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[]

 

12.4.2.2 Common Attribute Groups

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

12.4.2.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

12.4.2.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 - This property 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

  • size - This property denotes how many values of the same data type the attribute can have. The default size value is 1. A size greater than 1 denotes a multi-valued attribute which can have two or more values of the same data type. The multi-value attribute supports all data types except for binary.

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>

The following example shows a multi-valued attribute named AccountBalance:

<Attribute order="3" displayName="AccountBalance" type="double" name="Balance" size="2" sinceVersion="1.1">
            <MultiValues>
                <MultiValueName displayName="Previous Balance" index="0">
                     <HelpText>the previous account balance</HelpText>
                </MultiValueName>
                <MultiValueName displayName="Current Balance" index="1"/>
            </MultiValues>
</Attribute>

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

12.4.3 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

12.4.3.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>

12.4.3.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>

12.5 About Audit Definition Files

There are two types of definition files:

  • component_events.xml definition file

  • translation files

12.5.1 The component_events.xml File

The component_events.xml file specifies the properties the audit service needs to log audit events, including:

  • basic properties - and the major and minor version

    • the component type, which is the property that applications use to register with the audit service and obtain runtime auditor instances

    • Major and minor version of the application.

  • at most one custom attribute group

  • event categories with attribute references and events

  • component level filter definitions

  • runtime policies, which include:

    • filterPreset - specifies the audit filter level

    • specialUsers - specifies the users to always audit

    • maxBusstopDirSize

    • maxBusstopFileSize

    For details about run-time policies, see Section 13.3.

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>

12.5.2 Translation Files

Translation files are used to display audit definition in different languages.

12.5.3 Understand Mapping and Versioning Rules

The registration service uses certain rules 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.

12.5.3.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.

12.5.3.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.

Viewing Audit Definitions for your Component

You can use the OPSS script command createAuditDBView to create a database view of the audit definitions of your component.

For details about command syntax, see Section C.4.9.

Using the createAuditDBView command requires an understanding of how your component's attributes are mapped to database columns; see the discussion below for details.

Understanding the Mapping Table for your Component

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 12.5.3.1.