This chapter explains how to use Oracle Fusion Middleware Audit Framework (OFM Audit Framework) to audit application events. Using this framework, you create event definitions, register the application with the service at deployment, modify audit configuration at runtime, and generate reports.
This chapter includes the following topics:
To integrate your application with OFM Audit Framework, you perform the tasks explained in the following sections:
The following sections explain how to create the component-event.xml
and translation files:
When you create the component-events.xml
audit definition file, keep in mind the following points:
Any change to an audit event definition requires that the version ID be modified by changing the minor or major numbers.
There must be a 1-to-1 correspondence between tables for your application attribute definitions and database columns. Each custom attribute must have a corresponding order number in its definition.
The following procedure explains hot to generate the XLIFF (XML Localization Interchange File Format) translations files and pack them in the component_events_xlf.jar
file. At deployment and during registration, this information is stored in the audit store along with the component event definition.
Run a command like the following to generate XLIFF files:
java -cp $MW_HOME/oracle_common/modules/oracle.jps_12.2.1/jpsaudit.jar: $MW_HOME/oracle_common/modules/oracle.jps_12.2.1/jps-api.jar oracle.security.audit.tools.NewXlfGenerator -s /tmp/comp_events.xml -t /tmp/comp_events.xlf
Translate the generated xlf
file for the supported languages. This xlf
file contains translation units as well as help texts for all categories, events, and attributes. The prefixes for these are Category_, Event_ and Attribute_.
Package the translated files in a JAR file.
The following sections explain the various mechanisms by which applications can register with audit:
Note:
The use of domain extension templates is the preferred approach to registration. For information about templates, see Using Domain Extension Templates for Audit Artifacts.This section explains the two methods by which declarative registration of audit definitions occurs:
Default Audit Registration
Custom Audit Registration
By default, the following registration activity occurs when you deploy, redeploy or undeploy the application:
Deployment - Registers the audit event definition to the audit store if the application is not yet registered.
Redeployment - Upgrades the component event definition if the component is already registered.
Undeployment - Removes the application's audit event definition from the audit store.
A simple database view to query audit records is created in the IAU
schema at registration. This occurs for all except the component, for which Oracle Fusion Middleware Repository Creation Utility creates the view.
The parameters to customize audit registration are set in the weblogic-application.xml
WebLogic deployment descriptor. This file is packaged in the META-INF
directory of the application Enterprise ARchive (EAR) file. For information about packaging requirements, see Section 23.5.
A simple database view to query audit records is created in the IAU
schema by audit registration, unless view creation is explicitly disabled.
Table 22-1 shows the parameters with their options:
Table 22-1 Parameters for Audit Registration
Parameter | Option | Description |
---|---|---|
opss.audit.registration |
OVERWRITE |
Register component audit definition whether or not it is registered. |
UPGRADE (default option) |
Register component audit definition according to version 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. |
|
opss.audit.componentType |
Set the custom component type. (Optional) |
|
opss.audit.iauview |
SIMPLE INDEXABLE DISABLE |
|
The following example illustrates the use of registration and deregistration options:
<wls:application-param> <wls:param-name>opss.audit.registration</wls:param-name> <wls:param-value>DISABLE</wls:param-value> </wls:application-param> <wls:application-param> <wls:param-name>opss.audit.registration</wls:param-name> <wls:param-value>OVERWRITE</wls:param-value> </wls:application-param> <wls:application-param> <wls:param-name>opss.audit.unregistration</wls:param-name> <wls:param-value>DELETE</wls:param-value> </wls:application-param> <wls:application-param> <wls:param-name>opss.audit.unregistration</wls:param-name> <wls:param-value>DISABLE</wls:param-value> </wls:application-param>
The following example shoes how to register an application with audit programmatically:
AuditService auditService = JpsServiceLocator.getServiceLocator().lookup(AuditService.class); AuditRegistration auditReg = <instance of AuditRegistration implementation>; AccessController.doPrivileged(new PrivilegedExceptionAction<Object>() { public Object run() throws AuditException, IOException { auditService.register(auditReg); return null; } });
Calling the auditService.register
method requires that the application be granted the AuditStoreAccessPermission
permission with create, upgrade actions. For information about specifying grants, see Setting System Grants.
Here is a programmatic registration example:
JpsContextFactory ctxFactory = JpsContextFactory.getContextFactory(); JpsContext ctx = ctxFactory.getContext(); //get audit service final AuditService auditService = ctx.getServiceInstance(AuditService.class); //create an audit registration instance final AuditRegistration auditReg = new SampleRegistration(); //call API to register audit event definition AccessController.doPrivileged(new PrivilegedExceptionAction<Object>() { public Object run() throws AuditException, IOException { auditService.register(auditReg); return null; } });
Registration creates a database view to query audit records from the database. To add logic to manage view creation or to disable this feature, implement the interface oracle.security.jps.service.audit.AuditRegistrationExt
, an interface that extends AuditRegistration
:
SampleRegistration.java class SampleRegistration implements AuditRegistrationExt { /* methods from Audit Registration go here */ public AuditRegistrationExt.TYPE getIAUViewSupportType() { // add app specific logic here to determine the type return AuditRegistrationExt.TYPE.<type>; // where type is SIMPLE, INDEXABLE, DISABLE } }
To register your application with audit, use the registerAudit
WebLogic Scripting Tool (WLST) command. This command also allows to create an audit view with the registration:
registerAudit(xmlFile, [xlfFile], componentType, [mode=OVERWRITE|UPGRADE], [createView=SIMPLE|INDEXABLE|DISABLE])
where SIMPLE
is the default if no value is provided for createView
.
See registerAudit in the Oracle Fusion Middleware Infrastructure Security WLST Command Reference.
When a domain is created or extended, applications can specify the seeding of application-specific security data in the security store. For information about artifact seeding, see Section 7.1, "How Security Artifacts Are Seeded."
Java EE applications can register with audit by means of domain extension templates containing the component_events.xml
and component_events_xlf.jar
files. Audit registration processes them automatically when you deploy the application. For information about the files included in the template, see Section 7.4, "Layered Component Security Artifacts."
The OFM Audit Framework allows you to query audit data, and get and set audit policies programmatically. First use the following method to obtain an AuditService
instance:
AuditService auditService = JpsContextFactory.getContextFactory().getContext().getServiceInstance(AuditService.class); AuditAdminService auditAdminService = auditService.getAdminService();
The following sections explain how to use this instance to query and view audit data:
To query audit data, use any of the following methods:
Set<String> getComponentNames() throws AuditException; Map<String, ? extends AttributeGroup> getGenericAttributeGroups() throws AuditException; Collection<? extends EventCategory> getSystemEvents() throws AuditException; ComponentDefinition getComponentDef(String componentType) throws AuditException; AttributesDatabaseMap getAttributesMap(String componentType) throws AuditException; AttributesDatabaseMap getSystemAttributesMap() throws AuditException;
The following example demonstrates how to query audit data:
//search events and attributes for a component Set<String> components = auditAdminService.getComponentNames(); for (String componentType : components) { ComponentDefinition componentDef = auditAdminService.getComponentDef(componentType); //get attributes of a component AttributeGroup attrGroup = componentDef.getAttributes(); for (AuditAttribute attr : attrGroup.getAttributes()) { AuditAttribute.DataType type = attr.getAttributeType(); String attrName = attr.getName(); } //get events of a component Collection<? extends EventCategory> events = componentDef.getEvents(); for (EventCategory category : events) { if (category.isComponentSpecific()) { // isComponentSpecific() is true means the category is belong to a component, otherwise is system category Collection<? extends Event> categoryEvents = category.getAllEvents(); } } }
To retrieve and set an audit policy, use the following methods:
AuditPolicy getAuditPolicy(String componentType) throws AuditException; void setAuditPolicy(String componentType, AuditPolicy auditPolicy) throws AuditException;
The following example shows how to use these methods to obtain and set the audit policy for a component:
//get runtime policy for component JPS final String componentType = "JPS"; AuditPolicy policy = auditAdminService.getAuditPolicy(componentType); String filterLevel = policy.getFilterLevel(); //set runtim policy for component JPS final AuditPolicy newPolicy = new AuditPolicy("None", null, null); //setAuditPolicy() requires AuditStoreAccessPermission(<componentType>, "modify"); AccessController.doPrivileged(new PrivilegedExceptionAction<Object>(){ public Object run() throws AuditException { auditAdminService.setAuditPolicy(componentType, newPolicy); return null; } });
The following sections illustrate how applications can use the OFM Audit Framework to access audit programmatically and generate their own audit events:
The OFM Audit Framework provides the following class and interfaces:
Interface AuditService { Auditor getAuditor(String componentType); void register(AuditRegistration auditRegistration); void unregister(AuditRegistration auditRegistration); } Interface Auditor { boolean log(AuditEvent ev); boolean isEnabled(); 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 setApplicationName(String applicationName) public void setAttribute(String attributeName, Object attributeValue) public void setAttributeBoolean(String attributeName, boolean attributeValue) public void setAttributeBoolean(String attributeName, Boolean attributeValue) public void setAttributeBooleans(String attributeName, boolean[] values) public void setAttributeByteArray(String attributeName, byte[] attributeValue) public void setAttributeDate(String attributeName, Date attributeValue) public void setAttributeDates(String attributeName, Date[] values) public void setAttributeDouble(String attributeName, double attributeValue) public void setAttributeDoubles(String attributeName, double[] values) public void setAttributeFloat(String attributeName, float attributeValue) public void setAttributeFloats(String attributeName, float[] values) public void setAttributeInt(String attributeName, int attributeValue) public void setAttributeInts(String attributeName, int[] values) public void setAttributeLong(String attributeName, long attributeValue) public void setAttributeLongs(String attributeName, long[] values) public void setAttributeString(String attributeName, String attributeValue) public void setAttributeStrings(String attributeName, String[] values) public void setComponentName(String componentName) public void setComponentType(String componentType) public void setContextFields(String contextFields) public void setECID(String ecid) public void setEventCategory(String category) public void setEventDefinition(Object eventDefinition) public void setEventStatus(boolean status) public void setEventTimestamp(long eventTimestamp) public void setEventType(String eventType) public void setFailureCode(String failureCode) public void setHostId(String hostId) public void setHostNetworkAddr(String hostNetworkAddr) public void setInitiator(String initiator) public void setInstanceId(String instanceId) public void setMessageText(String messageText) public void setModuleId(String moduleId) public void setOracleHome(String oracleHome) public void setOracleInstance(String oracleInstance) public void setProcessId(String processId) public void setRemoteIP(String value) public void setResource(String value) public void setRID(String rid) public void setRoles(String value) public void setTarget(String value) public void setTargetComponentType(String targetComponentType) public void setThreadId(String threadId) public void setTransactionId(String transactionId) }
To set permissions and to obtain an auditor instance, see Setting System Grants, and Obtaining the Auditor Instance.
Applications must have the AuditStoreAccessPermission
permission to use methods provided by the OFM Audit Framework. In this example, the grant allows the MyApp
application to call the auditService.getAuditor
method in an 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>comp1</name> <actions>action1,action2,action3</actions> </permission> </permissions> </grant>
where the <actions> is the comma-separated list of actions that the application can carry out. The following table lists the available actions:
Action | Authorizes client to |
---|---|
create | Call AuditService.register to register a new audit component. |
upgrade | Call AuditService.register to upgrade a component event definition. |
delete | Call AuditService.unregister to deregister an audit component. |
read | Call AuditService.getAuditor to get an instance of component auditor. |
modify | Call AuditAdminService.setAuditPolicy to modify audit policy. |
After your application registers to audit, it can get its auditor instance programmatically:
//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); }
As the application's audit requirements evolve, you typically update audit definitions to reflect those changes. Specifically, you:
Update the audit definition file. For information about versions, see Section 13.7, "About Mapping and Version Rules."
Redeploy the application EAR file with the updated event definition file. Alternatively, notify audit registration about the newer version.
Verify your changes.
Note:
When you create or extend a WebLogic Server domain, you can specify audit artifacts in the domain template to facilitate audit definition upgrades. For information about files in component templates, see Section 7.4, "Layered Component Security Artifacts."