Auditing

Auditing is a key security aspect of identity solutions. 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 call 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 logging configuration, and we’ll mention at the end the steps required to implement your own module, including an example.

Auditing Handlers and Audit Trails

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

Configure the Built-In Handler

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 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 your 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

Enable auditing for identity provider idp-1 of identity appliance ida-1 to the the file audit-ida-1-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

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

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

Create a Custom Audit Handler

The easiest way to showcase 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 installed as a custom feature. You can download an example from githubopen in new window.

Custom Extensions Descriptor

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-ee-custom-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>

Custom Extensions Deployment Location

The bundle binary distribution file must be installed in the $JOSSO2_HOME/extensions folder, following a Maven repository structure. In our case, the location is:

$JOSSO2_HOME/extensions/org/atricore/idbus/examples/org.atricore.idbus.examples.custom-audit-handler/2.4.1/org.atricore.idbus.examples.custom-audit-handler-2.4.1.jar

TIP

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.

# Auditing

# Auditing Handlers and Audit Trails

# Configure the Built-In Handler

# Create a Custom Audit Handler