Page Comparison

...

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

...