Page Comparison

File(s): conf/audit.xml, conf/errors.xml, conf/logback.xml, conf/authn/authn.properties (V4.3+)
Format: Native Spring, Logback

...

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.

Note that the audit log does not log individual authentication success/failure information because that can happen repeatedly in the course of a single “transaction” from the IdP’s perspective. There are diagnostic log messages produced for those events, but not audit events. It is presumed that the true “audit” log of an authentication service is produced by that service itself, while the IdP’s log would only be used in the rare case that something needs to be correlated to a client address or similar information.

There are initially two audit 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-The primary audit stream deals with the request/response profile handling of the IdP itself (this also includes logging the requests and responses associated with the SAML proxying support). This is routed by default through a logger named "Shibboleth-Audit" to a file called idp-audit.log.

Another audit record stream exists 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. 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.

Prior to V4.3, the audit log does not include records of individual authentication success or failure results; only the diagnostic (“process”) log includes (unstructured) records of those events. V4.3 introduces a separate stream of authentication audit events for each supported login flow. By default this feature is not enabled, but if done, these records appear in the same audit stream as the primary auditing. It is straightforward (and usually advisable) to route these records by category to a separate file or destination since the record format is not the same as the primary records.

Finally, the primary audit log supports the ability to create multiple log records in different formats or with different fields at the same time for the same events (and optionally route them to different categories for output to different destinations). The authentication auditing does not support this feature for simplicity (and because of the relative paucity of fields).

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.

...

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“Shibboleth-Consent-Audit 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.

<!-- Adds a function to extract a custom field called MYFIELD after the final response has been generated. -->
<bean id="shibboleth.PostResponseAuditExtractors" parent="shibboleth.DefaultPostResponseAuditExtractors">
	<property name="sourceMap">
		<map merge="true">
            <entry key="MYFIELD" value-ref="MyExtractionFunctionBean" /> 
		</map>
	</property>
</bean>

     <bean id="shibboleth.CASValidationAuditExtractors" parent="shibboleth.DefaultCASValidationAuditExtractors" lazy-init="true">
         <property name="sourceMap">
             <map merge="true">
                 <entry>
                     <key>
                         <util:constant static-field="net.shibboleth.idp.cas.protocol.CASAuditFields.SERVICE_URL"/>
                     </key>
                     <bean parent="shibboleth.ContextFunctions.Scripted" factory-method="inlineScript">
                         <constructor-arg>
                             <value>
                             <![CDATA[
                                 var serviceLookupFunctionClass = Java.type("net.shibboleth.idp.cas.audit.impl.ServiceLookupFunction");
                                 var serviceLookupFunction = new serviceLookupFunctionClass();
                                 var service = serviceLookupFunction.apply(input);
                                 if (service != null) {
                                     var serviceNew = service.replace(/\|/g, '%7C');
                                 }
                                 else {
                                     var serviceNew = null;
                                 }
                                 serviceNew;
                             ]]>
                             </value>
                         </constructor-arg>
                     </bean>
                 </entry>
             </map>
         </property>
     </bean>

	<bean id="AttributeValueExtraction" parent="shibboleth.ContextFunctions.Scripted" factory-method="inlineScript" abstract="true">
		<constructor-arg>
	        <value>
	        <![CDATA[ 
	        var getinfo = function() {
	        	var rpContext = input.getSubcontext("net.shibboleth.idp.profile.context.RelyingPartyContext");
		        if (null === rpContext) {
		            return null;
		        }
	        	
		        var attrContext = rpContext.getSubcontext("net.shibboleth.idp.attribute.context.AttributeContext");
		        if (null === attrContext) {
		            return null;
		        }
		        var attributes = null
		        attributes = attrContext.getUnfilteredIdPAttributes();
		        if (null === attributes) {
		            return null;
		         }
	            attribute = attributes.get(custom);
	            if (null === attribute || attribute.getValues().isEmpty()) {
	                return null;
	            }
	            var iter = attribute.getValues().iterator();
	            var result = "";
	            while (iter.hasNext()) {
	               result = result + " " + iter.next().toString();
	            }
	            return result;
		     }
		     getinfo();
	         ]]>
	        </value>
	    </constructor-arg>
	</bean>

<bean id="EmailExtraction" parent="AttributeValueExtraction" p:customObject="mail" />

...