Versions Compared

Key

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

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

Table of Contents

Overview

The c14n/x500 “x500” post-login subject canonicalization flow c14n method extracts a username from a Java Subject that contains either a single X509Certificate object in the public credentials set or a single X500Principal in the Principal set. It is primarily designed to work in conjunction with the X509 or X509Internal login flows .

General Configuration

Expand
titleV4.0

Use conf/c14n/x500-subject-c14n-config.xml to configure this flow.

...

titleV4.1+

(i.e., certificate-based authentication).

Configuration

Method Settings

Use conf/c14n/subject-c14n.properties to configure this

...

method.

If your system

...

has been upgraded, you may continue to use conf/c14n/x500-subject-c14n-config.xml as before, or you may remove it, while ensuring the new properties are being loaded.

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

By default, the subject DN is searched for a "CN" RDN attribute (with OID 2.5.4.3). You can configure alternative attributes to search for, or give preference to subjectAltName extensions (if an X509Certificate is present).

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.

...

Enabling this Method

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

Description

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

Expand

Bean ID

Type

titleBeans (V4.0)

Bean ID

Type

Default

Description

shibboleth.c14n.x500.SubjectAltNameTypes

List<Integer>

A list of subjectAltName extension types to look for

shibboleth.c14n.x500.ObjectIDs

List<String>

2.5.4.3

A list of attribute OIDs to search for in the subject DN

shibboleth.c14n.x500.Lowercase

Boolean

false

Whether to lowercase the username

shibboleth.c14n.x500.Uppercase

Boolean

false

Whether to uppercase the username

shibboleth.c14n.x500.Trim

Boolean

true

Whether to trim leading and trailing whitespace from the username

shibboleth.c14n.x500.Transforms

Pair<String,String>

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

Expand
titleBeans (V4.1+)
V5.2+

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/x500”, so enabling it for a login flow looks like:

Code Block
idp.authn.X509.c14n.flows = c14n/x500

It is possible to configure two instances of this method at the same time with different settings. The default instance is configured with a set of global properties, so defining a second instance of it with different settings requires adding a bean to conf/c14n/subject-c14n.xml. This bean can be defined at the top level of the file and needs a unique ID to reference in the login flow property example above. It does not have to carry the “c14n/” prefix but this is useful for clarity.

As an example, to define a second instance with a rule to lower case the input (without applying that same rule to the default instance of course):

Code Block
<beanid="c14n/x500-lower"parent="c14n/x500"
  p:lowercase="true" />

That then allows you to reference “c14n/x500-lower” in a login flow’s property as above.

Expand
titleOlder Versions

In older versions, this method is generally enabled for you by default by virtue of a reference to the bean in the shibboleth.PostLoginSubjectCanonicalizationFlows list bean in conf/c14n/subject-c14n.xml:

Code Block
    <util:list id="shibboleth.PostLoginSubjectCanonicalizationFlows">
        <ref bean="c14n/x500" />
    </util:list>

Most often it shows up last in the list and doesn’t hurt anything to leave enabled, but the reference could be removed if not in use.

Reference

Expand
titleBeans

Bean ID

Type

Description

c14n/x500

X500SubjectCanonicalization

Built-in instance of this method, auto-configured by properties and other beans as described. V5.2+ allows reuse of this bean as a parent to define additional instances of this method with different settings.

shibboleth.c14n.x500.Transforms

Pair<String,String>

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

Expand
titleProperties (V4.1+)

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

Name

Type

Default

Description

idp.c14n.x500.subjectAltNameTypes

List<Integer>

Comma-delimited list of subjectAltName extension types to look for

idp.c14n.x500.objectIDs

List<String>

2.5.4.3

Comma-delimited list of attribute OIDs to search for in the subject DN

idp.c14n.x500.lowercase

Boolean

false

Whether to lowercase the username

idp.c14n.x500.uppercase

Boolean

false

Whether to uppercase the username

idp.c14n.x500.trim

Boolean

true

Whether to trim leading and trailing whitespace from the username