| Table of Contents |
|---|
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.
...
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.
...
The name property in the rule corresponds to the Name XML attribute of a SAML <saml2:Attribute> or <saml1or <saml1:Attribute> element or the Format XML attribute of a SAML <saml2:NameID> or <saml1:NameIdentifier> element.
...
This page refers to several different namespaces by convention as detailed below:
NameSpace | URI | Description |
|---|---|---|
saml | urn:oasis:names:tc:SAML:1.0:assertion | SAML1 Assertion namespace |
saml2 | urn:oasis:names:tc:SAML:2.0:assertion | SAML2 Assertion namespace |
am | urn:mace:shibboleth:2.0:attribute-map | The Shibboleth SP Attribute Map namespace |
conf | urn:mace:shibboleth:3.0:native:sp:config | The Shibboleth SP core configuration namespace |
md | urn:oasis:names:tc:SAML:2.0:metadata | The SAML2 Metadata namespace |
mdattr | urn:oasis:names:tc:SAML:metadata:attribute | The 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:
| Include Page | ||||
|---|---|---|---|---|
|
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.
Name | Cardinality | Description |
|---|---|---|
<am:Attributes> | 1 | Root element of configuration |
When a non-inline configuration is used, it supports the following child elements common to all reloadable configuration resources.
| Include Page | ||||
|---|---|---|---|---|
|
<am:Attributes> Element Reference
...
The following optional attributes are supported:
Name | Type | Default | Description |
|---|
metadataPolicyId metadataPolicyId | string | Optional reference to a security policy to apply to SAML assertions processed in |
the <mdattr: |
EntityAtributes> metadata extension (see below). |
metadataAttributeCaching metadataAttributeCaching | boolean | true | When 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 | |
|---|---|---|---|
> | 0 or 1 | Supplies a dedicated MetadataProvider for use in validating SAML assertions processed in the | |
> | 0 or 1 | Supplies a dedicated TrustEngine for use in validating SAML assertions processed in the | |
0 or 1 | Supplies a dedicated AttributeFilter for use in filtering data from SAML assertions processed in the | ||
<am:Attribute> | 1 or more | An extraction rule (see next section) | |
<am:Attribute> Element Reference
Each <am:Attribute> element element describes an extraction rule, the core of this plugin's behavior.
Attributes
Name | Type | Req? | Description |
|---|---|---|---|
name | string | Y | SAML Attribute Name or Name Identifier Format to extract |
nameFormat | string | 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. | |
id | string | Y | Internal ID by which the extracted SP attribute will be known, generally a common/short/simple name for the data element |
Child Elements
Name | Cardinality | Description |
|---|---|---|
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
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<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> | ||||||
| language | xml | title |
Loading an externally specified mapping file
| Code Block | ||||
|---|---|---|---|---|
| ||||
<AttributeExtractor type="XML" validate="true" reloadChanges="false" path="attribute-map.xml"/> |
...
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".
...
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.
| Note |
|---|
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.
...