Auditing

1 Formatting Rules
2 Isolating Hub Auditing
3 Hub-Specific Fields
4 Field Extraction Points
5 Reference

The Hub supports audit logging much like the IdP does, but somewhat more directly oriented around auditing the requests into the Hub together with logging protocol message information consumed or generated.

To avoid contaminating things, the set of log formatting rules (i.e., which fields to log and how) is separate from the IdP’s AuditLoggingConfiguration, while reusing many of the existing fields defined there in obvious ways (though usually inverted due to the reversal of roles). A few new fields specific to the Hub are also of course defined and supported. As in the IdP, it is possible, though unusual, to define multiple auditing record formats that will be created at the same time, optionally via different categories.

The following summary assumes some familiarity with the original AuditLoggingConfiguration material, so refer to that for some of the core concepts.

Formatting Rules

The rules for logging to specific categories with specific formats are essentially a copy of the IdP machinery, just with internal defaults and separate bean names used to override them.

A bean named shibboleth.sp.AuditFormattingMap (e.g., added to audit.xml) will override the internal default, which looks like this:

    <util:map id="shibboleth.sp.DefaultAuditFormattingMap">
        <entry key="Shibboleth-Audit.SP" value="TBD" />
    </util:map>

Isolating Hub Auditing

Out of the box, because the IdP’s logback configuration does not have a specific set of rules defined for logging the Hub-generated events, they will appear in the same audit logging stream as the IdP. This is perhaps fine in most cases (i.e., when not operating as an IdP), but is easily changed by adding dedicated logging configuration for the “Shibboleth-Audit.SP” subcategory and turning off the additivity rule:

    <!-- Example routing SP Hub flow auditing to separate location. -->
    
    <appender name="SP_HUB_AUDIT" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <File>${idp.logfiles}/sp-audit.log</File>

        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${idp.logfiles}/sp-audit-%d{yyyy-MM-dd}.log.gz</fileNamePattern>
            <maxHistory>${idp.loghistory}</maxHistory>
        </rollingPolicy>

        <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <charset>UTF-8</charset>
            <Pattern>%msg%n</Pattern>
        </encoder>
    </appender>
    
    <logger name="Shibboleth-Audit.SP" level="ALL" additivity="false">
        <appender-ref ref="SP_HUB_AUDIT"/>
    </logger>

You will also see the audit records by default in the process log, and you will also see the various “suffixes” added to the parent logging category for specific types of events, which allows even further discrimination of logging destinations if desired. (For example, you could log events related to logout to their own appender.)

Hub-Specific Fields

Only a handful of “new” fields currently exist, mostly do with the Agent identity, as well as the new transaction ID field sent by the Agent, which you can also insert as an MDC field into other logs.

Field	Description

Field	Description
AGENT	Agent ID
APP	Application ID (usually just “default” unless overrides are defined)
TX	Transaction ID attached to request by Agent to facilitate correlation of log events

Field Extraction Points

As with the IdP, there are a number of wired in points during processing where fields get extracted, since some information is only populated after specific points in flows that could fail in the middle of doing work. The process of adding to or changing the fields these extraction steps will populate is identical to the IdP, per AuditLoggingConfiguration.

The built-in extraction points and beans used generally are as follows:

shibboleth.sp.FlowStartAuditExtractors
- Extractors that run immediately after the flow starts operating and the ability to add fields is possible
shibboleth.sp.PostAgentDecodeAuditExtractors
- Extractors focused on the input message from the Agent, runs after decoding the input message so that basic Agent and request information is known (assuming decoding succeeds)
shibboleth.sp.PostLookupAuditExtractors
- Runs after establishing a message sender's identity, supplements the input side with information about the relying party (the IdP/OP.etc. in this case)

The extraction points/beans used by the SAML plugin are:

shibboleth.sp.saml.InboundRequestAuditExtractors
- Extractors focused on a SAML request message being consumed, currently limited to <LogoutRequest> messages as the Hub consumes no other SAML requests
shibboleth.sp.saml.InboundResponseAuditExtractors
- Extractors focused on a SAML response message being consumed, i.e., <Response> and <LogoutResponse> messages
shibboleth.sp.saml.AssertionAuditExtractors
- Extractors focused on SAML assertions
shibboleth.sp.saml.OutboundRequestAuditExtractors
1. Extractors focused on a SAML request message being produced, i.e., <AuthnRequest> and <LogoutRequest> messages
shibboleth.sp.saml.OutboundResponseAuditExtractors
1. Extractors focused on a SAML response message being produced, currently limited to <LogoutResponse> messages as the Hub produces no other SAML responses

There are a couple of other extraction points used internally to pull out SAML <NameID> details at the appropriate points before/after encryption/decryption may take place to ensure the plaintext data is logged, but they generally do not need customization.

As in the IdP, each entry in these maps is a key containing the string label to associate (the name of the field), and a value containing a Function<ProfileRequestContext,Object> instance. Functions can return either single objects that get converted to a string for logging, or a Collection of objects that are converted to strings and separated by commas within the logged field.

Reference

General beans definable in audit.xml:

Bean ID	Type	Function

Bean ID	Type	Function
shibboleth.sp.AuditFormattingMap	Map<String,String>	Map of logging categories to audit formatting strings for SP audit logging

In addition, there are a set of standard beans containing the map of field extractors for all of the various "interception points" of the processing of the Hub. A pair of beans are reserved for each point, a default set that comes out of the box, and a defined bean ID to override or add to those defaults. Each of these beans is of type Map<String,Function<ProfileRequestContext,Object>>

shibboleth.sp.FlowStartAuditExtractors / shibboleth.sp.DefaultFlowStartAuditExtractors
shibboleth.sp.PostAgentDecodeAuditExtractors / shibboleth.sp.DefaultPostAgentDecodeAuditExtractors
shibboleth.sp.PostLookupAuditExtractors / shibboleth.sp.DefaultPostLookupAuditExtractors
shibboleth.sp.saml.InboundRequestAuditExtractors / shibboleth.sp.saml.DefaultInboundRequestAuditExtractors
shibboleth.sp.saml.InboundResponseAuditExtractors / shibboleth.sp.saml.DefaultInboundResponseAuditExtractors
shibboleth.sp.saml.AssertionAuditExtractors / shibboleth.sp.saml.DefaultAssertionAuditExtractors
shibboleth.sp.saml.OutboundRequestAuditExtractors / shibboleth.sp.saml.DefaultOutboundRequestAuditExtractors
shibboleth.sp.saml.OutboundResponseAuditExtractors / shibboleth.sp.saml.DefaultOutboundResponseAuditExtractors