1. Introduction... 1 2. Auditing Handlers and Audit Trails... 2 3. Configure the Built-In Handler... 3 4. Create a Custom Audit Handler... 5 iii
Auditing is a key security aspect of identity solutions. The JOSSO s auditing module provides a systematic way of collecting information related to events and activities that can be used to ensure conformance with internal and external policies. In JOSSO we cal this information audit trails. Audit trails are generated all across the platform, and captured by the auditing service. The following is a high level list of available trails: Sign-on Sign-off Session Timeout Authentication User handling (create, remove, update, delete) Role management (create, remove, update, delete) In this tutorial we ll take a look at the built-in auditing loging configuration, and we ll mention at the end the steps required to implement your own module, including an example. 1
The Auditing Module follows the flexibility principle that shapes the entire platform, allowing users to create and provide their own extensions into the system. For the Auditing Module, you can create your own AuditHandler implementation to receive and process AuditTrails. As mentioned before, audit trails represent security events and activities where each trail instance contains the following information: Category: identity appliance/provider that generated the trail, it includes the appliance realm (i.e. com.mycompany.sso.ida-1.audit.idp-1) Severity: refers to the severity of the action (CRITICAL, WARNING, INFO, LOW). Action: event or action recorded. (i.e. SSO, SLO, SLO_TOUT) Outcome: action s result (SUCCESS, FAILURE) Time: action timestamp Principal: Optional, the authenticated remote user associated to the action Error: Optional, represents an error associated to the action. Properties: Additional set of action specific properties (i.e remote address) 2
The default auditing handler can record audit trails to a log or logs. You can configure different output logs for different Identity Appliances or even for one for each provider. The logging handler takes full advantage of the logging system, allowing configuration for filesystem based logs, database persisted logs, or even network service logs. The built-in handler will use the audit trail category property to log the event, this can be used to configure the logging system. In this example we assume that the Identity Appliance realm is com.mycompany.sso.ida-1. JOSSO provides a pre-configured audit.log appender named audit that can be used when configuring auditing for your deployment. To enable auditing to the default appender, just edit the file $JOSSO2_HOME/etc/org.ops4j.pax.logging.cfg.prod and add a new entry for you appliance like this (look for this section at the end of the file). If you require different log files for different appliances/providers, just define a new appender and refer to it when enabling the corresponding category. Once you re done copy the modified file over $JOSSO2_HOME/etc/ org.ops4j.pax.logging.cfg Enable auditing for an appliance to the default audit.log # Add appliances that should output audit information # to audit log log4j.category.com.mycompany.sso.ida-1.audit=trace, audit idp-1.log # File appender for audit-ida-1-idp-1 log4j.appender.audit-ida-1-idp-1=org.apache.log4j.rollingfileappender log4j.appender.audit-ida-1-idp-1.layout=org.apache.log4j.patternlayout log4j.appender.audit-ida-1-idp-1.layout.conversionpattern=%d{iso8601} %-5.5p %m%n Enable auditing for identity provider idp-1 of identity applinace ida-1 to the the file audit-ida-1- log4j.appender.audit-ida-1-idp-1.file=${karaf.base}/data/log/audit-ida-1- idp-1.log log4j.appender.audit-ida-1-idp-1.append=true log4j.appender.audit-ida-1-idp-1.maxfilesize=10mb log4j.appender.audit-ida-1-idp-1.maxbackupindex=99 # Add appliances that should output audit information # to audit log log4j.category.com.mycompany.sso.ida-1.audit.idp-1=trace, audit 3
Configure the Built-In Handler Log Details Options JOSSO supports multiple logging detail options: Production, Detailed, Development. You may want to update the proper files with the auditing options if auditing is required in those modes. $JOSSO2_HOME/etc/org.ops4j.pax.logging.cfg.debug, $JOSSO2_HOME/ etc/org.ops4j.pax.logging.dev 4
The easiest way to show-case how to create a custom Audit Handler is by providing an example. Once implemented, the handler must compiled and packaged as an OSGi bundle to be deployinstalled as a custom feature. You can download an example from github [https:// github.com/atricore/atricore-idbus/tree/1.4.1/examples/custom-audit-handler] Once built, the bundle can be added as a custom feature to JOSSO, simply edit the file, and add the new bundle: $JOSSO2_HOME/features/com/atricore/josso/josso-ee-custom/2.4.1/josso-eecustom-2.4.1-features.xml <?xml version="1.0" encoding="utf-8"?> <features name="atricore-josso-ee-custom-2.4.2-snapshot"> <!-- Add custom extensions here --> <feature name="custom" version="2.4.2-snapshot"> <bundle >mvn:org.atricore.idbus.examples/ org.atricore.idbus.examples.custom-audit-handler/2.4.1</bundle> </feature> </features> Features File Keep in mind that the product version 2.4.1 used in the example may need to be replaced with the corresponding product version (i.e. 2.4.2-SNAPSHOT) when looking for the custom features file. 5