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.
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 | 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
Other Examples
Non-Standard Naming
While we advise against doing so, you will run into constrant 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.