File(s): conf/audit.xml, conf/errors.xml, conf/logback.xml
Format: Native Spring, Logback
Overview
The audit logging feature provides a detailed record of every transaction handled by the IdP to allow tracing of user activity, statistical analysis of usage, legal record keeping, etc. It is highly extensible, allowing the format to be customized, selection of fields to log on a per-profile basis, and the addition of custom audit fields using additional Java code or scriptlets without modifying core code in most cases. Unlike the diagnostic logs, the audit log is meant to be machine-readable.
There are initially two such logs provided, and there might be more added later if other use cases emerge. The core audit log is used for general request/response auditing, and is routed by default through a logger named "Shibboleth-Audit" to a file called idp-audit.log. A second log is used for logging decisions made by users regarding attribute release and terms of use acceptance, and is routed by default through a logger named "Shibboleth-Consent-Audit" to a file called idp-consent-audit.log.
It's possible through additional configuration to send audit records configured in multiple formats to different logging categories; for example you might have custom tools that want particular formats and the IdP can produce those formats for you in real time while still generating other formats at the same time.
General Configuration
As with the diagnostic logs, the actual logging is handled by the Logback implementation and so the portion of configuration that deals with how the logs are written and managed is in the conf/logback.xml file through the manipulation of the two <logger> elements and related content for the "Shibboleth-Audit" and "Shibboleth-Consent-Audit" categories.
However, there is minimal formatting applied there, just direct output of the audit message. The configuration of the audit format(s) to use for particular transactions is handled separately, in conf/audit.xml, to allow customizing of the audit fields themselves, using formatting tokens that are themselves configured within the IdP and are extensible. You can think of it like a second logging abstraction on top of the underlying one to avoid reliance on Logback-specific extensions.
There are really two halves to the auditing system: field extraction and log output. While suitable defaults are provided, both halves can be changed using conf/audit.xml (or conf/intercept/consent-intercept-config.xml for the Shibboleth-Consent-Audit category). Extending field extraction typically requires additional Java code or scripts to pull new data out of the request state and make it available to the log output stage, but there are a lot of built-in fields.