PicketBox Audit

<< Go Back to PicketBox Overview


PicketBox (Formerly JBoss Security) provides audit capabilities for Java Applications.

Audit Providers


The Audit Providers form the cornerstone of the PicketBox audit framework. By default, a LogAuditProvider is provided as part of the framework.

Audit Event


The AuditEvent is an object that is the carrier of the audit information. An AuditEvent gets logged by the Audit Provider.


Audit Manager


AuditManager is the entry into the auditing framework that is available as part of the security domain under which the authentication/authorization features were utilized.


Class Diagram




Sample Code


In this example, we are going to use PicketBox for authentication. After that, we use the auditing feature to audit the authentication event.



import java.security.Principal;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import javax.security.auth.Subject;

import org.jboss.security.AuthenticationManager;
import org.jboss.security.audit.AuditEvent;
import org.jboss.security.audit.AuditLevel;
import org.jboss.security.audit.AuditManager; 
import org.jboss.security.audit.AuditProvider;
import org.picketbox.config.PicketBoxConfiguration;
import org.picketbox.factories.SecurityFactory; 

//A private variable
 private final String securityDomainName = "test";

//Test method to test authentication and then audit
   public void testValidAuthentication() throws Exception
         String configFile = "config/audit.conf";
         PicketBoxConfiguration idtrustConfig = new PicketBoxConfiguration();
         AuthenticationManager am = SecurityFactory.getAuthenticationManager(securityDomainName);
         Subject subject = new Subject();
         Principal principal = getPrincipal("anil");
         Object credential = new String("pass");
         boolean result = am.isValid(principal, credential, subject);
         assertTrue("Valid Auth", result);
         assertTrue("Subject has principals", subject.getPrincipals().size() > 0);
         Map<String,Object> contextMap = new HashMap<String,Object>();
         AuditEvent auditEvent = new AuditEvent(AuditLevel.SUCCESS,contextMap);
         AuditManager auditManager = SecurityFactory.getAuditManager(securityDomainName);
         assertTrue("Audit Event is contained in the static map of Audit Provider",

   private Principal getPrincipal(final String name)
      return new Principal()
         public String getName()
            return name;
   public static class TestAuditProvider implements AuditProvider
      public static List<AuditEvent> eventList = new ArrayList<AuditEvent>();

      public void audit(AuditEvent auditEvent)


The configuration file "audit.conf" looks as follows:

<?xml version='1.0'?> 
<policy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   <application-policy name = "test"> 
          <login-module code = "org.jboss.security.auth.spi.UsersRolesLoginModule"
             flag = "required">  
          <provider-module code="org.picketbox.test.api.AuditUnitTestCase$TestAuditProvider"/>


In this example, we used a TestAuditProvider that has a list to store the audit events. In your applications, you should either write your own AuditProvider or reuse the LogAuditProvider.




Note: The LogAuditProvider utilizes the JBoss Logging SPI. Because of this, it is possible to log the audit events either in log4j or JDK logs.

PicketBox Audit using Java Annotation

You can use the @Audit annotation on Java classes. Please refer to PicketBox Authorization article. The annotation is described in PicketBoxSecurityAnnotations.



  1. Security Auditing in JBoss Application Server v5.x



<< Go Back to PicketBox Overview