TranscodingRuleConfiguration

1 Overview
- 1.1 Transcoder rule for "mail"
2 Rule Formats
- 2.1 Spring XML version of "mail" rule
3 Generic and Required Properties
4 Reference
5 Other Examples
- 5.1 Non-Standard Naming
- 5.2 Metadata-Driven Naming 5.1

Overview

A transcoding rule is a collection of properties describing how to translate between an "outside" representation of a piece of data and an "inside" representation in the form of an IdPAttribute object. The IdPAttribute class is the main type of object that holds information about a subject, and may come from a variety of sources, though usually they're produced by the Attribute Resolver service.

The "outside" representations can be anything, provided there are plugins available that know how to convert to and from another form. Historically the main example of this has been SAML <Attribute> elements (both SAML 1 and SAML 2) but includes other types of objects as well.

The plugin type that implements these translations is the AttributeTranscoder, of which there are a number of specialized subtypes and concrete implementations that understand how to handle particular kinds of IdPAttributeValue subclasses.

An AttributeTranscoder object is actually very generic and only cares about the syntax of the data it handles; it gets everything else it needs to know at runtime from a set of rules expressed in the form of a Map. The map is keyed by simple string names of properties that describe how to encode and decode the data, and the values are of any type, depending on the specific property. Most are Strings or Booleans, but can be anything.

Most transcoding rules concern themselves with addressing the following:

the "id" of the IdPAttribute, which identifies the data inside the IdP
the naming of the object outside the IdP, as in the case of a SAML 2.0 Attribute's Name and NameFormat
the AttributeTranscoder that should be used to encode and decode the data values

There are some other kinds of properties, but the most important ones are just those three. The most common additional need is for the “relyingParties” property, which is a brute force way to control the application of the rule to only specific SPs (or IdPs in the case of proxying).

As a practical example, a standard transcoding rule for handling e-mail addresses in SAML using the Properties syntax discussed later might be:

Transcoder rule for "mail"

id=mail
transcoder=SAML2StringTranscoder SAML1StringTranscoder
saml2.name=urn:oid:0.9.2342.19200300.100.1.3
saml1.name=urn:mace:dir:attribute-def:mail

The "transcoder" property is referring to the bean names of the objects to use, which are documented on the parent page, and the others are pretty self-explanatory if you've seen defaults in older versions of Shibboleth. Note that as with all historical Shibboleth practice in the IdP and SP, that rule implies a SAML 2.0 NameFormat of “urn:oasis:names:tc:SAML:2.0:attrname-format:uri” and a SAML 1.1 AttributeNamespace of “urn:mace:shibboleth:1.0:attributeNamespace:uri”.

A complete explanation of how this works and what the property names are follows.

Rule Formats

The two main approaches for defining rules are using Spring XML and Java Properties files. We expect most people will be happier to define one-off exceptions for local needs using the Properties syntax.

Because the Properties format is limited to expressing a single rule at a time, the XML approach using Spring syntax is more appropriate for defining lots of rules at once without ending up with a giant pile of small files. It's a good way to deliver standard rules both by us and potentially by other sources of commonly defined rules in the future. It also supports Spring property replacement, which can be useful as well.

Both formats ultimately require a Map<String,Object> be constructed and passed into the the underlying class, TranscodingRule.

A parent bean called shibboleth.TranscodingRule to support direct use of the class, but in most cases (*) it's easier to use the shibboleth.TranscodingProperties parent bean, which allows the rule to be defined using the Spring <props> element. There's a little bit more syntax used in order to support merging of the properties back into a set of defaults we include to reduce the amount of work and duplication needed to define new rules.

(*) The main reason you might need the direct class is to use non-String values of properties, which is not a general need; the system converts things from String internally to simplify things.

The conf/attributes/default-rules.xml file includes a number of examples of this syntax being used.

The other useful bean, also used in that file, is shibboleth.TranscodingRuleLoader, and the value of that bean with this syntax is that it allows multiple rules to be collected together in a list without each individual rule having to be given a Spring bean ID, which is just more work and hassle to assign while avoiding duplication.

The previous example for "mail" when defined in this syntax would be:

Spring XML version of "mail" rule

<bean parent="shibboleth.TranscodingProperties">
	<property name="properties">
		<props merge="true">
			<prop key="id">mail</prop>
			<prop key="transcoder">SAML2StringTranscoder SAML1StringTranscoder</prop>
			<prop key="saml2.name">urn:oid:0.9.2342.19200300.100.1.3</prop>
			<prop key="saml1.name">urn:mace:dir:attribute-def:mail</prop>
		</props>
	</property>
</bean>

The only functional difference is that this rule includes via merge a couple of additional default properties that are included in the IdP's system files.

The alternative syntax for defining a single rule is just to use a Java Properties file (only the non-XML flat-file syntax is supported, because, obviously...)

An example of this was shown earlier. A key point: the name of the file is irrelevant. It doesn't make assumptions about the attribute ID based on the name or allow that property to be omitted. In practice of course it's sensible to name things appropriately for ease of maintenance.

The use of Properties files is also handled by the shibboleth.TranscodingRuleLoader bean, which supports vacuuming up a directory tree of Properties file all at once.

This is illustrated for you in the conf/attribute-registry.xml file, and by default the conf/attributes/custom/ directory is already designated as a place for these files to be created. You can create any subfolders you want for organization because it will walk the whole tree.

You can of course create other loader beans that load different directories if desired.

A minor limitation of this approach is that it does not allow the idp.service.attribute.registry.encodeType Spring property to be honored by custom rules. If you want to alter the default for the SAML transcoders' “encodeType” setting, you will need to explicitly set that property in the rule as documented for those transcoders.

Generic and Required Properties

Most of the properties used in rules are actually not generic but are a consequence of which AttributeTranscoders are used; each such object defines a contract with regard to what properties it supports and especially what properties it requires to operate. Errors won't generally be detected until runtime and then logged and generally ignored. The rule will simply be non-functional.

There are a small set of generic properties, some required and some optional. The "Type" refers to the underlying object that the system expects to be able to produce as a value of the property, but String is almost always a supported format to use for convenience.

Name	Req?	Type	Description

Name	Req?	Type	Description
id	Y	String	The IdPAttribute id/name that is used internally. This dictates when the rule will be applied to attributes within the IdP for outbound encoding, as well as what to call an attribute created during inbound decoding.
transcoder	Y	Space-delimited list of Bean IDs, or an AttributeTranscoder	This defines which AttributeTranscoder objects should be used to encoder and decode data when the rule runs, and dictates most of the rest of the properties that will be required or supported. In most cases this is expressed by specifying one or more Spring bean IDs in a list; the implementation will turn those into the right objects if they exist.
activationCondition		Predicate<ProfileRequestContext> or a Bean ID	Standard across the system, this is a condition to evaluate at runtime to control whether to apply the rule
encoder		Boolean	Defaults to true, can be set false to limit use of the rule to decoding only
decoder		Boolean	Defaults to true, can be set false to limit use of the rule to encoding only
relyingParties		Collection<String> or a space-delimited list of Strings	Shortcut for applying an activation condition that matches a set of relying party names against the request
displayName[.lang]		String	Language-specific values to use as display names for the IdPAttribute
description[.lang]		String	Language-specific values to use as descriptions for the IdPAttribute

The latter two are optionally language-aware; if the raw property name is used, then the corresponding value is used any time the default Locale is in effect for a request. Otherwise a dot separator must be followed by a language code, which may also include country code.

The rest of the supported properties can be found in the documentation specific to the various categories of AttributeTranscoders:

The OIDC OP plugin also includes a set of claim transcoders.

Reference

Also discussed above, there are several beans defined to support the creation of the mapping rules contained in the registry.

Name	Type	Description

Name	Type	Description
shibboleth.TranscodingProperties	Properties	Parent bean for defining transcoding rules using a Java Properties object
shibboleth.TranscodingRule	TranscodingRule	Parent bean for low-level Spring-based creation of transcoding rules; shibboleth.TranscodingProperties is generally used instead
shibboleth.TranscodingRuleLoader	TranscodingRuleLoader	Parent bean for defining collections of rules either as a collection of maps or by loading property files from a directory
SAML2StringTranscoder SAML2ScopedStringTranscoder SAML2ByteTranscoder SAML2XMLObjectTranscoder SAML2DateTimeTranscoder SAML1StringTranscoder SAML1ScopedStringTranscoder SAML1ByteTranscoder SAML1XMLObjectTranscoder CASStringTranscoder CASScopedStringTranscoder CASDateTimeTranscoder	AttributeTranscoder	Built-in collection of transcoders usable in rules

Other Examples

Non-Standard Naming

While we advise against doing so, you will run into constant pressure from vendors to support one-off Attribute names. When you agree to do that, you should understand that it won’t stop, and you will end up over time with dozens of these rules to maintain and a brittle configuration prone to problems. Standards exist for that reason.

Having said that, it is possible to support exception-based naming in a number of ways, and if you keep it to a minimum it may be sufficient to just name the SPs for which a rule should apply and create a property file (e.g., in conf/attributes/custom/mail.properties) to add the rule like so:

id = mail
transcoder = SAML2StringTranscoder SAML1StringTranscoder
saml2.name = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
saml2.friendlyName = mail
saml2.encodeType = false
saml2.relyingParties = https://broken.example.org/sp

This is merely an alternative approach to using an AttributeEncoder to do the same thing, just outside instead of inside the resolver configuration.

Metadata-Driven Naming ^5.1

Yet another way to handle exception-based naming rules is with SAML metadata. Each set of transcoders for a protocol supports its own property for instructing the system to check for a metadata “tag” extension that carries values specifying naming rules specific to that SP. This approach only applies to encoding of data, not decoding. Refer to the protocol-specific transcoder topics linked above for the details and examples.