Page tree
Skip to end of metadata
Go to start of metadata

Overview

Identified by type="XML", this AttributeExtractor implements an XML-based rule syntax for designating SAML attributes and name identifiers to decode into internal attributes. Your configuration will almost certainly be using this plugin type. Next to metadata, this is probably the most commonly "touched" aspect of the configuration on the SAML side and forms the basis of the useful behavior of the SP to get information out of the SAML exchange into server variables for your application to access.

At a basic level, what you're doing here is taking each individual SAML Attribute or Name Identifier you want to support and creating a corresponding <am:Attribute> element (or uncommenting or adjusting one that already exists by default) in the configuration to match and map that incoming thing into an internal thiing.

The plugin supports extraction of SAML Attributes and Name Identifiers from the following SAML constructs (it does not know how to pull any other data from these elements, only SAML Attributes and Name Identifiers):

  • <saml:Assertion>
  • <saml:Attribute>
  • <saml:NameIdentifier>
  • <saml2:Assertion>
  • <saml2:Attribute>
  • <saml2:NameID>
  • <saml2:EncryptedAttribute>

The actual extraction process relies on a secondary layer of AttributeDecoder plugins that actually consume the XML content and turn it into string data.

This extractor's configuration is implemented as a reloadable XML resource, which means that the XML content can be supplied inline, in a local file, or a remote file, and can be monitored for changes and reloaded on the fly (but see the warning below). The root of the XML in any of those cases MUST be an <am:Attributes> element, either as a child element in an existing file or the root of a different file.

Exercise caution allowing this particular configuration to be reloadable if you rely on HTTP request headers to access attribute information. You should avoid using headers, in which case the file can be safely made reloadable, but when headers are used there are limitations internally on how the system tracks which headers are being reserved for SP data and if this falls out of sync, it becomes possible for a client to smuggle/spoof headers into unprotected variables the SP hasn't recognized it needs to protect yet because the set changed.

A full restart of both the shibd daemon and the web server is generally required to make header extraction changes reliable, and as a result the shipping defaults mark this configuration as non-reloadable.

General Configuration

Each <am:Attribute> child element installs a rule for extracting a particular SAML Attribute or type of Name Identifier into an internal SP attribute. The source of the attribute is identified with the name (and possibly nameFormat) XML attributes and internally tagged by the id.

The name property in the rule corresponds to the Name XML attribute of a SAML <saml2:Attribute> or <saml1:Attribute> element or the Format XML attribute of a SAML <saml2:NameID> or <saml1:NameIdentifier> element.

The Shibboleth SP by default will install rules using a nameFormat of urn:mace:shibboleth:1.0:attributeNamespace:uri and urn:oasis:names:tc:SAML:2.0:attrname-format:uri to accommodate both SAML versions.

The nameFormat property can be omitted unless a different NameFormat is being used. This property is also omitted/ignored when extracting information from a <saml2:NameID> or <saml1:NameIdentifier> element.

The internal id is typically short/simple and is used throughout all other SP components (such as attribute filters).

Multiple <am:Attribute> rules can share the same id; the implication is that a given internal name may be mapped from multiple externally-named sources to consolidate multiple sources down into one representation.

There are examples of rules later in this page to illustrate how this works; it's very simple in practice.

Reference

XML Namespaces

This page refers to several different namespaces by convention as detailed below:

NameSpaceURIDescription
saml

urn:oasis:names:tc:SAML:1.0:assertion

SAML1 Assertion namespace
saml2

urn:oasis:names:tc:SAML:2.0:assertion

SAML2 Assertion namespace
amurn:mace:shibboleth:2.0:attribute-mapThe Shibboleth SP Attribute Map namespace
confurn:mace:shibboleth:3.0:native:sp:configThe Shibboleth SP core configuration namespace
mdurn:oasis:names:tc:SAML:2.0:metadata

The SAML2 Metadata namespace

mdattrurn:oasis:names:tc:SAML:metadata:attributeThe SAML2 EntityAttribute Metadata Extension namespace

Attributes

Aside from the type="XML" attribute itself, there is no other attribute content specific to this plugin type.

It supports all of the attributes common to all reloadable configuration resources:

NamesTypeDefaultDescription
id
string
Identifies the component for logging purposes.
url
 URL

Remote location of an XML resource containing the required configuration. The SP does not verify the transport (i.e. it does not verify the X.509 certificate presented by the remote server when HTTPS is the transport).

path
local path

Path to a local file containing the required configuration

validate
booleanfalseIf true, XML validation is performed when loading the resource
reloadChanges
booleantrueIf a path attribute is used, the local file is monitored for changes and reloaded dynamically. This incurs some runtime overhead for locking, so should be disabled if not needed.
maxRefreshDelay
time in seconds0If a url attribute is used, this attribute sets the time between attempts to download a fresh copy of the resource. If 0 (the default), no reloading occurs. This incurs some runtime overhead for locking, so should be left at 0 if not needed
reloadInterval


Synonym for maxRefreshDelay

backingFilePath
local path
If a url attribute is used, the downloaded resource is copied to this location. If the software is started and the remote resource is unavailable or invalid, the backing file is loaded instead
certificate
local path
Path to a certificate containing a public key to use to require and verify an XML signature over the resource. The certificate's other content is ignored.
signerName
string
If present, the name is supplied to the <TrustEngine> used to verify an XML signature over the resource. A certificate containing the name must be available in the verification process (typically inside the signature).

Child Elements

The following child element must be provided, either inline, or as the root element of a local or remote XML resource to load from, which would be specified via the attribute(s) above.

NameCardinalityDescription
<am:Attributes>1Root element of configuration

When a non-inline configuration is used, it supports the following child elements common to all reloadable configuration resources.

These child elements are typically only used when relying on a remote configuration resource and are for advanced use cases.

Name

Cardinality

Description

<TrustEngine

0 or 1Used to require the presence of a top-level signature over the entire resource and to control the verification process

<CredentialResolver>

0 or 1

Used to require the presence of a top-level signature over the entire resource and to control the verification process.

Mutually exclusive with the <TrustEngine> element and the certificate attribute.

<TransportOption>

0 or moreProvides low-level control over the library used to remotely access the resource

<am:Attributes> Element Reference

This is the root element of the mapping configuration. Most of the advanced features here are for use with a feature you are very unlikely to encounter in practice, the ability to embed signed SAML Assertions inside a metadata extension as a sort of attestation of some information about an IdP. The only likely content you'll use are the rules themselves via the <am:Attribute> element.

Attributes

The following optional attributes are supported:

NameTypeDefaultDescription
metadataPolicyId string

Optional reference to a security policy to apply to SAML assertions processed in the <mdattr:EntityAtributes> metadata extension (see below).

metadataAttributeCaching booleantrueWhen false, disables the caching of decoded attribute information that is normally done to improve the efficiency of extracting attribute information from the <mdattr:EntityAttributes> metadata extension (see below). The usual reason to turn this off is to support language-aware decoding of attribute values.

Child Elements

The following child element content is supported:

Name

Cardinality

Description

<am:MetadataProvider> 0 or 1Supplies a dedicated MetadataProvider for use in validating SAML assertions processed in the <mdattr:EntityAtributes> metadata extension (see below)
<am:TrustEngine> 0 or 1Supplies a dedicated TrustEngine for use in validating SAML assertions processed in the <mdattr:EntityAtributes> metadata extension (see below)

<am:AttributeFilter>

0 or 1

Supplies a dedicated AttributeFilter for use in filtering data from SAML assertions processed in the <EntityAtributes> metadata extension (see below).

<am:Attribute>1 or moreAn extraction rule (see next section)

<am:Attribute> Element Reference

Each <am:Attribute> element describes an extraction rule, the core of this plugin's behavior.

Attributes

NameTypeReq?Description
namestringY

SAML Attribute Name or Name Identifier Format to extract

nameFormatstring
Optional setting to constrain the matching by Attribute Name to also take into account the AttributeNamespace (SAML 1) or NameFormat (SAML2). The SP defaults this to matching to make attribute names based on URIs automatic. Ignored when matching with Name Identifier.
idstringYInternal ID by which the extracted SP attribute will be known, generally a common/short/simple name for the data element

Child Elements

NameCardinalityDescription
<am:AttributeDecoder>0 or 1

Optionally specifies an attribute decoder to use. A simple/string decoder is used if not otherwise specified, which is sufficient if the values are simple strings without any unusual structure.

Examples

These examples just illustrate how the overall configuration looks within shibboleth2.xml.

For more detailed examples of how to create actual rules, see the XMLAttributeExtractorExamples subpage.

Inline Attribute Extractor
<config:AttributeExtractor type="XML">
	<am:Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    	<am:Attribute name="urn:oid:2.5.4.3" id="cn"/>
	    <am:Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">
    	    <am:AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
	    </am:Attribute>
	</am:Attributes>
</config:AttributeExtractor>
Loading an externally specified mapping file
<AttributeExtractor type="XML" validate="true" reloadChanges="false" path="attribute-map.xml"/>

Metadata Attribute Extraction

The plugin supports a metadata extension used widely in mature metadata deployments, the <mdattr:EntityAttributes> element, which can be used to attach <saml2:Attribute> and <saml2:Assertion> elements to an <md:EntityDescriptor>.  Extracting this data allows information about a user's IdP to be exposed in the same way that a user's other attributes are exposed.

To ensure they can be distinguished from more typical user data, the trigger for this feature is the metadataAttributePrefix property in the <ApplicationDefaults> element. Setting this property is both a precondition for metadata attribute extraction and a value that is prepended to the internal attribute names that result. For example, a prefix of "Meta-" will turn an extracted attribute called "mail" into "Meta-mail".

In the case of bare <saml:Attribute> elements, often termed "tags", this is the entire picture. Any such elements found within an <mdattr:EntityAttributes> extension are processed identically to user attributes with the same set of decoding and mapping rules. The extension may appear on both the <md:EntityDescriptor> and <md:EntitiesDescriptor>elements, and the plugin will walk the metadata tree from the role to the entity level up through any parent groups, and process each extension it finds.

Signed Assertions in Metadata

At only the entity level, the use of embedded, signed SAML assertions is also supported, but this is quite a bit more complex, and may require additional configuration as follows. It's also very rare in practice.

A dedicated MetadataProvider can be defined for the plugin to use when evaluating the assertions. You can think of this as "meta-metadata", definitions of issuers of assertions about issuers of assertions (now you see why it's rare). Issuers of these assertions are required to supply SAML 2.0 Metadata with the <md:AttributeAuthorityDescriptor> role as a convention.

If you don't define a dedicated MetadataProvider for the plugin to use, it will reuse the metadata supplied to the SP as a whole. This may not be the desired behavior.

Optionally, you can also define an embedded instance of a TrustEngine. If one isn't supplied, the normal one defined to the SP will be used when verifying the signed assertions. It's common that this will be sufficient.

The evaluation process is controlled using a Security Policy that is typically specific to this purpose and is referenced by a metadataPolicyId attribute. Normally, rules that would apply to generic assertion processing within the SP, such as replay and freshness checking, do not apply to assertions found in metadata, so a separate policy has to be used.

Note that unsigned assertions are NOT permitted (you'd just embed a <saml2:Attribute> directly).

Finally, you can also define an embedded instance of an AttributeFilter. This enables a special "internal" filtering step to be applied to the attributes extracted from each assertion, separate from the other filtering performed by the SP. Specifically, this filtering step is performed with knowledge of the actual "issuer" of the attributes (the issuer of the embedded assertion). This step is also performed before the attributes are internally renamed and prefixed with the metadataAttributePrefix.

When the SP performs its standard filtering, the metadata attributes will have been renamed, and the "issuer" is presumed to be the user's IdP itself, because all of the attributes have been pooled by that time.

In other words, you should perform any specialized filtering of metadata-based attributes based on their source by using the dedicated filtering step here, and refer to the attributes by their "unprefixed" names. Other, generic filtering rules based on attribute values (e.g. checking syntax) can be applied using the standard filtering step, referring to metadata-based attributes by the "prefixed" names.

  • No labels