PostLoginCanonicalizationConfiguration

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

Overview

With the release of V5.2, the Subject Canonicalization layer has been substantially enhanced both internally (for performance) and externally (the configuration). The improvements are primarily geared to the post-login use case and this material outlines a simpler means of configuring this feature in complex scenarios in which multiple login methods are in use with potentially non-overlapping or conflicting c14n needs.

The c14n “flows” (which are not usually actual web flows now) can now be defined as free-standing Spring beans that will automatically be registered and available to use without having to define them (or control the order of use) using the legacy list bean. Which c14n approaches are used and in what order is now easily configurable by each login flow using a property specific to each flow.

Internally, a new interface was introduced to allow c14n to be implemented procedurally in Java rather than using Spring Web Flow definitiions. This is simpler and faster, while support for using web flows is retained for very advanced use cases in the future, but isn’t expected to be common.

The enhancements also allow for a given c14n method to be configured more than once with different settings and assigned a custom “name” for reference by specific login flows.

Configuration

By default, the system operates essentially as before by attempting each method defined in the legacy list (shibboleth.PostLoginSubjectCanonicalizationFlows) in conf/c14n/subject-c14n.xml. For existing deployments, this is assumed to be “working already” and so is backward-compatible through any upgrades to this or later versions.

However, it is not recommended in most cases to continue to leverage this list bean to reference or define c14n methods (with the exception of the need to support older/existing plugins, discussed later).

Instead, to use one or more of these c14n methods with a particular login flow, you define a property specific to that login flow in conf/authn/authn.properties (they are present but commented in the latest “shipping” default version of that file). These properties contain a comma-delimited list of c14n bean IDs to attempt for each login flow.

For example, to configure the Password login flow to attempt c14n via the “function” and “simple” methods defined above, one would use the following property:

In this manner, each login method can be explicitly configured to run the c14n logic required without any concern about overlap.

Internally, the following beans are defined with default configurations of the supported c14n methods:

• c14n/simple

• c14n/x500

• c14n/attribute-sourced

• c14n/SAML2ProxyTransform

• c14n/function ^5.2

Most of these methods are predominantly expected to be configured by means of method-specific properties in conf/c14n/subject-c14n.properties, as discussed on those pages. In a few cases, there are still additional Spring beans used, as noted on each of their documentation pages.

Older Plugins

With IdP plugins targeted at V5.0 and V5.1, the property based approach described above is not supported yet, and so you will need to refer to the older documentation and leverage the legacy list bean to configure c14n. When in doubt, refer to the plugin’s documentation on that.