Chapter 10. Auditing

Procedure 10.1. Enable the security audit feature

1. Open the log4j configuration file

   Navigate to $JBOSS_HOME/server/$PROFILE/conf/
   Open the jboss-log4j.xml file using a text editor.

2. Uncomment the security audit category

   By default, the Security Audit Provider category definition in the jboss-log4j.xml file is commented out. Uncomment the category definition shown in Example 10.1, “log4j Security Audit Provider category”.

   Example 10.1. log4j Security Audit Provider category

   <?xml version="1.0" encoding="UTF-8"?>
   
   <!-- Limit the verbose MC4J EMS (lib used by admin-console) categories -->
   <category name="org.mc4j.ems">
     <priority value="WARN"/>
   </category>
      
   <!-- Show the evolution of the DataSource pool in the logs [inUse/Available/Max]
   <category name="org.jboss.resource.connectionmanager.JBossManagedConnectionPool">
     <priority value="TRACE"/>
   </category>
      -->
   
   <!-- Category specifically for Security Audit Provider -->
   <category name="org.jboss.security.audit.providers.LogAuditProvider" additivity="false">
   <priority value="TRACE"/>
     <appender-ref ref="AUDIT"/>
   </category>
   
      
   <!-- Limit the org.jboss.serial (jboss-serialization) to INFO as its DEBUG is verbose -->
   <category name="org.jboss.serial">
     <priority value="INFO"/>
   </category>
   
   

   Copy to Clipboard Toggle word wrap

3. Uncomment the audit appender

   By default, the AUDIT appender definition in the jboss-log4j.xml file is commented out. Uncomment the appender definition shown in Example 10.1, “log4j Security Audit Provider category”.

   Example 10.2. log4j Security Audit Provider category

   ...
   <!--  Emit events as JMX notifications
   <appender name="JMX" class="org.jboss.monitor.services.JMXNotificationAppender">
     <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
     <param name="Threshold" value="WARN"/>
     <param name="ObjectName" value="jboss.system:service=Logging,type=JMXNotificationAppender"/>
     <layout class="org.apache.log4j.PatternLayout">
       <param name="ConversionPattern" value="%d %-5p [%c] %m"/>
     </layout>
   </appender>
   -->
   
   <!-- Security AUDIT Appender -->
   <appender name="AUDIT" class="org.jboss.logging.appender.DailyRollingFileAppender">
     <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
     <param name="File" value="${jboss.server.log.dir}/audit.log"/>
     <param name="Append" value="true"/>
     <param name="DatePattern" value="'.'yyyy-MM-dd"/>
     <layout class="org.apache.log4j.PatternLayout">
       <param name="ConversionPattern" value="%d %-5p [%c] (%t:%x) %m%n"/>
     </layout>
   </appender>
      
      <!-- ================ -->
      <!-- Limit categories -->
      <!-- ================ -->
   
   <!-- Limit the org.apache category to INFO as its DEBUG is verbose -->
   <category name="org.apache">
     <priority value="INFO"/>
   </category>
   ...
   

   Copy to Clipboard Toggle word wrap

4. Save, and restart server

   You have now activated the auditing service for your implementation, as configured in the jboss-log4j.xml file.
   Restart the server to ensure the new security policy takes effect.

5. Verify security auditing is functioning correctly

   Once the audit service is configured and deployed, audit log entries will verify the audit service and EJB invocation success.
   The audit.log file is located in jboss-as/server/$PROFILE/log/ directory.
   A successful EJB invocation would look similar to the following audit.log output.

   Example 10.3. Successful EJB Invocation log entry

   2008-12-05 16:08:26,719 TRACE [org.jboss.security.audit.providers.LogAuditProvider] (http-127.0.0.1-8080-2:) [Success]policyRegistration=org.jboss.security.plugins.JBossPolicyRegistration@76ed4518; Resource:=[org.jboss.security.authorization.resources.EJBResource:contextMap={policyRegistration=org.jboss.security.plugins.JBossPolicyRegistration@76ed4518}:method=public abstract org.jboss.test.security.interfaces.RunAsServiceRemote org.jboss.test.security.interfaces.RunAsServiceRemoteHome.create() throws java.rmi.RemoteException,javax.ejb.CreateException:ejbMethodInterface=Home:ejbName=RunAs:ejbPrincipal=jduke:MethodRoles=Roles(identitySubstitutionCaller,):securityRoleReferences=null:callerSubject=Subject:
           Principal: [roles=[identitySubstitutionCaller, extraRunAsRole],principal=runAsUser]
           Principal: Roles(members:extraRunAsRole,identitySubstitutionCaller)
   :callerRunAs=[roles=[identitySubstitutionCaller, extraRunAsRole],principal=runAsUser]:callerRunAs=[roles=[identitySubstitutionCaller, extraRunAsRole],principal=runAsUser]:ejbRestrictionEnforcement=false:ejbVersion=null];Source=org.jboss.security.plugins.javaee.EJBAuthorizationHelper;Exception:=;

   Copy to Clipboard Toggle word wrap
   An unsuccessful EJB invocation would look similar to the following audit.log output.

   Example 10.4. Unsuccessful EJB Invocation log entry

   [Error]policyRegistration=org.jboss.security.plugins.JBossPolicyRegistration@76ed4518;Resource:=[org.jboss.security.authorization.resources.EJBResource:contextMap={policyRegistration=org.jboss.security.plugins.JBossPolicyRegistration@76ed4518}:method=public java.security.Principal org.jboss.test.security.ejb3.SimpleStatelessSessionBean.invokeUnavailableMethod():ejbMethodInterface=Remote:ejbName=SimpleStatelessSessionBean:ejbPrincipal=UserA:MethodRoles=Roles(<NOBODY>,):securityRoleReferences=null:callerSubject=Subject:
           Principal: UserA
           Principal: Roles(members:RegularUser,Administrator)
   :callerRunAs=null:callerRunAs=null:ejbRestrictionEnforcement=false:ejbVersion=null];Source=org.jboss.security.plugins.javaee.EJBAuthorizationHelper;Exception:=Authorization Failed: ;

   Copy to Clipboard Toggle word wrap

Procedure 10.2. Enable security auditing for Web containers

1. Enable EJB security auditing

   You must enable security as described in Procedure 10.1, “Enable the security audit feature”.

2. Activate auditing in the server realm

   Web container auditing must first be activated in the server realm of the server.xml file.
   The server.xml file is located in the jboss-as/server/$PROFILE/deploy/jbossweb.sar/ directory.
   The <Realm> element must have the enableAudit="true" attribute set, as per Example 10.5, “server.xml audit activation”.

   Example 10.5. server.xml audit activation

   <Realm className="org.jboss.web.tomcat.security.JBossWebRealm" certificatePrincipal="org.jboss.security.auth.certs.SubjectDNMapping" allRolesMode="authOnly" 
   enableAudit="true"/>

   Copy to Clipboard Toggle word wrap

3. Specify auditing levels system property

   The auditing levels for Web applications must be specified using the org.jboss.security.web.audit system property in the run.conf (Linux) or run.conf.bat (Microsoft Windows) script.
   Alternatively, you can specify the system property in the jboss-as/server/$PROFILE/deploy/properties-service.xml file.

   • Linux

     Add the system property into the jboss-as/bin/run.sh file.

     ## Specify the Security Audit options
     #System Property setting to configure the web audit:
     #* off = turn it off
     #* headers = audit the headers
     #* cookies = audit the cookie
     #* parameters = audit the parameters
     #* attributes = audit the attributes
     #* headers,cookies,parameters = audit the headers,cookie and 
     #                               parameters
     #* headers,cookies = audit the headers and cookies
     JAVA_OPTS="$JAVA_OPTS -Dorg.jboss.security.web.audit=headers,cookies,parameter"

     Copy to Clipboard Toggle word wrap

   • Microsoft Windows

     Add the system property into the jboss-as/bin/run.bat file.

     rem Specify the Security Audit options
     rem System Property setting to configure the web audit
     rem * off = turn it off
     rem * headers = audit the headers
     rem * cookies = audit the cookie
     rem * parameters = audit the parameters
     rem * attributes = audit the attributes
     rem * headers,cookies,parameters = audit the headers,cookie and
     rem   parameters
     rem * headers,cookies = audit the headers and cookies
     set JAVA_OPTS=%JAVA_OPTS% " -Dorg.jboss.security.web.audit=headers,cookies,parameter"

     Copy to Clipboard Toggle word wrap

   • properties-service.xml

     Update the SystemPropertiesService class MBean in the jboss-as/server/$PROFILE/deploy/properties-service.xml file, and declare the java property as an <attribute>. You can uncomment the relevant operating system block in the code sample below.

     <mbean code="org.jboss.varia.property.SystemPropertiesService" 
     name="jboss:type=Service,name=SystemProperties">
        <attribute name="Properties">
     org.jboss.security.web.audit=headers,cookies,parameter
        </attribute>
     </mbean>
     

     Copy to Clipboard Toggle word wrap

4. Verify security auditing is functioning correctly

   Once the system property is specified in the files, audit log entries will verify Web invocation success.
   The audit.log file is located in jboss-as/server/$PROFILE/log/ directory.
   A successful Web invocation would look similar to the following audit.log output.

   Example 10.6. Successful Web Invocation log entry

   2008-12-05 16:08:38,997 TRACE [org.jboss.security.audit.providers.LogAuditProvider] (http-127.0.0.1-8080-17:) [Success]policyRegistration=org.jboss.security.plugins.JBossPolicyRegistration@76ed4518;Resource:=[org.jboss.security.authorization.resources.WebResource:contextMap={policyRegistration=org.jboss.security.plugins.JBossPolicyRegistration@76ed4518,securityConstraints=[Lorg.apache.catalina.deploy.SecurityConstraint;@6feeae6, resourcePermissionCheck=true},canonicalRequestURI=/restricted/get-only/x,request=[/web-constraints:cookies=null:headers=user-agent=Jakarta Commons-HttpClient/3.0,authorization=host=localhost:8080,][parameters=],CodeSource=null];securityConstraints=SecurityConstraint[RestrictedAccess - Get Only];Source=org.jboss.security.plugins.javaee.WebAuthorizationHelper;resourcePermissionCheck=true;Exception:=;

   Copy to Clipboard Toggle word wrap
   An unsuccessful EJB invocation would look similar to the following audit.log output.

   Example 10.7. Unsuccessful Web Invocation log entry

   2008-12-05 16:08:41,561 TRACE [org.jboss.security.audit.providers.LogAuditProvider] (http-127.0.0.1-8080-4:) [Failure]principal=anil;Source=org.jboss.web.tomcat.security.JBossWebRealm;request=[/jaspi-web-basic:cookies=null:headers=user-agent=Jakarta Commons-HttpClient/3.0,authorization=host=localhost:8080,][parameters=][attributes=];2008-12-05 16:07:30,129 TRACE [org.jboss.security.audit.providers.LogAuditProvider] (WorkerThread#1[127.0.0.1:55055]:)

   Copy to Clipboard Toggle word wrap