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 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.
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.
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.
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 |
|---|---|---|---|
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 4.1 | Boolean | Defaults to true, can be set false to limit use of the rule to decoding only | |
decoder 4.1 | 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.