Versions Compared

Old Version 18

changes.mady.by.user Rod Widdowson

Saved on

compared with

New Version 19

changes.mady.by.user Scott Cantor

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Current File(s):conf/c14n/attribute-sourced-subject-c14n-config.xml (V4.0), conf/c14n/subject-c14n.properties (V4.1+)
Format: Native Spring, Properties (V4.1+)

...

The c14n/attribute post-login subject canonicalization flow extracts a username from an IdPAttribute resolved (primarily) using the attribute resolution function within the IdP. A common use for this flow is to perform a directory or database lookup to map information derived from the authentication process (e.g. the subject of a certificate) into a different value for use within the IdP.

A secondary feature in V4.1+ allows for a Subject that contains one or more IdPAttributePrincipal objects to be processed directly for an IdPAttribute to pull the value from. This is primarily of use with various "external" authentication options such as SAML proxying, allowing a SAML Attribute decoded from another IdP to be directly consumed and used as a canonical principal name without the hassle of the attribute resolution process (and configuration).

...

Localtabgroup
Localtab live
titleV4.0

Use conf/c14n/attribute-sourced-subject-c14n-config.xml to configure this flow, along with the AttributeResolverConfiguration.

Typically you will supply a list of attributes to resolve and a list of attributes to search for in the results. The first such attribute with a suitable value will supply the username to return.

By default, the only transform applied to the result is a trim of leading or trailing whitespace. Case-folding and regular expression replacements can be added, per the reference section below.

Localtab live
activetrue
titleV4.1+

Use conf/c14n/subject-c14n.properties to configure this flow, along with the AttributeResolverConfiguration.

If your system is upgraded, you may continue to use conf/c14n/attribute-sourced-subject-c14n-config.xml as before, or you may remove it, while ensuring the new properties are being loaded.

There are two ways this flow can locate a suitable IdPAttribute to use:

  • By running the "full" Attribute Resolver service (which has some special considerations noted below)

  • By pulling an IdPAttribute directly from an IdPAttributePrincipal in the input Subject (as mentioned above, this is normally useful when proxying authentication to another IdP)

These methods can be combined, in the sense that the list of attributes to search for may be found in either way, so it's possible to run the resolver conditionally and/or check both the Subject and the resolution results. In most cases this is an either/or situation and the resolver won't be used if you expect the data to be in the Subject already.

When pulling directly, you will typically just supply a list of attributes to check for (first value wins), and set the idp.c14n.attribute.resolutionCondition property to "shibboleth.Conditions.FALSE", to turn off the full attribute resolution step.

When using the resolver, typically you will supply a list of attributes to resolve and a list of attributes to search for in the results. The first such attribute with a suitable value will supply the username to return.

By default, the only transform applied to the result is a trim of leading or trailing whitespace. Case-folding and regular expression replacements can be added, per the reference section below. The regular expression replacement feature is the only one remaining that still requires XML and you may define that bean, if needed, in conf/c14n/subject-c14n.xml

Using the Attribute Resolver

...

Usually, the attribute resolver relies on the canonical principal name to do its work (the value of the $resolutionContext.principal variable in scripts or search templates). By definition that isn't possible here (this is the process that provides that value later), but the value of that variable in the resolver can be set by means of a function bean (e.g., using a script) named shibboleth.c14n.attribute.PrincipalNameLookupStrategy. In most cases this function would peek inside the Java Subject being canonicalized and pull out custom bits of information.

The Java Subject this flow is operating on can be accessed via an expression of the form:

...

While it would not be a typical case to need to access a value entered by a user except in one specific case noted below, that value will be present inside the Subject as a principal object of type net.shibboleth.idp.authn.principal.UsernamePrincipal. In most other cases, it's simpler to just leave such a value as the canonical principal name and adjust your resolver configuration to accomodate whatever that might be than to try and use the resolver ahead of time to turn it into some other value.

...

The following example illustrates how one could do this, where one has chosen to allow the user to enter either their uid or their e-mail address as the username. Changes need to be made to all of the following, and sample config highlights the changes to each that would enable such. (One would also need to configure your authn handler to allow for either input, such as changing idp.authn.LDAP.userFilter to '(|(uid={user})(mail={user}))'.)

  • conf/attribute-resolver.xml

  • conf/c14n/subject-c14n.xml

  • conf/c14n/attribute-sourced-subject-c14n-config.xml (V4.0) or conf/c14n/subject-c14n.properties (V4.1+)

The example takes the user's input name and supplies it to the attribute resolver to do a search of LDAP against the two possible candidate attributes and returns the uid attribute from the directory so that either input maps to a fixed output. There are other ways to configure the resolver that might be more aligned to other searches you need to perform, cache results, etc. but this illustrates the idea.

attribute-resolver.xml
Expand
Code Block
    <!-- Example LDAP Connector -->
    <resolver:DataConnector id="myLDAP" xsi:type="dc:LDAPDirectory" exportAttributes="uid"
       ldapURL="ldap://localhost:10389"
       baseDN="ou=People,dc=example,dc=edu"
       principal="cn=admin,dc=example,dc=edu"
       principalCredential="password">
       <dc:FilterTemplate>
           <![CDATA[
               (|(uid=$resolutionContext.principal)(mail=$resolutionContext.principal))
           ]]>
       </dc:FilterTemplate>
       <dc:ReturnAttributes>uid</dc:ReturnAttributes>
    </resolver:DataConnector>
subject-c14n.xml
Code Block
languagexml
<!-- Remove comment tags to enable Attribute-based c14n -->
<bean id="c14n/attribute" parent="shibboleth.PostLoginSubjectCanonicalizationFlow" />

...

Localtabgroup
Localtab live
titleBeans (V4.0)

The beans defined in conf/c14n/attribute-sourced-subject-c14n-config.xml follow:

Bean ID

Type

Default

Description

shibboleth.c14n.attribute.AttributesToResolve                      

List<String>


A list of attributes to resolve (an empty list directs the resolver to resolve everything it knows about)

shibboleth.c14n.attribute.AttributeSourceIds

List<String>


A list of attributes to search for in the results, looking for a StringAttributeValue or ScopedStringAttributeValue

shibboleth.c14n.attribute.PrincipalNameLookupStrategy

Function<ProfileRequestContext,String>


Provides a principal name value for the AttributeResolutionContext during attribute resolution (i.e., $resolutionContext.principal will be set)

shibboleth.c14n.attribute.Lowercase

Boolean

false

Whether to lowercase the username

shibboleth.c14n.attribute.Uppercase

Boolean

false

Whether to uppercase the username

shibboleth.c14n.attribute.Trim

Boolean

true

Whether to trim leading and trailing whitespace from the username

shibboleth.c14n.attribute.Transforms

Pair<String,String>


Pairs of regular expressions and replacement expressions to apply to the username

Localtab live
titleBeans (V4.1+)

The following beans may be defined in conf/subject-c14n.xml if needed:

Bean ID

Type

Description

shibboleth.c14n.attribute.PrincipalNameLookupStrategy

Function<ProfileRequestContext,String>

Provides a principal name value for the AttributeResolutionContext during attribute resolution (i.e., $resolutionContext.principal will be set)

shibboleth.c14n.attribute.Transforms

Pair<String,String>

Pairs of regular expressions and replacement expressions to apply to the attribute-sourced username

Localtab live
activetrue
titleProperties (V4.1+)

The following properties are commented out in conf/c14n/subject-c14n.properties:

Name / Type / Default

Default

Description

idp.c14n.attribute.attributesToResolve


Comma-delimited list of attributes to resolve (an empty list directs the resolver to resolve everything it can)

idp.c14n.attribute.attributeSourceIds


Comma-delimited list of attributes to search for in the results, looking for a StringAttributeValue or ScopedStringAttributeValue

idp.c14n.attribute.resolveFromSubject

false

Whether to examine the input Subject for IdPAttributePrincipal objects to pull from directly, instead of from the output of the Attribute Resolver service

idp.c14n.attribute.resolutionCondition

shibboleth.Conditions.TRUE

Bean ID of a Predicate<ProfileRequestContext> to evaluate to determine whether to run the Attribute Resolver or go directly to the Subject alone

idp.c14n.attribute.lowercase

false

Whether to lowercase the username

idp.c14n.attribute.uppercase

false

Whether to uppercase the username

idp.c14n.attribute.trim

true

Whether to trim leading and trailing whitespace from the username

...