SAML1AttributeTranscoderConfiguration

1 Overview
2 Common Properties
3 Metadata-Based Naming 5.1
- 3.1 Example
4 Transcoder Types

Overview

A set of built-in transcoders supporting SAML 1 <Attribute> and <AttributeDesignator> objects is provided that support the most frequently needed value types. Most of them support a common set of properties, documented below; a few other properties are defined for specific transcoder types. Since they largely all do the same thing in the same way, they're documented here together.

A particular property of the SAML schema is that <AttributeDesignator> cannot have values while <Attribute> MUST have them, so there are some built-in enforcement checks.

Note that <AttributeDesignator> elements can be mapped to and from IdPRequestedAttribute objects but the conversion is lossy due to the lack of an isRequired property in SAML and the inability to express requested values.

Common Properties

In addition to the generic properties, all SAML 1 transcoders support the following:

Name	Type	Default	Description

Name	Type	Default	Description
saml1.name	String		The `<Attribute>` `AttributeName` to map to and from
saml1.namespace	String	urn:mace:shibboleth:1.0:attributeNamespace:uri	The `<Attribute>` `AttributeNamespace` to map to and from
saml1.encodeType	Boolean	true	Whether to encode values with an `xsi:type` attached
saml1.nameFromMetadata ^5.1	Boolean	false	Whether to check for a metadata extension tag for naming rules

Note the default for “saml1.namespace” above. If your desired inbound or outbound syntax does not include the AttributeName XML Attribute or relies on a different value, then you MUST set it explicitly in the rule.

Metadata-Based Naming ^5.1

The transcoders also support an option to rely on SAML metadata extension tags to provide SP-specific naming rules. This is an alternative to the use of the relyingParties approach of naming specific SPs in a rule to limit its use. This feature can be combined with “default” naming via a rule such that the metadata is checked for a per-SP name in preference to the default in a rule, with the default applying in the absence of a tag value applying.

Note that this approach only works for encoding into SAML, and does not support the decoding side because the “source name” of a SAML Attribute would then not be known to the system independently of a specific SP (the encoding direction works because the source name there is the internal attribute ID, which is required to be specified in the rule).

To use this feature, the rule must contain the saml1.nameFromMetadata property set to true. The rule may or may not also contain the default saml1.name (and saml1.namespace) properties as a fallback.

If in use, all SAML 1 transcoders will check for an extension Attribute/tag of the name “http://shibboleth.net/ns/attributes/naming/saml1” whose values contain a space-delimited tuple of the form “id name namespace”. All three values MUST be present. A tag may contain multiple values, but only the first value containing the matching attribute ID will be applied.

Whether this approach is better for you really depends on how you manage and curate metadata and your ability to extend it, which is increasingly the key to most effectively operating the Shibboleth software.

Example

Consider an SP (let’s call it Sluck), that requires mail, givenName, and sn to be supplied using invented Attribute names, in contravention to the SAML standard. To enable metadata-based naming override, the saml1.nameFromMetadata property flag has to be added to each of the rules (all three in this case are in conf/attributes/inetOrgPerson.xml). The metadata for Sluck would then contain the following extension block:

<EntityDescriptor entityId="https://example.sluck.com" ...>
...
  <Extensions>
    <mdattr:EntityAttributes xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute">
    
      <!-- Note that the tag here MUST contain the proper NameFormat to be honored. -->
      <saml:Attribute xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
          Name="http://shibboleth.net/ns/attributes/naming/saml1"
          NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <!-- Three overridden naming rules. -->  
        <saml:AttributeValue>mail email unspecified</saml:AttributeValue>
        <saml:AttributeValue>givenName first_name unspecified</saml:AttributeValue>
        <saml:AttributeValue>sn first_name unspecified</saml:AttributeValue>
        
      </saml:Attribute>
      
    </mdattr:EntityAttributes>
  </Extensions>
...
</EntityDescriptor>

The AttributeNamespace value in the rules in the example is arbitrary as this is not a real world example and the use of that field in SAML 1 was essentially unspecified, so other than our default, no other values really have ever been defined anywhere, and our default only applies to the use of URI naming.

Transcoder Types

There are 4 built-in subtypes of SAML 1 transcoders, as follows. Each one is predefined as a Spring bean for use in rules using the "short" name of the class, as enumerated in the TranscodingRuleConfiguration reference section.

SAML1StringAttributeTranscoder

The simplest and most commonly used transcoder, it supports encoding and decoding internal values from and to the StringAttributeValue class. It supports no additional properties.

SAML1ScopedStringAttributeTranscoder

It supports encoding and decoding internal values from and to the ScopedStringAttributeValue class. It supports the following additional properties (all optional):

Name	Type	Default	Description

Name	Type	Default	Description
saml1.scopeType	"inline" or "attribute"	"attribute"	The "style"/syntax with which to encode and decode the scope portion
saml1.scopeAttributeName	String	Scope	The name of the XML attribute to encode and decode the scope portion when saml1.scopeType is "attribute"
saml1.scopeDelimiter	String	@	The character(s) to use to separate the value and scope when saml1.scopeType is "inline"

SAML1ByteAttributeTranscoder

It supports encoding and decoding internal values from and to the ByteAttributeValue class, with a base64 transform applied. It supports no additional properties.

SAML1XMLObjectAttributeTranscoder

It supports encoding and decoding internal values from and to the XMLObjectAttributeValue class. It supports the following additional properties (all optional):

Name	Type	Default	Description

Name	Type	Default	Description
saml1.includeAttributeValue	Boolean	false	When decoding, controls whether the decoded XMLObject is actually the `<AttributeValue>` element itself, or its child element