| Oracle® Fusion Middleware Application Security Guide 11g Release 1 (11.1.1) Part Number E10043-10 |
|
|
PDF · Mobi · ePub |
| Oracle® Fusion Middleware Application Security Guide 11g Release 1 (11.1.1) Part Number E10043-10 |
|
|
PDF · Mobi · ePub |
This chapter explains how applications (also known as audit clients) can use the Oracle Fusion Middleware Audit Framework to provide auditing capabilities. Release 5.1.2 Patch Set 5 introduces an audit service that enables you to integrate with the audit framework programmatically to log audit events and generate compliance reports using the same capabilities available to Oracle components.
Using the audit service, applications can:
create event definitions without the use of custom tables
register with the audit service when you deploy the application
change event definitions when redeploying the application
change audit configuration settings at run-time
This chapter contains these topics:
As Figure 28-1 shows, Java EE applications running on Oracle WebLogic Server can integrate with and leverage the audit framework seamlessly:
During application deployment or audit service start-up, a client such as a Java EE application or Oracle component registers with the audit service. The registration service updates the metadata store with the latest audit definitions contained in component_events.xml and related files.
See Also:
Section 12.3 for details about the audit flow.The rest of this chapter explains the metadata model, and how you can integrate your applications with the audit flow to log audit events and create audit reports.
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.
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.
Table 28-1 shows the supported attribute data types and the corresponding Java object types:
The common attribute group is stored in the IAU_COMMON database table.
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
A custom attribute group is defined with a namespace, a version number, and one or more attributes.
Attributes consist of:
attribute name
data type
attribute-database column mapping order, which specifies the order in which an attribute is mapped to a database column of a specific data type in the custom attribute table
help text (optional)
maximum length
display name
This example defines attribute group Accounting with namespace accounting and version 1.0:
<Attributes ns="accounting" version="1.0">
<Attribute name="TransactionType" displayName="Transaction Type" type="string" order="1"/>
<Attribute name="AccountNumber" displayName="Account Number" type="int" order="2">
<HelpText>Account number.</HelpText>
</Attribute>
……
</Attributes>
Custom attribute groups and attributes are stored in the IAU_CUSTOM table.
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
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>
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>
The audit metadata store provides the repository for the metadata model and contains component audit definitions, NLS translation entries, runtime policies, and database mapping tables.
Note:
The metadata store is separate from the audit data store.The audit metadata store supports several critical auditing functions:
The audit 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
Take these steps to integrate your application with the audit framework:
Create an audit definition file, component_events.xml.
Package the component_events.xml file in the application EAR file.
Add the audit event API to the application code to enable it to log audit events.
Integrate with Oracle Business Intelligence Publisher for reporting.
Update the audit event definition and redeploy as needed.
The following sections provide more details on these tasks:
This task involves creating the following files:
component_events.xml definition file
translation files
component_events.xml File
The component_events.xml file includes these elements:
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
Custom FilterPresetDefinition- specifies the custom Filter Preset Definition
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 "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>
Translation Files
Create the translation files required for your application.
Translation files are used to display audit definition in different languages. Generate the files in XLIFF format; during registration, this information is stored in the audit metadata store along with the component audit event definition.
When creating your audit definition file, you must be aware of certain rules that the registration service uses to create the audit metadata for the application. This metadata is used to maintain different versions of the audit definition, and to load audit data and generate reports.
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:
retrieves the component audit and translation information.
parses and validates the definition, and stores it in the audit metadata store.
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.
When registering a new component or application, the registration service creates an attribute-to-database column mapping table from the component's custom attributes, and then saves this table to the audit metadata store.
Attribute-database mapping tables are required to ensure unique mappings between your application's attribute definitions and database columns. The audit loader uses mapping tables to load data into the audit store; the tables are also used to generate audit reports from custom database table IAU_CUSTOM.
A custom attribute-database column mapping has properties of attribute name, database column name, and data type.
Each custom attribute must have a mapping order number in its definition. Attributes with the same data type are mapped to the database column in the sequence of attribute mapping order. For example, if the definition file looks like this:
<Attributes ns="accounting" version="1.1"> <Attribute name="TransactionType" type="string" maxLength="0" displayName="Transaction Type" order="1"/> <Attribute name="AccountNumber" type="int" displayName="Account Number" order="2"> <Attribute name="Date" type="dateTime" displayName="Date" order="3"/> <Attribute name="Amount" type="float" displayName="Amount" order="4"/> <Attribute name="Status" type="string" maxLength="0" displayName="Account Status" order="5"/> <Attribute name="Balance" type="float" displayName="Account Balance" order="6"/> </Attributes>
then the mapping is as follows:
<AttributesMapping ns="accounting" tableName="IAU_CUSTOM" version="1.1"> <AttributeColumn attribute="TransactionType" column="IAU_STRING_001" datatype="string"/> <AttributeColumn attribute="AccountNumber" column="IAU_INT_001" datatype="int"/> <AttributeColumn attribute="Date" column="IAU_DATETIME_001" datatype="dateTime"/> <AttributeColumn attribute="Amount" column="IAU_FLOAT_001" datatype="float"/> <AttributeColumn attribute="Status" column="IAU_STRING_002" datatype="string"/> <AttributeColumn attribute="Balance" column="IAU_FLOAT_002" datatype="float"/> </AttributesMapping>
The version ID of the attribute-database column mapping table matches the version ID of the custom attribute group. This allows your application to maintain the backward compatibility of attribute mappings across audit definition versions. For more information about versioning, see Section 28.5.1.1.
Java EE applications can be registered by packaging component_events.xml and component_events_xlf.jar in the META-INF folder of the application's EAR files. The audit registration service will process them automatically when the application is deployed.
Options include:
Deployment - Registers the audit event definition to the audit metadata store if the application is not yet registered.
Redeployment - Upgrades the component audit event definition if the component is already registered. See Section 28.5.1 for details.
Undeployment - Removes the application's audit event definition from the audit metadata store.
Registration parameters are set in the OPSS deployment descriptor opss-application.xml, which is also packaged in the META-INF folder of the application EAR files. Table 28-2 shows the parameters with their options:
Table 28-2 Parameters for Audit Registration Service
| Parameter | Option | Description |
|---|---|---|
|
opss.audit.registration |
OVERWRITE |
Register component audit definition whether or not it is registered. |
|
UPGRADE |
Register component audit definition according to versioning support. |
|
|
DISABLE |
Do not register component audit definition. |
|
|
opss.audit.deregistration |
DELETE (default option) |
Delete component audit definition from audit store when undeploying applications. |
|
DISABLE |
Keep component audit definition in audit store when undeploying applications. |
Applications can programmatically access the run-time audit service to generate their own audit events using the client API.
The audit client API is as follows:
Interface AuditService {
Auditor getAuditor(String componentType);
void register(AuditRegistration auditRegistration);
void unregister(AuditRegistration auditRegistration);
}
Interface Auditor {
boolean log(AuditEvent ev);
boolean isEnabled(String categoryName, String eventType, boolean eventStatus, Map<String, Object> properties);
}
public class oracle.security.jps.service.audit.AuditEvent {
public AuditEvent(AuditContext ctx, String eventType,
String eventCategory, boolean eventStatus, String messageText);
public void setInitiator(String initiator);
public void setAttributeBoolean(String attributeName, Boolean attributeValue);
public void setAttributeDouble(String attributeName, double attributeValue);
public void setAttributeDate(String attributeName, Date attributeValue);
public void setAttributeByteArray(String attributeName, byte[] attributeValue);
public void setAttributeFloat(String attributeName, float attributeValue);
public void setAttributeLong(String attributeName, long attributeValue);
public void setAttributeInt(String attributeName, int attributeValue);
public void setAttributeString(String attributeName, String attributeValue);
public void setAttribute(String attributeName, Object attributeValue)
}
Subsequent sections explain how to obtain permissions and a run-time auditor instance.
You must have system grants to get auditor instances from the audit service. In this example, the grant allows application MyApp to call auditService.getAuditor("MyApp") in AccessController.doPrivileged block:
<grant>
<grantee>
<codesource>
<url>file:${oracle.deployed.app.dir}/MyApp${oracle.deployed.app.ext}</url>
</codesource>
</grantee>
<permissions>
<permission>
<class>oracle.security.jps.service.audit.AuditStoreAccessPermission</class>
<name>MyApp</name>
<actions>read</actions>
</permission>
</permissions>
</grant>
After your application registers to the audit service, it can get its runtime auditor instance programmatically from the OPSS audit service, as shown in the following sample code fragment:
//Gets audit service instance
final AuditService auditService = JpsServiceLocator.getServiceLocator().lookup(AuditService.class);
//Gets Auditor instance for application 'MyApp'
Auditor auditor = AccessController.doPrivileged(
new PrivilegedExceptionAction<Auditor>() {
public Auditor run() throws AuditException {
return auditService.getAuditor("MyApp");
}
});
final String category = "Transaction";
final String eventName = "deposit";
//Check if event 'deposit' is enabled in filtering.
boolean enabled = auditor.isEnabled(category, eventName, "true", null);
if (enabled) {
AuditContext ctx = new AuditContext();
String message = "deposit transaction";
//Creates an audit event
AuditEvent ev = new AuditEvent(ctx, eventName, category, "true", message);
//Sets event attributes
ev.setInitiator("johnsmith");
ev.setAttributeInt("accounting:AccountNumber", 2134567);
ev.setAttributeDate("accounting:Date", new Date());
ev.setAttributeFloat("accounting:Amount", 100.00);
//Logs audit event
boolean ret = auditor.log(event);
}
You can leverage Oracle Business Intelligence Publisher to generate reports from your application's audit data, utilizing the same reporting capabilities available to Oracle components.
The basic steps are as follows:
Use the mapping table to generate an Oracle BI Publisher report template.
Set up the Oracle BI Publisher report service.
Copy the report template into Oracle BI Publisher to view component audit events.
Generate reports with Oracle BI Publisher.
As the application's audit requirements evolve, you can update the integration to reflect the changes. The steps are as follows:
Update the audit definition file. Be mindful of the versioning rules as you take this step.
Redeploy the application EAR file with the updated event definition file. Alternatively, you can notify the audit registration service of the existence of a newer version.
Verify your changes.
|
 Copyright © 2003, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|