Page Comparison

Overview

Various profiles and subsystems within the IdP, especially including the authentication process, need to be able to turn a potentially complex representation of a subject into a canonical "string" form that represents the principal internally and consistently. In particular, it is a property of this canonical form that two non-equal forms MUST refer to a different subject.

...

There are at present two uses for this subsystem:

1. Normalizing the authenticated Subject into a simple username (referred to as "post-login" canonicalization, see also AuthenticationConfiguration)

2. Mapping a SAML 1 <NameIdentifier> or SAML 2 <NameID> element into a simple username (referred to as NameID consumption, see also NameIDConsumptionConfiguration)

Even though these are wildly different use cases, the same basic process is used to orchestrate the work. The difference arises from the specific subflows used by the master c14n subflow to do the actual work. The design will accomodate any future use cases in which something that's not necessarily a (single) string has to be turned into a username that is a string to match against the internal representation of users in an organization's systems.

...

The master c14n subflow is modeled after the master Authentication subflow in that there can be a number of different subflows described by a  SubjectCanonicalizationFlowDescriptor. The only real information of interest there is a predicate that can control the conditions under which the flow will execute, usually by examining the Subject at hand to see if there is compatible work for the flow to do.

...

The layout of the contexts used during c14n follows:. If you see an error, your browser settings are blocking the macro render. Note that the links no longer work properly on Cloud Confluence, but if you right-click the boxes, you can open the javadoc link in a new tab.

node [shape=record]

Profile [label="ProfileRequestContext", URL="http://shibboleth.net/cgi-bin/java-opensaml.cgi/org/opensaml/profile/context/ProfileRequestContext"]

C14N [label="SubjectCanonicalizationContext", URL="http://shibboleth.net/cgi-bin/java-identity-provider.cgi/net/shibboleth/idp/authn/context/SubjectCanonicalizationContext"]

Profile -> C14N

Obviously, this is very simple. The input and output of the c14n flow are both carried within a single child context. There certainly are additional contexts present in the tree depending on which c14n use case is involved. For example, during authentication the tree will look as the Authentication page describes, but most of the time the extra information isn't relevant. 

Programming Guide to Extending Canonicalization

...

A c14n flow is a subflow that is assigned a flow ID that starts with "c14n/" and is further defined to the system with a bean of type net.shibboleth.idp.authn.SubjectCanonicalizationFlowDescriptor in a list in conf/c14n/subject-c14n.xml.

...

The input contract is as follows:

1. An SubjectCanonicalizationContextwill exist and be populated with an input Subject to operate on.

2. A called c14n flow will be present in the collection of available c14n flows (that is, if a flow is run, it can assume it was supposed to run).

3. A called c14n flow can assume that its ActivationCondition was successfully evaluated.

4. There may intermediate state present in the tree, but flows should generally assume that they are free to act as if no such state exists unless their logic is dependent on recognizing and acting on that state. In other words, if you don't care about intermediate results, you don't have to care about intermediate results.

The output contract is as follows:

1. If a c14n flow completes with a "proceed" event, then it MUST satisfy the following requirements:

   1. The SubjectCanonicalizationContext's principalName property MUST be set.

2. If a c14n flow completes with any other event, it should assume that its outcome will be treated as unsuccessful. Flows may signal specific behavior back to the c14n master flow:

   1. ReselectFlow – tells the master c14n flow to choose another eligible flow to run (i.e., fall through)

   2. InvalidSubject – tells the master c14n flow that the input Subject was not appropriate for the flow to act on, and to choose another eligible flow to run (i.e., fall through)

   3. Anything Else – c14n will fail and the event will be reflected back as the result of the c14n master flow, to be interpreted by the calling parent flow (signaling a custom event requires that conf/c14n/subject-c14n-events-flow.xml be modified)

Programming Guide to Using Canonicalization

...

If you're creating a custom profile/protocol feature that needs c14n, a web flow that wishes to invoke the c14n subsystem must do the following:

1. Create a SubjectCanonicalizationContext and populate (at least) the subject and potentialFlows properties, along with any other inputs available.

2. Attach the SubjectCanonicalizationContext as a child of the ProfileRequestContext.

3. Transfer control to the "c14n" subflow and transition on the possible results back to your own flow.

The following events worthy of special note may occur as a result of invoking the subsystem:

Various other events signifying more low-level error conditions may also occur.

...

In the case of "proceed", SubjectCanonicalizationContext's principalName property MUST be set.

...