Introduction

This sections gives you an overview about the Auditing Infrastructure and how you can use it to audit your application.

The auditing capabilities are strongly related with the security events fired by your application. When an user is authenticated, for example, a specific event is handled to produce some audit information using a specific provider. Audit providers can produce and store audit records in several ways, choosing among other things where the information should be persisted (eg.: databases, text files, etc).

Auditing is performed in the following manner:

1. Some specific security event is fired (see Event Handling for more information)

2. The AuditEventHandler receives the notification and delegates the original event to the AuditProvider

3. The AuditProvider creates a AuditEvent instance and populates it with some information. Most of the information is obtained from the original event.

4. Depending on the AuditProvider implementation, the audit record is stored somewhere.

By default, only one AuditProvider implementation is provided: org.picketbox.core.audit.providers.LogAuditProvider. But you can always provide your own implementation.

Enable Auditing

To enable auditing you need to build the PicketBox configuration telling which provider you want to use.

As said before, the LogAuditProvider is provided by default. This implementations uses your logging configuration to persist the audit records.

ConfigurationBuilder builder = new ConfigurationBuilder();


// enable auditing using the default audit provider
builder
    .audit()
        .logProvider();

PicketBoxManager picketBoxManager = // create and start the manager

if you want to use your own AuditProvider implementation you can configure it in the following manner.

ConfigurationBuilder builder = new ConfigurationBuilder();


// instantiates the custom audit provider
CustomAuditProvider customAuditProvider = new CustomAuditProvider();
        
// configures the custom audit provider
builder
    .audit()
        .provider(customAuditProvider);

PicketBoxManager picketBoxManager = // create and start the manager

Decorating Audit Events

Sometimes you may need to perform some additional validation or decorate the audit records with more information. This can be very useful if you want to handle the audit events records before or after they are processed by the audit provider. Let's say you want to:

• Decorate audit records with some application's specific information

• Highlight audit records to make them more suitable for your needs, making easier the analysis around the audit information

• Enable notifications and send e-mails or invoking some specific application logic or business process

• Decide whether a specific audit record whould be processed or not

As said before, the audit infrastructure is strongly based on the PicketBox's event system. Audit events are just events that can also be handled as any other security related event. What you need to do is just write a class that observes audit events types, like showed in the code bellow.

public class ApplicationAuditEventHandler {


    @EventObserver
    public void onPreAudit(PreAuditEvent event) {
        // put here your custom audit logic. Like decorate the audit event BEFORE its processing by the audit provider
    }

    @EventObserver
    public void onPostAudit(PostAuditEvent event) {
        // put here your custom audit logic to process the audit event AFTER the processing by the audit provider
    }

}

Built-In Audit Providers

##AUDIT_TYPE: Authentication## 
##CREATION_DATE: Tue Nov 20 20:51:48 BRST 2012## 
##DESCRIPTION: User was authenticated## 
##USER_CONTEXT:  Username: admin/ IsAuthenticated: true / Credential: [null] / Authentication Result: [Principal: org.picketbox.core.PicketBoxPrincipal@48cbdb20 / Status: SUCCESS / Messages: []] / Session: [null]## 
##AUDIT_CONTEXT: customAuditInfo=Some custom audit info;##