13 Introduction to Oracle Fusion Middleware Audit Framework

The Oracle Fusion Middleware Audit Framework allows you to audit application events. Using this framework, you create events specific to your application, register the application at deployment, and generate audit reports.

This chapter includes the following topics:

What Are the Audit Objectives?

The objectives of audit are to comply with regulations, to monitor business activity, and to obtain data for risk analysis.


To comply with regulations required in the enterprise and to allow the review of compliance policies, customers must audit identity information and user access events on applications and devices across the enterprise, including the following:

  • User profile change

  • Access rights change

  • User access

  • Operational activities, such as like application start and stop, upgrade, and backup


Audit data allows you to monitor activity, to create dashboards, and to build key performance indicators to observe the health of the various systems in the enterprise.


Audit data analysis can be used to assess the efficacy of controls and risks. Based on historical data, a risk score is calculated and assigned to a user. Then, any runtime evaluation of a user access to systems can include risk scores as additional criteria to determine access permission.

Audit support across enterprises is not uniform. For example, there are no standards to generate audit records, format records, or define audit policies. As a result, audit solutions have a number of drawbacks:

  • There is no centralized audit framework.

  • Audit support is inconsistent from application to application.

  • Audit data, audit policies, and configuration are scattered across the enterprise.

  • Cross-component analysis of audit is complex and time-consuming.

  • Scattered data, lack of consistency, and decentralization make the audit solutions fragile with idiosyncrasies.

Audit Terminology

This section introduces several audit terms used in this document.


A component refers to an Oracle Fusion Middleware component.

Audit-Aware Components

An audit-aware component is a component that is integrated with Audit Framework, whose audit policies can be configured and whose events can be audited.

Audit Store

The audit store is a database that has a predefined audit schema and that stores audit events. After you configure the audit store, the audit loader periodically uploads data to this database. Audit data is cumulative and grows in size over time. Ideally, the audit store should be a database not used by other applications but used exclusively by audit. The audit store stores audit events generated by components as well as user applications integrated with Audit Framework.

Audit Definition File

An audit definition file is a file where an applications specify its specific audit rules (such as events and filters) that control audit.

Audit Events

An audit event is an event that is recorded by Audit Framework. This framework provides a set of generic events that you map to application audit common events, such as authentication or policy change. It also allows you to define specific application events and to update audit configuration with Fusion Middleware Control or with WebLogic Scripting Tool (WLST) commands.

Audit Loader

The audit loader is a module of Oracle WebLogic Server that supports audit activity in the server. After you configured the audit store, the audit loader collects audit records of all running components and loads them to the audit store. For Java components, the audit loader starts when the container starts up. To upload events with the audit loader, register the system component with audit (with the registerAudit WLST command) or use the standalone audit loader.

Audit Policy

An audit policy specifies the events that Audit Framework captures for a particular component. You define policies at the component level (so that it applies to a particular component), or at the domain level (so that it applies to all components in the domain).

Bus-Stop Files

A bus-stop file is a local file that contains audit data records. Bus-stop files are simple text files that can be queried easily to look up specific audit events. If audit is configured in the domain, then the data in these files is periodically uploaded to the audit store after a configurable time interval. If audit is not configured in the domain, then the data is kept in bus-stop files.

You correlate and combine audit data from multiple components in a report, for example, when you want to identify authentication failures in all middleware components and instances.

By default, the bus-stop files are located the following directory:

Weblogic Domain Home/servers/server_name/logs/auditlogs

with sub-directories for each component bus-stop files. For example, OPSS bus-stop files are kept in the following directory:

Weblogic Domain Home/servers/server_name/logs/auditlogs/JPS

Event Filters

An event filter is a filter that controls whether the event is logged. For example, a successful login event to a component is logged only for a certain subset of users.

Audit Configuration MBeans

Audit configuration MBeans are the MBeans that manage audit configuration. For Java components and applications, these MBeans are present in WebLogic Administration Server and the audit configuration is centrally managed. For system components, each component has its separate MBeans.

About Auditing with Oracle Fusion Middleware Audit Framework

The following sections describe the Audit Framework support to audit components:

Overview of Oracle Fusion Middleware Audit Framework

The Audit Framework includes the following features:

  • A uniform way to administer audits across Java components, system components, and applications.

  • A Java component audit, including:

    • Support audit for applications that are not audit-aware.

    • The ability to search for audit data at any application level.

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

  • Flexible policies including:

    • Previously seeded audit policies, which capture most common audit events, available for ease of configuration.

    • A tree-like policy structure.

  • The ability to write your own reports based on the published audit schema. For information about audit analysis, see Using Audit Analysis and Reporting.

  • Keeping audit data and files in a common location (the audit store), which simplifies record maintenance.

  • A common audit record format including:

    • Baseline attributes such as outcome (status), event date-time, and user.

    • Event-specific attributes such as the authentication method, source IP address, target user, and resource.

    • Contextual attributes such as the execution context ID (ECID), and session ID.

  • A common and unified way to configure audit policies for the entire domain.

  • Oracle Fusion Middleware support, so that audit:

    • Can be used across Oracle Fusion Middleware components and services.

    • Integrates with Oracle Enterprise Manager Fusion Middleware Control (Fusion Middleware Control).

    • Integrates with WLST.

  • A dynamic metadata model that integrates with the Audit Framework and that allows applications to:

    • Register at any time.

    • Define and log specific audit events.

    • Upgrade definitions independent of release cycles by providing event definitions versions.

About Components and Applications

Oracle Fusion Middleware Audit Framework provides a centralized framework for all Oracle Fusion Middleware products. Specifically, it provides audit for the following applications and components:

  • Middleware Platform - This includes Java components such as OPSS and Oracle Web Services Manager. All the deployed applications leveraging Java components benefit from audit, which happens at the platform level.

  • Java EE applications - The framework provides audit for Java EE applications, including Oracle Java EE-based components, and applications and components can specify their own specific audit events.

  • System Components - For system components, such as Oracle HTTP Server, the framework provides an end-to-end solution similar to that of Java components, including APIs for C and C++ applications.

See also:

Oracle Fusion Middleware Components in Administering Oracle Fusion Middleware.

Understanding Audit

The following sections explain fundamental audit concepts:

The Audit Model

The audit model provides a standards-based, integrated framework for Java EE and SE applications and components across Oracle Fusion Middleware.

Dynamic Model

The Oracle Fusion Middleware Audit Framework features a dynamic audit model that lets applications manage audit event definitions and make version changes independent of release cycles. Audit event definitions can be dynamically updated at redeployment.

Application Life Cycle Support

The model supports all aspects of the application life cycle from design to development to deployment.

Application Registration

A versatile registration lets you register applications with audit in different ways:

  • Declaratively, by packaging the configuration in the META-INF directory of the application Enterprise ARchive (EAR) file.

  • Programmatically, by calling the audit registration methods.

  • At the command line, by calling WLST audit commands.

  • When you create a domain, by specifying security artifacts in a product template.

Distributed Environments

Oracle Fusion Middleware Audit Framework supports distributed environments with multiple servers. It monitors the audit store so changes in audit policies introduced in one server are synchronized with all other servers in the domain.

Consider, for example, a distributed environment consisting of an Administration Server and three Managed Servers. A single security store (that includes audit data) supports all the servers in the domain. When you change an audit policy in the Administration Server with Fusion Middleware Control, then those changes are automatically propagated and synchronized with all other servers in the domain.

See also:

Performing Declarative Audit Registration

registerAudit in WLST Command Reference for Infrastructure Security

How Security Artifacts Are Seeded

About the Audit Store

The audit store contains component event definitions, attribute table mappings, and audit policies.

The audit store includes:

  • Audit registration that allows you:

    • Create, modify, and delete event definition entries.

    • Create attribute database mappings to store audit data.

  • The service that retrieves event definitions and runtime policies.

  • Audit MBean commands that allow you to look up and modify component audit definitions and runtime policies.

The Audit Framework requires a database to store audit data, and this database can be any of the supported ones. For information about supported types, see Supported File, LDAP, and Database Stores.

When a new application registers with audit, the following 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 tables

  • Runtime audit policies

How Audit Data Is Stored

Audit data resides in intermediate or permanent storages.

  • Intermediate storage, in bus-stop files. Each component instance writes to its own separate bus-stop file. Bus-stop files are text-based and easy to query.

  • Permanent storage, in the audit store (if configured in the environment). Audit records generated by all components in the domain are written to the same store.

Advantages to Using a Database Store

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

  • You cannot view domain-level audit data.

  • You cannot obtain reports easily.

And there are advantages to using the audit store:

  • It allows you to generate audit reports.

  • The database store contains records from all components in the domain, whereas the bus-stop contains audit records for one component only.

  • It improves performance.

About the Oracle Fusion Middleware Audit Framework

The Audit Framework provides a set of interfaces for any audit-aware components integrating with it. During runtime, applications may call these APIs to manage audit policies and to audit the necessary information about a particular event happening in the application code. These interfaces allow applications to specify event details and attributes needed to provide the context of the event they want to audit.

Audit Setup: Main Steps

The following list includes the major tasks that you carry out to you set up and maintain audit in your environment:

Understanding the Runtime Audit Event Flow

If the audit store is not configured in your environment, then the audit records are kept in bus-stop files. An application does not stop execution if it is unable to record an audit event.

The audit event flow is best understood by looking at the following sequence that takes place when an audit event occurs within an application running in an environment where you have configured audit:

  1. During application deployment or service start-up, a client Java EE application registers with audit.

  2. The service reads the application audit definition file and updates definitions in the audit store.

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

  4. The Audit Framework checks whether to audit events with this type, status, and attributes. If they must be audited, then the audit function is called to create the event and collect information such as the status, initiator, resource, and ECID.

  5. The event is stored in a bus-stop file. Each application or component has its own bus-stop file.

  6. The audit loader pulls the events from bus-stop files, formats the data using the application's metadata, and moves it to the audit store.

About Audit Attributes, Events, and Event Categories

The Audit Framework supports a model that allows you to specify and define dynamically application audit attribute groups, categories, and events.

The following sections explain this support:

Audit Attribute Groups

Attribute groups provide broad classification of audit attributes and consist of three types: common, generic, and custom.

  • The common attribute group contains system attributes common to all applications, such as the component type, system IP address, and host name. The IAU_COMMON database table contains attributes in this group.

  • Generic attribute groups contain attributes for audit authentication and user provisioning.

  • Custom attribute groups are those defined by an application to meet specific needs. The scope of attributes in a custom group is limited to a component. These attribute groups and attributes are stored in the IAU_CUSTOMn table, where n denotes an integer (1,2, and so on).

About Generic Attribute Groups

A generic attribute group refers to a namespace and a version number, and contains one or more attributes. The following example illustrates an attribute group with the authorization namespace 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>

You refer to 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_ATTRIBUTE_NAME for table columns

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

  • IAU_CODESOURCE as string

  • IAU_PRINCIPALS as string


About Custom Attribute Groups

A custom attribute group refers to a namespace, a version number, and one or more attributes. Each custom attribute incudes:

  • 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 an attribute that can have two or more values of the same data type. These attributes support all data types except for binary types.

The following example illustrates the definition of the Accounting attribute group with the accounting namespace 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>

The following example defines the AccountBalance attribute with multiple values:

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

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

Table 13-1 Audit Attribute Data Types

Attribute Data Type Java Object Type Notes





















Maximum length 2048 bytes



Unlimited length




Audit Events and Event Categories

An event category contains audit events in a functional area. For example, a session category may contain login and logout events significant to the life cycle of a user session. 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

About System Categories and Events

A system category references common and generic attribute groups and includes audit events. System categories are the base set of component event categories and events. Applications can refer to system categories and use the events in them to log audit events and set filter preset definitions.

The following example illustrates the definition of attributes, events, and the UserSession system category with an attribute referencing the common AuthenticationMethod attribute:

<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>
  <Category name="UserSession" displayName="User Sessions">
     <Attribute name="AuthenticationMethod" ns="common" version ="1.0" />
   <Event name="UserLogin" displayName="User Logins" shortName="uLogin"></Event>
   <Event name="UserLogout" displayName="User Logouts" shortName="uLogout" 
   <Event name="Authentication" displayName="Authentication"></Event>
   <Event name="InternalLogin" displayName="Internal Login" shortName="iLogin"
   <Event name="InternalLogout" displayName="Internal Logout" shortName="iLogout"
   <Event name="QuerySession" displayName="Query Session"     shortName="qSession"></Event>
   <Event name="ModifySession" displayName="Modify Session"     shortName="mSession"></Event>
  <Category displayName="Authorization" name="Authorization"></Category>
  <Category displayName="ServiceManagement" name="ServiceManagement"></Category>
About Component and Application Categories

A component or application can extend system categories or define new component event categories.

The following example illustrates the definition of a category with the AccountNumber, Date, and Amount attributes from the accounting attribute group, and it includes the purchase and deposit events:

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

Extend system categories by creating category references in your application audit definitions, listing the system events that the category includes, and adding attribute references and events to the category reference.

The following example illustrates the definition of the ServiceManagement system category reference with the ServiceTime attribute, and the restartService event:

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

Audit Artifact Naming Requirements

The name of a category, an event, or an attribute must:

  • Be an English word

  • Be less than 26 characters

  • Contain characters a-z, A-Z, and numbers 0-9 only

  • Start with a letter

About Audit Definition Files

An audit definition file specifies the application's specific audit rules (such as events and filters). Audit definition files provide a way to translate event definitions to foreign languages. There are two types of audit definition files:

About the component_events.xml File

The component_events.xml file specifies the properties audit uses to log audit events, including the following:

  • Basic properties

    • The component type, which applications use to register with audit and obtain a runtime auditor instance

    • Major and minor version of the application

  • A custom attribute group

  • Event categories with attribute references and events

  • Component level filter definitions

  • Runtime policies

The following example illustrates the definition of this 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 name="AccountNumber" displayName="Account Number" type="int" order="2">
                <HelpText>Account number.</HelpText>
            <Attribute name="Date" displayName="Date" type="dateTime" order="3"/>
            <Attribute name="Amount" displayName="Amount" type="float" order="4">
                <HelpText>Transaction amount.</HelpText>
            <Attribute name="Status" displayName="Account Status" type="string" order="5">
               <HelpText>Account status.</HelpText>
            <Category displayName="Transaction" name="Transaction">
                  <Attribute name="AccountNumber" ns="accounting" version="1.0" />
                  <Attribute name="Date" ns="accounting" version="1.0" />
                  <Attribute name="Amount" ns="accounting" version="1.0" />
                <Event displayName="purchase" name="purchase">
                   <HelpText>direct purchase.</HelpText>
                <Event displayName="deposit" name="deposit">
                   <HelpText>depositing funds.</HelpText>
                <Event displayName="withdrawing" name="withdrawing">
                   <HelpText>withdrawing funds.</HelpText>
                <Event displayName="payment" name="payment">
                   <HelpText>paying bills.</HelpText>
            <Category displayName="Account" name="Account">
                  <Attribute name="AccountNumber" ns="accounting" version="1.0" />
                  <Attribute name="Status" ns="accounting" version="1.0" />
                <Event displayName="open" name="open">
                   <HelpText>Open a new account.</HelpText>
                <Event displayName="close" name="close">
                   <HelpText>Close an account.</HelpText>
                <Event displayName="suspend" name="suspend">
                   <HelpText>Suspend an account.</HelpText>
            <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 displayName="Medium" helpText="" name="Medium">
              <FilterCategory enabled="partial" name="Transaction">deposit,withdrawing</FilterCategory>
              <FilterCategory enabled="partial" name="Account">open,close</FilterCategory>
            <FilterPresetDefinition displayName="High" helpText="" name="High">
              <FilterCategory enabled="partial" name="Transaction">deposit,withdrawing,payment</FilterCategory>
              <FilterCategory enabled="true" name="Account"/>
        <Policy filterPreset="Low">
              <FilterCategory enabled="partial" name="Transaction"> purchase </FilterCategory>

About Runtime Properties

In addition, there are runtime properties you create with Fusion Middleware Control, WLST commands, or during registration. They include the following properties:

  • filterPreset, to specify the audit filter level

  • specialUsers, to specify the users to audit always

  • maxBusstopFileSize, to specify the size of a bus-stop file

About Mapping and Version Rules

Audit registration applies certain rules to create the audit data for the application, and this data is used to maintain different versions of the audit definition and to generate reports.

The following sections explain how the registration works:

What Are Version Numbers?

An audit definition file has a major and a minor version number. Any change introduced to an audit event definition requires updating the version number. These numbers are used by audit registration to determine the compatibility of event definitions and attribute mappings between versions. These version numbers have no relation to Oracle Fusion Middleware version numbers.

Component Version

When you register a component, audit registration checks if this is a first-time registration or an upgrade.

In case of 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 store.

  3. Generates the attribute-column mapping table and saves it in the audit store.

In case of an upgrade, the current version number for the component in the audit store is compared with the new version number to determine whether to proceed with the upgrade.

Java EE Application Version

To reset the version number after you modified an application audit definition, Oracle recommends that you:

  • Increase the minor version number only when making changes in an audit definition that will work with the audit data created by the previous attribute database mapping table.

    For example, suppose the current definition version 2.1. When adding a new event that does not affect the attribute database mapping table, you change the version to 2.2, and leave the major version unchanged (major=2). Similarly, increase the minor version after adding a new attribute.

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

Changes becomes effective after you restart the server.

About Custom Attribute to Database Column Mappings

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

If the number of custom attributes is greater than 100, then you must create additional tables manually. OPSS ships with the tables IAU_CUSTOM and IAU_CUSTOM_01 only.

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. These tables are also used to generate audit reports from custom IAU_CUSTOM database table.

Use the createAuditDBView WLST command to generate a SQL file that creates a database view of the audit definitions for your component.

Understanding the Mapping Table for your Component

A custom attribute-database column mapping has the following properties: 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, the following definition file:

<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"/>

maps to:

<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"/>

The version number of the attribute-database column mapping table matches the version number of the custom attribute group. This allows your application to maintain a backward compatibility of attribute mappings across audit definition versions.

See Also:

createAuditDBView in WLST Command Reference for Infrastructure Security

Oracle Fusion Middleware Audit Framework Reference

What Are Version Numbers?