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.
In many cases, this will be a very simple, or at least self-contained, process. But for generality, and in particular to support the ability to leverage the flexibility of the Attribute Resolver components, the Subject Canonicalization process is implemented as a subsystem implemented using a Spring Web Flow excuted against a context tree.
The web flow operates on the SubjectCanonicalizationContext class, which has a Java Subject property to operate on. The Subject will contain one or more Java Principal subtypes that particular web flow actions must be coded to look for and operate on to produce a result.
Upon completion, the web flow populates the context with either a resulting principal name or produces an error state.
The SubjectCanonicalication subflow is modeled after the 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 be injected to control the conditions under which a flow will execute.
Much like the authentication flow, a set of potential canonicalization subflows is populated by an action into the SubjectCanonicalizationContext, and then a selection action iterates over them looking for a candidate subflow to run. Specific events can result in a retry of alternative subflows until success or a fatal error occurs, or no more subflows can be attempted.