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 like 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).

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

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.

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:

idp.authn.Password.c14n.flows = c14n/function, c14n/simple

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

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.

Advanced Topics

Multiple Instances of a Method

It is now possible to configure multiple copies of a particular c14n method with different settings. This requires additional Spring XML configuration since the default instances get most of their behavior from a single set of properties. The attribute-sourced method is the most common use case for this, since its configuration includes the specification of which attribute(s) to resolve and source from, and that method also doubles as a means of extracting a username from incoming data when proxying to another IdP.

For example, consider the use case of the Password login flow relying on a local directory to remap the username via the Attribute Resolver, while simultaneously using the SAML proxy login flow to extract an Attribute decoded from the incoming assertion. While it is possible to do this (at times) with a single instance of the attribute-sourced c14n method, a more reliable way to prevent accidental overlap is to define a second instance of the method.

Assuming the properties used to configure this method are set up to support the Password/Attribute Resolver use case, a second instance can be added with a bean such as the following added to conf/c14n/subject-c14n.xml:

<bean id="c14n/proxy-sourced" parent="c14n/attribute-sourced">
  <property name="implementation">
    <bean id="ProxySourcedC14N" parent="shibboleth.AttributeSourcedC14N"
        p:attributesToResolve="proxyUsername"
        p:attributeSourceIds="proxyUsername"
        p:resolveFromSubject="true"
        p:resolutionCondition="false" />
  </property>
</bean>

There are a couple of parent beans in this example. The outer bean defines a named c14n method to the system, while the inner bean in the “implementation” property is the Java implementation of this method to use, with various settings overridden to differentiate them from the parent bean’s settings defaulted by the properties in subject-c14n.properties.

While the beans noted above and shown in this example are named with the “c14n/” prefix for both compatibility and clarity, that isn’t a requirement, so deployers are free to define new instances of these methods using whatever naming they prefer.