File(s): conf/c14n/subject-c14n.xml, conf/c14n/subject-c14n.properties
Format: Native Spring, Properties
The “SAML2ProxyTransform“ subject c14n method does an extraction of a NameIDPrincipal from the Java Subject and returns the value as the canonical principal name for the subject. It also supports a small set of optional transforms and case-folding to apply to the name.
The primary use case for this feature is the SAML login flow, i.e., SAML proxying. It supports the import of the asserted <NameID> element value from the proxied IdP as the normalized subject name. This is essentially the same functionality as the non-proxy variant of this feature described under the NameIDConsumptionConfiguration topic, but is separate so that the control beans of the two features (the ones discussed below) don't need to overlap.
This flow will succeed if and only if the input Java Subject contains exactly one NameIDPrincipal in its Principal collection.
Use conf/c14n/subject-c14n.xml and conf/c14n/subject.properties to configure this flow.
The most important bean is shibboleth.ProxyNameTransformPredicate, which controls the circumstances under which the importing flow will be allowed to run. The bean itself must be a Predicate object. The example configuration demonstrates how to create a condition that requires the issuer be one of a listed set of named entities. But any Predicate can be used, such as a script. With some proxies, it's assumed that control over the metadata and allowable authenticating IdPs is sufficient to allow broad acceptance of whatever NameID value they happen to supply.
The shibboleth.ProxyNameTransformFormats bean is a list of the <NameID> Format(s) that you want to allow for import. The pre-existing list contains a number of Formats defined by SAML. You may need to add to it if you or some other party needs to exchange a custom Format, or you may want to prune out many of them for safety/assurance that only what you expect will be accepted.
The method supports some simple transform capability. The shibboleth.ProxyNameTransforms bean is a list of regular expression and replacement string pairs that can transform the input value into a different username value rather than importing it directly. It also allows for case folding via a couple of properties.
In the most unusual cases, there is support for injecting a custom object of your own creation that implements the NameIDDecoder interface to fully customize the decoding process. The bean name shibboleth.SAML2ProxyTransform.NameIDDecoder is reserved for this purpose. Normally the existing implementation will be adequate.
In V5.2+, this method is enabled by setting a per-login-flow property in conf/authn/authn.properties that references it. The default bean ID of this method is “c14n/SAML2ProxyTransform”, so enabling it for a login flow looks like:
It would be unlikely to ever need to configure multiple instances of this method, though it’s possible to do so. Since the SAML login flow is largely the only one that would ever need this method and you can only configure that flow once, it’s generally assumed the configuration of this method is also going to be singular. |
In older versions, this method is generally commented out by default inside the shibboleth.PostLoginSubjectCanonicalizationFlows list bean in conf/c14n/subject-c14n.xml:
Enabling it thus requires uncommenting it, and then adjusting the various beans and properties noted above and in the Reference section. It will generally not interfere with any other login flows due to their inability to populate the necessary Principal into the Subject. |
The beans related to this feature in conf/c14n/subject-c14n.xml follow:
|
Properties related to this feature in conf/c14n/subject-c14n.properties follow:
|