The Oracle Fusion Middleware Audit Framework (OFM 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:
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
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.
This section introduces several audit terms used in this document.
A component refers to an Oracle Fusion Middleware component.
An audit-aware component is a component that is integrated with OFM Audit Framework, whose audit policies can be configured and whose events can be audited.
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 OFM Audit Framework.
An audit definition file is a file where an applications specify its specific audit rules (such as events and filters) that control audit.
An audit event is an event that is recorded by OFM 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.
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.
An audit policy specifies the events that OFM 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).
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
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 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.
The following sections describe OFM Audit Framework support to audit components:
OFM 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 Chapter 15, "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 OFM 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.
OFM 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.
Understanding Key Oracle Fusion Middleware Concepts in Administering Oracle Fusion Middleware.
The following sections explain fundamental audit concepts:
The audit model provides a standards-based, integrated framework for Java EE and SE applications and components across Oracle Fusion Middleware.
OFM 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.
The model supports all aspects of the application life cycle from design to development to deployment.
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.
OFM 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.
registerAudit in Oracle Fusion Middleware Infrastructure Security WLST Command Reference
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.
OFM 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 Section 4.1, "Supported File, LDAP, and DB 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
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.
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.
OFM 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.
The following list includes the major tasks that you carry out to you set up and maintain audit in your environment:
Understanding the audit architecture, the essential elements of the framework, the flow of actions, and OFM Audit Framework. For information about these tasks, see Section 14.1, "Audit Administration Tasks."
Integrating applications with the framework. For information about integration, see Section 22.1, "Integrating Applications with OFM Audit Framework."
Creating the audit definition file that specifies the application's audit events and how they map to the audit schema. For information about audit definition files, see Section 22.2, "Creating Audit Definition Files."
Registering the application with audit. For information about audit registration, see Section 22.3, "Registering the Application with the Service."
Migrating audit information. For information about audit data migration, see Section 6.6.3, "Migrating Audit Data."
Generating audit reports. For information about audit reporting, see Chapter 15, "Using Audit Analysis and Reporting."
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:
During application deployment or service start-up, a client Java EE application registers with audit.
The service reads the application audit definition file and updates definitions in the audit store.
When a user accesses the component or application, an audit function is called to audit the event.
OFM 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.
The event is stored in a bus-stop file. Each application or component has its own bus-stop file.
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.
OFM 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:
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).
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> </Attribute> </Attributes> ……
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:
GENERIC_ATTRIBUTE_GROUP_NAME for table names
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
IAU_INITIATORGUID as string
A custom attribute group refers to a namespace, a version number, and one or more attributes. Each custom attribute incudes:
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)
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> </Attribute> …… </Attributes>
The following example defines the
AccountBalance attribute with multiple values:
<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>
Table 13-1 shows the attribute data types supported and the corresponding Java object types:
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:
Component and application categories
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
<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>
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
Amount attributes from the
accounting attribute group, and it includes the
<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>
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
<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>
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
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:
component_events.xml file. For information about this file, see About the component_events.xml File.
Translation files, which are used to display audit definition in different languages. For information about translation files, see Section 22.2.2, "Translation Files."
component_events.xml file specifies the properties audit uses to log audit events, including the following:
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
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> <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 "NorthEast"),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>
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
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:
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.
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:
Retrieves the component audit and translation information.
Parses and validates the definition, and stores it in the audit store.
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.
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.
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
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.
createAuditDBView WLST command to generate a SQL file that creates a database view of the audit definitions 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"/> </Attributes>
<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 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.
createAuditDBView in Oracle Fusion Middleware Infrastructure Security WLST Command Reference