Reloading SAML: Why do you need SAML Metadata?

9 min readApr 1, 2018

As we previously discussed, SAML is a structured format to define security information (assertions) about a subject (usually about an individual) by an authorized authority called asserting party; however, there is no point to generate a SAML assertion and keep it itself by the asserting party, instead generated SAML assertions need to be shared with another party so that this other party can use this SAML assertion, technically we call this other party as relying party.

As we discussed, SAML assertions are only useful when they transmit from one party to another usually over a network connection. By the way, SAML does not define its own transport mechanism, instead, SAML utilize existing Internet protocols such as HTTP, SOAP etc. these transport semantics are known as SAML Bindings and we have discussed SAML Bindings during our previous post.

In real-world, in order to communicate between two parties, there should be a prior agreement between these two parties, this is a valid requirement for communication between SAML asserting party and SAML relying on the party as well. To generate and transmit a SAML assertion by a particular SAML entity it should know the following information about the other party.

The unique identifier of the other party, in SAML jargons this is called as “entityID”.
The role of the other party, for example in Web Browser SSO profile <AuthRequest> message need to send to a party which can play a “SSO IdP” role.
Whether the other party expect confidentiality during the message transmission? if that is the case generated SAML assertions need to be encrypted before the transmission, also the first party should know the encryption algorithms and other cryptographic policies supported by the other party.
Whether the other party expect message integrity and proof of origin for SAML messages? if that is the case generated SAML assertions need to be digitally signed before the transmission, also the first party should know the signing algorithms and other cryptographic policies supported by the other party.
Also for both message encryption and signing each party should have a valid public key certificate of the other party.
Supported transport and messaging semantics of the other party, in SAML jargons this is called supported bindings, an example whether the other party support bindings such as HTTP-GET, HTTP-POST, HTTP POST etc.
Network locations or endpoint address to establish network connections and transmit messages.
SAML attribute profiles supported by the other party.
Indication of the validity of the above data to determine whether that information are outdated or not.

Now let’s move to the main question of this post,

how one party describe above information and make them available for the other party ?

We can find two possible answers for the above question

Use human language to describe all of this information so that a human being can read & understand this manual and then configure/program systems accordingly. Theoretically, this should work but practically this caused lot of problems, some of the disadvantages are machines can not understand these manuals and there is no standard format.
Use structured and machine-readable format, this approach solves both of the disadvantages related to the previous approach.

Note : Following page, which contains detailed instructions about how to configure SAML SP in WSO2 IS is an example for the above 1st approach.

Metadata for SAML V2.0 specification defines XMLSchema based such machine-readable format to describe capabilities and expectations of a SAML actor. This post tries to introduce and discuss core concepts related to SAML Metadata specification.

Unique identification of SAML Entity

Each of the entity (SP, IdP etc.) that participates in SAML protocol should have a unique identifier, this identifier should be a URI with maximum 1024 characters. According to Metadata specification this identifier is represented as an attribute called “entityID” within <EntityDescriptor> or <EntitiesDescriptor> elements.

Also any valid Metadata definition should start with either <EntityDescriptor> or <EntitiesDescriptor> elements. <EntityDescriptor> used to describes a single deployment of SAML entity and <EntitiesDescriptor> used to describes a group of SAML deployments.

Anatomy of SAML Metadata Definition

Following diagram illustrates the typical high-level elements of SAML Metadata Definition.

EntityDescriptor

As discussed <EntityDescriptor> element is the root element of a SAML metadata definition and denote a SAML entity such as SAML SP, SAML IdP . <EntityDescriptor> element can contain following attributes.

entityID [Required] — the unique identifier of the SAML entity which is described by this definition.
ID [Optional] — a document-unique identifier for the element, typically used as a reference point when signing.
validUntil [Optional] — The expiration time of the metadata
cacheDuration [Optional] — the maximum length of time a consumer should cache the metadata.

Example EntityDescriptor from Salesforce

<ds:Signature>

Used to include a digital signature that can be used to sign various elements in a metadata definition.

<Extensions>

Used to include metadata extensions that are agreed upon between a metadata publisher and the consumer, we will discuss actual usage of this element in a later section of this post.

<Organization>

The optional element which can be used to identifying the organization responsible for the SAML entity, it possible to include details such as organization’s name, display name, URL.

<ContactPerson>

This element can be used to provide various kind of information about a contact person such as individuals’ name, email address and phone numbers etc.

<AdditionalMetadataLocation>

This element can be used to provide a set of locations where additional metadata exists for the current SAML entity.

Role Descriptors

This is one of the very important members of a SAML metadata definition and used to describe the role or capabilities of the SAML entity. As shown in the following diagram SAML Metadata specification define a set of SAML roles, additionally it also facilitates to derive new SAML roles as needed.

In a later section of this post, we’ll look at a few important roles with details, hence following section limit to provide a very brief introduction about each of the role.

<IDPSSODescriptor> — Used to describe identity providers(IdP) supporting SSO.
<SPSSODescriptor> — Used to describe service providers(SP) supporting SSO.
<AuthnAuthorityDescriptor> — Used to describe SAML authentication authorities or in an other words SAML entities that can respond to <samlp:AuthnQuery> requests.
<AttributeAuthorityDescriptor> — Used to describe SAML attribute authorities or in an other words SAML entities that can respond to <samlp:AttributeQuery> requests.
<PDPDescriptor> — Used to describe XACML policy decision points support for XACML SAML Profile.
<AffiliationDescriptor> — This role is somewhat different from other roles, instead of describing its own roles this element is used to define an affiliation among SAML entities.

It’s also possible to use one SAML metadata definition to describe a number of SAML entities, in such cases <EntitiesDescriptor> element is used as the root element instead of <EntityDescriptor> element. <EntitiesDescriptor> element can contain collection of <EntityDescriptor> elements or collection of <EntitiesDescriptor> elements.

So far we have discussed a lot of details related to SAML specification, from now onward I will change the style of the post and try to move forward with more examples/practical oriented approach.

During the previous post we looked at the role of SAML as a SSO implementation technology, in an any usual SSO scenario we can identify two distinct roles as Identity Provider (IdP) who act as the SAML asserting party and Service Provider (SP) who act as the relying party, in next two sections we will look at how SAML metadata can be used to describe IdP and a SP.

How to describe SAML SSO supported IdP

Here is a real-world SAML metadata definition which describes a deployment of WSO2 IS that act as SAML SSO provider.

We already discussed about <EntityDescriptor> and <IDPSSODescriptor> in the previous section, but in above example <IDPSSODescriptor> elements contains number of child elements that we haven’t discusse yet, following diagram shows all the possible sub-elements supported by <IDPSSODescriptor> element.

Additionally <IDPSSODescriptor> support “WantAuthnRequestsSigned” attribute as well.

<KeyDescriptor> Element

This element provides information about the cryptographic keys that an entity uses to sign data or receive encrypted keys, along with additional cryptographic details. <KeyDescriptor> element also support for an attribute called “use” which can be used to specify the purpose of the key being described and possible values are “encryption” and “signing”.

Additionally <KeyDescriptor> element support following sub-elements as well.

<ds:KeyInfo> element that directly or indirectly identifies a key
<EncryptionMethod> specifying an algorithm and algorithm-specific settings supported by the entity.

In the above example, it included a X509 certificate which is used for signing. I internally skip discussing other elements at this point and when we discuss each profile (which map with each practical use of SAML) I will describe how each of this element is related to each profile.

How to describe SAML SSO supported SP

Like in the previous section, let’s start with the following example which describes Salesforce as a SAML service provider and downloaded from Salesforce SSO settings page.

Following diagram shows all the possible sub-elements under the <SPSSODescriptor>.

Additionally <SPSSODescriptor> support “AuthnRequestsSigned” and “WantAssertionsSigned” attributes as well.

Again for the same reason, I skip the discussion on sub-elements of <SPSSODescriptor> at this point and will discuss them under each SAML profile.

How to exchange SAML Metadata

So far we discussed various aspects of SAML Metadata definition, now let’s look at how you can exchange generated metadata with another party, there are two approaches possible.

Static Configuration

Source — https://en.wikipedia.org/wiki/SAML_Metadata#Liberty_Metadata_Specifications

In this approach, an administrator receives a SAML metadata definition via an offline channel such as email and deployed into the SAML entity ( such as IDP, SP) by himself. This is a quite popular approach but the main disadvantage of this approach is once some of the metadata belong to one party get invalid there are no automated means to correct them except human interventions.

To give a real-world example, to configure WSO2 IS as a trusted IdP for Salesforce, one can use the following two simple steps.

Step -1: Download the IdP metadata file from WSO2 IS deployment and upload into Salesforce SAML SSO configuration page.

Salesforce SSO page for IdP Metatada uploads

Salesforce SAML IdP configuration after uploading the IdP Metadata from WSO2 IS

Step -2: Download the SP metadata file from Salesforce and upload that into WSO2 IS SP configuration page.

WSO2 IS SP configuration after uploading Salesforce SP Metadata file.

Note: You can find further details about the above example from here

2. Dynamic exchange

In this approach, both parties collect metadata definition from a 3rd party service and this 3rd party service is responsible to ensure the accuracy of SAML metadata definitions, compared to the previous approach this is more robust but involve some runtime complexity.

I believe I have covered most of the basic concepts related to SAML metadata specification including understanding the metadata definitions and transmission mechanisms within this post.