28 Developing with the Audit Service

28.4.1 Default Application 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 metadata store if the application is not yet registered.

• Redeployment - Upgrades the component audit event definition if the component is already registered. See Section 12.5.3.1 for details.

• Undeployment - Removes the application's audit event definition from the audit metadata store.

28.4.2 Custom Application Audit Registration

Custom audit registration parameters are set in the WebLogic deployment descriptor weblogic-application.xml, which is also packaged in the META-INF folder of the application EAR files.

Table 28-1 shows the parameters with their options:

Examples of weblogic-application.xml

The following sample from a weblogic-application.xml file demonstrates the use of registration and de-registration 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>

28.4.3 Programmatic Registration

You can register your application to audit service by invoking audit registration service programmatically. The registration logic is as follows:

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;
            }
        });

Invoking auditService.register requires that clients be granted AuditStoreAccessPermission with create, upgrade actions. For details about setting grants, see Section 28.6.2.

Here is an example of registering the audit service programmatically:

//
        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 audit service API to register audit event definition
        AccessController.doPrivileged(new PrivilegedExceptionAction<Object>() {
            public Object run() throws AuditException, IOException {
                auditService.register(auditReg);
                return null;
            }
        });

28.5.1 Query Audit Metadata

The APIs to query audit metadata are as follows:

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 use the APIs to query audit metadata:

 //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();
 
            }
        }
    }

28.5.2 View and Set Audit Run-time Policy

The APIs to retrieve and set audit runtime policy are as follows:

AuditPolicy getAuditPolicy(String componentType) throws AuditException;
   
    void setAuditPolicy(String componentType, AuditPolicy auditPolicy) throws AuditException;

The following example shows how to use the APIs to first obtain and then 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("All", null, null);
    //setAuditPolicy() requires AuditStoreAccessPermission(<componentType>, "modify");
    AccessController.doPrivileged(new PrivilegedExceptionAction<Object>(){
        public Object run() throws AuditException {
            auditAdminService.setAuditPolicy(componentType, newPolicy);
            return null;
        }
    });

28.6.1 Audit 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();

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)
}

Subsequent sections explain how to obtain permissions and a run-time auditor instance.

28.6.2 Set System Grants

Audit clients must have AuditStoreAccessPermission to invoke the Audit API. 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>comp1</name>
    <actions>action1,action2,….</actions>
  </permission>
 </permissions>
</grant>

where the <actions> are a comma-separated list of authorized actions relating to the audit API that the audit client needs to invoke. The possible actions are as follows:

28.6.3 Obtain Auditor Instance

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);
}