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 "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.
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:
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.
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.
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.
Standard across the system, this is a condition to evaluate at runtime to control whether to apply the rule
Defaults to true, can be set false to limit use of the rule to decoding only
Defaults to true, can be set false to limit use of the rule to encoding only
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
Language-specific values to use as display names for the IdPAttribute
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: