This material is for deployers running any version of the IdP before V5.2, but it is compatible with V5.2 and will remain compatible for the foreseeable future unless noted otherwise in the software’s Release Notes.

It is also applicable/necessary for those using plugins that are compatible with older IdP versions, until those plugins are updated to support the new APIs in V5.2. For example, the TOTP, WebAuthn, and OpenID authentication plugins are still dependent on this approach.

File(s): conf/c14n/*
Format: Native Spring, Properties

Overview

For versions of the IdP prior to V5.2, including V5.0 and V5.1, the system operates using a “chain” (that is, a list) of globally defined c14n flows that are enumerated via the beans defined or referenced in conf/subject-c14n.xml in the bean named shibboleth.PostLoginSubjectCanonicalizationFlows. That list gets injected into the low-level system files that define the various authentication flows and it instructs them to attempt run each c14n subflow in order until one succeeds and returns an appropriate result to use.

There are some deficiences and inflexibility with this model that are addressed in V5.2+, which is why the documentation is forked for now, as these improvements have been introduced in the middle of the V5 development cycle. This material is still usable with V5.2+ for the time being, it’s just not as flexible or easy to configure.

Because this list is global, and because it specifically ties the beans in the list to particular named webflows, the same list of flows is attempted for every login method you deploy with the IdP, and it is largely impossible in a supported way to configure the same c14n method twice with different settings. While not impossible, it is not particularly elegant or simple to control which c14n flows get used by specific login methods using this approach.

Configuration

With a legacy configuration, defining a c14n method involves either defining or referencing a bean keyed by the name of the method to use, and placing that definition inside the shibboleth.PostLoginSubjectCanonicalizationFlows mentioned above.

The default in older releases looks essentially like this (with the comments removed):

    <util:list id="shibboleth.PostLoginSubjectCanonicalizationFlows">
        <!-- <bean id="c14n/attribute" parent="shibboleth.PostLoginSubjectCanonicalizationFlow" /> -->

        <!-- <ref bean="c14n/SAML2ProxyTransform" /> -->

        <ref bean="c14n/x500" />

        <ref bean="c14n/simple" />
    </util:list>

In English, that says “Use the pre-defined x500 and simple flows in that order, using the built-in definitions for these flows, which depend on properties that are defined in conf/subject-c14n.properties”.

The other two beans are commented out. The first one is an actual bean defintion that activates the attribute-sourced flow (again using properties to control most of it) and the other one is a commented reference to the SAML2ProxyTransform flow’s definition.

Because the configuration was relatively inflexible, there’s not usually that much more to do other than to adjust which of these beans are references/defined and which are left commented so as to turn them off. The rest of the options are generally set via properties, discussed on the pages that define each of these particular features.