SAML metadata

Last updated

[CS 1] The SAML metadata standard belongs to the family of XML-based standards known as the Security Assertion Markup Language (SAML) published by OASIS in 2005. A SAML metadata document describes a SAML deployment such as a SAML identity provider or a SAML service provider. Deployments share metadata to establish a baseline of trust and interoperability.

Contents

Overview

To securely interoperate, partners share metadata in whatever form and by whatever means possible. In any case, at least the following metadata must be shared:

Every SAML system entity has an entity ID, a globally-unique identifier used in software configurations, relying-party databases, and client-side cookies. On the wire, every SAML protocol message contains the entity ID of the issuer.

For authentication purposes, a SAML message may be digitally signed by the issuer. To verify the signature on the message, the message receiver uses a public key known to belong to the issuer. Similarly, to encrypt a message, a public encryption key belonging to the ultimate receiver must be known to the issuer. In both situations—signing and encryption—trusted public keys must be shared in advance.

Once the message is signed and encrypted, the issuer sends the message to a trusted protocol endpoint, the location of which must be known in advance. Upon receipt, the message receiver decrypts the message (using its own private decryption key) and verifies the signature (using a trusted public key in metadata) before mapping the entity ID in the message to a trusted partner.

The previous scenario requires each party to know the other in advance. To establish a baseline of trust, parties share metadata with each other. Initially, this may be as simple as sharing information via email. Over time, as the number of SAML partners grows, the natural tendency is to automate the metadata sharing process.

To fully automate the metadata sharing process, a standard file format is needed. To this end, the SAML V2.0 Metadata specification [OS 1] defines a standard representation for SAML metadata that simplifies the configuration of SAML software and makes it possible to create secure, automated processes for metadata sharing.

Metadata-driven interoperability

As SAML technology has matured, the importance of SAML metadata has steadily increased. Today an implementation that supports SAML web browser single sign-on requires a schema-valid SAML metadata file for each SAML partner. (See the SAML V2.0 Profiles [OS 2] specification for more information about SAML web browser SSO.)

SAML web browser SSO with static metadata configuration SAML Web Browser SSO With Static Metadata.png
SAML web browser SSO with static metadata configuration

Static metadata configuration

The term static metadata refers to a metadata file that is configured directly into the SAML application by an administrator. In doing so, the administrator becomes responsible for the maintenance of the metadata regardless of how the metadata was obtained in the first place. Thus static metadata contributes to the overall static configuration of the SAML application.

Unfortunately, SAML metadata is inherently non-static as illustrated by the following typical scenario between a SAML identity provider (IdP) and a SAML service provider (SP). Suppose an IdP owner obtains SAML metadata from an SP partner. Perhaps the SP metadata is transmitted to the IdP owner via email, or maybe the IdP owner logs into a protected web app and downloads the SP metadata via a browser. Regardless of how the metadata is obtained, the result is the same: the IdP owner configures the SP metadata directly into the IdP software.

Now suppose the SP metadata contains a public encryption key. Presumably, the corresponding private decryption key is configured into the SP software. If the private decryption key is compromised (or otherwise needs to be replaced), the public encryption key in the SP metadata is no longer trustworthy and must be replaced as well.

Since the SP metadata is statically configured in the IdP software, only the IdP owner can replace the public encryption key in the SP metadata. In this sense, the IdP owner is responsible for the SP metadata. This mismatch leads to interoperability issues.

The same is true on the SP side. By statically configuring IdP metadata into the SP software, the SP owner implicitly accepts the responsibility to maintain the IdP metadata when something changes. Since an IdP (or SP) typically has many partners, static metadata configuration clearly does not scale, and moreover, change management associated with static metadata is difficult at best.

SAML web browser SSO with automated metadata exchange SAML Web Browser SSO With Automated Metadata Exchange.png
SAML web browser SSO with automated metadata exchange

Dynamic metadata exchange

Not surprisingly, metadata sharing processes yearn to be automated. Every metadata file that is statically configured into the SAML application by an administrator incurs technical debt. The accumulation of this debt prevents the SAML deployment from scaling to its potential.

To avoid excessive technical debt, the metadata sharing process must be automated. One approach is to enlist the help of a trusted third party whose responsibility it is to collect, curate, and distribute metadata across the network. Curated metadata is consistently formatted, more likely to be free of vulnerabilities (intentional or otherwise), and therefore safe to use.

In the case of SAML metadata, this trusted third party is called a SAML federation. The community of SAML deployers comprising the federation willingly conform to one or more profiles of SAML to promote interoperability and trust. To that end, federation participants often share a central infrastructure for metadata sharing, which allows the federation to scale to thousands of interoperable SAML deployments.

History

Now let's retrace some of the steps that led to the publication of the SAML V2.0 Metadata specification in March 2005. A turning point occurred on 14 November 2003—our story starts there.

Historical origins

In response to Microsoft Passport, the Liberty Alliance conceived the Identity Federation Framework, a federation technology developed over a three-year period between 2002 and 2004. (The previously mentioned history of SAML provides context for ID-FF.) On 14 November 2003, Liberty contributed ID-FF 1.2 to OASIS. The contribution included a document entitled Liberty Metadata Description and Discovery Specification Version 1.0, [LibertyMeta 1] which included the following design goals:

  1. "whois for SAML federations" (based on the Organization and ContactPerson elements in metadata)
  2. dynamic discovery of metadata (with resolution via DNS and Well-Known Location)
  3. document-level security using XML Signature

As it turns out, all of those goals were preserved in the OASIS SAML V2.0 Metadata Standard described later in this article.

The schema document included with the legacy Liberty ID-FF 1.2 archive is identified as Liberty Metadata Version 1.1 whereas Liberty Metadata Version 1.0 was contributed to OASIS. The apparent contradiction was explained by the schema's author. (Peter Davis, Personal Communication) Between November 2003 (when Version 1.0 was contributed to OASIS) and December 2004 (when Version 1.1 was completed by Liberty), development of the Liberty metadata specification continued in parallel with the OASIS work stream. See the chart below for a visual representation. The arrows in the chart indicate dependencies while the dashed lines indicate equivalencies.

SAML metadata dependencies SAML Metadata Dependency Graph.png
SAML metadata dependencies

Relevant references into the Liberty work stream are given at the end of this article. The original metadata schema contributed to OASIS is listed in its entirety in section 7 of the Liberty Metadata Version 1.0 [LibertyMeta 1] specification. Similarly, the specification for Liberty Metadata Version 1.1 [LibertyMeta 2] includes a listing of the Version 1.1 schema. Both the Version 1.0 schema and the Version 1.1 schema are linked here courtesy of the Internet Archive's Wayback Machine.

Post-November 2003

Over the next thirteen months, from November 2003 to December 2004, the OASIS Security Services (SAML) Technical Committee (SSTC) molded the Liberty metadata specification into what eventually became known as SAML Metadata. During that time, the SSTC generalized the metadata specification to include support for multiple protocols (including non-SAML protocols) but more importantly, the Liberty metadata schema was retrofitted with numerous extension points. Historically, the extensibility of SAML Metadata has had important consequences, as we shall see.

By March 2004, most of the Liberty contribution was incorporated into the OASIS work stream. [SAMLMeta 1] From that point onward, the Liberty and OASIS work streams progressed concurrently (but not independently since the same people were working on both specifications). Between March and July 2004, the fledgling SAML Metadata specification underwent significant churn.

In July 2004, the SSTC issued a public call for comments covering a complete set of SAML V2.0 draft specifications. Included in that specification set was a working draft of a newly forged SAML V2.0 Metadata specification. [SAMLMeta 2]

In retrospect, it appears as though the bulk of the SAML V2.0 Metadata specification was developed between March and July 2004, but clearly the SAML V2.0 Metadata Standard sprung from the loins of the Liberty Alliance, specifically Liberty Metadata Version 1.0. [LibertyMeta 1] Consequently, to understand the origins of SAML Metadata, one must study the provenance of Liberty metadata.

The remaining history of SAML Metadata is mostly OASIS administrative process. After the final Committee Draft was published in November 2004, [SAMLMeta 3] the SSTC began the standardization process in January 2005. Finally, on 5 March 2005, OASIS announced the newly ratified SAML V2.0 Standard.

The V2.0 specification set (see the References section for a complete list) included the final SAML V2.0 Metadata specification. [OS 1] A decade later, in September 2015, OASIS published a revised SAML Metadata specification with errata. [OS 3] As a result, the original metadata specification was deprecated, as were the other documents in the original 2.0 specification set.

During the intervening decade, between 2005 and 2015, the SSTC developed a number of "Post-V2.0" draft specifications. Some of these draft documents became Committee Specifications. A select subset of these Committee Specifications are listed in the References section at the end of this article.

Pre-November 2003

As it turns out, the influence of the Liberty Identity Federation Framework on SAML Metadata predates the contribution of ID-FF 1.2 in November 2003. Apparently the SSTC was dabbling in metadata in parallel with the Liberty Alliance. An excerpt from a draft metadata specification published in September 2003 bears this out:

This document defines metadata that describe the elements and attributes required to use the SAML Web Browser SSO Profiles. Since the Liberty Alliance Web SSO Profiles are directly based on the SAML Web SSO Profiles, the metadata defined in this document borrows extensively from the metadata definitions in the draft Liberty Alliance 1.2 specifications. (Excerpted from "Metadata for SAML 2.0 Web Browser SSO Profiles" [SAMLMeta 4] )

The revision history at the end of that draft document gives the following characterization of itself: "Initial draft based on Draft 07 of SAML 1.1 Metadata specification." In other words, earlier draft documents were published. Indeed, the revision history at the end of the previous draft [SAMLMeta 5] shows a trail of metadata specifications dating back to November 2002.

Following the document trail, the influence of Liberty ID-FF on SAML metadata can be traced to a draft specification published in April 2003. [SAMLMeta 6] This is the first known OASIS document that references Liberty ID-FF, specifically, Liberty Metadata Version 1.0-06, [LibertyMeta 3] an early version of the Liberty Metadata specification about which little is known. It is, however, clear that "Metadata for SAML 1.1 Web Browser Profiles" was intended to be a companion to the SAML V1.1 Standard but of course we know that V1.1 does not specify the use of metadata. See the next section for relevant conjecture.

Two early metadata schema may be of interest:

  1. In June 2002, barely a month after the SSTC completed its work on what was to become the SAML V1.0 Standard, the Shibboleth project developed a metadata schema consisting of <OriginSite> and <DestinationSite> elements. This schema would drive the initial versions of the Shibboleth IdP software.
  2. In February 2003, the SSTC released a draft schema for a metadata specification entitled "Metadata for SAML 1.0 Web Browser Profiles." [SAMLMeta 7] That schema remains a curiosity, however, since the very next version of that document stream (and all subsequent versions) would exhibit the Liberty metadata syntax.

There is no evidence to suggest that either of these early attempts to define a metadata schema had any appreciable effect on the development of the Liberty metadata schema.

Historical summary

We know that metadata standards for SAML V1.0 or SAML V1.1 were never published. We also know that the necessary IPR for Liberty Metadata was not in place until November 2003. With that, we offer the following summary and conjecture:

  1. A draft specification entitled "Metadata for SAML 1.0 Web Browser Profiles" [SAMLMeta 8] was the first known SAML metadata specification. The document is dated 12 November 2002, which is one week after the SAML V1.0 Standard was announced, which is curious. In any case, the metadata syntax used in that document is completely different from what we now know as SAML Metadata. That document was never published and its origins remain a mystery.
  2. A draft specification entitled "Metadata for SAML 1.1 Web Browser Profiles" [SAMLMeta 6] was the first known SAML metadata specification based on Liberty ID-FF. It was completed in April 2003. The title of the draft specification makes it clear that the SSTC knew that SAML V1.1 was coming and moreover SAML metadata was to be included in the SAML V1.1 Standard.
  3. Unfortunately that did not happen since the necessary IPR was not in place when the SAML V1.1 Standard was announced. Indeed, the formal contribution of Liberty ID-FF 1.2 to OASIS occurred two months after the announcement of the SAML V1.1 Standard in September 2003.
  4. In September 2003, less than two weeks after the announcement of the SAML V1.1 Standard, the SSTC set its sights on SAML V2.0 by forking the document stream and renaming the draft document: "Metadata for SAML 2.0 Web Browser Profiles." [SAMLMeta 4]
  5. SAML Metadata came to life between March and July 2004. The SSTC issued a public call for comments that included a candidate SAML Metadata specification. [SAMLMeta 2]
  6. The final SAML Metadata specification [OS 1] was included in the SAML V2.0 Standard specification set announced in March 2005.
  7. For the next 10 years, the specification documents evolved (but the schema remained stable). A specification for SAML V2.0 Metadata with Errata (SAMLMeta20Errata [OS 3] ) was published in September 2015.

Post-V2.0 specifications

As mentioned earlier, the SAML V2.0 Metadata Schema [OS 4] has numerous extension points. This feature led to a proliferation of "Post-V2.0" specifications that extended the standard in several directions. The more popular metadata extensions are listed below for convenience (see the examples for specific use cases):

  1. SAML V2.0 Metadata Extensions for Registration and Publication Information Version 1.0. [CS 1]
  2. SAML V2.0 Metadata Extension for Entity Attributes. [CS 2]
  3. SAML V2.0 Metadata Extensions for Login and Discovery User Interface Version 1.0. [CS 3]
  4. Identity Provider Discovery Service Protocol and Profile. [CS 4]
  5. Service Provider Request Initiation Protocol and Profile Version 1.0. [CS 5]
  6. SAML V2.0 Metadata Profile for Algorithm Support Version 1.0. [CS 6]

An important "Post-V2.0" specification is the SAML V2.0 Metadata Interoperability Profile, [CS 7] which builds on the premise that a formal public key infrastructure (PKI) can be extremely complex and in some cases intractable (it is well known, for example, that browser-facing TLS certificate revocation is broken [Misc 1] ). In essence, the Metadata Interoperability Profile is an attempt to provide a workable key revocation mechanism for SAML federations.

Since its publication in August 2009, the Metadata Interoperability Profile has been a particularly influential document, especially in higher education (see, for example, the certificate-related requirements for deployers [Misc 2] in one large R&E federation). Metadata interoperability plays a key role in a formal implementation profile published by the Kantara Initiative:

Implementations MUST support the interpretation and application of metadata as defined by the SAML V2.0 Metadata Interoperability Profile. It follows that implementations MUST be capable of interoperating (leading to success or failure as dictated by default configuration) with any number of SAML peers for which metadata is available, without additional inputs or separate configuration. [Misc 3]

Indeed, the key feature that distinguishes a scalable SAML implementation (from one that is not) is metadata interoperability.

SAML metadata examples

In this section we give concrete examples of the SAML entity descriptor, the basic unit of policy and interoperability in SAML metadata. Each of the examples includes the following metadata bits:

In the examples below, a particular URI in metadata (such as an entityID or an endpoint location) maps to a responsible party via the URI's domain component:

Note that SAML metadata describes all parties involved in metadata-driven SAML Web Browser SSO except the browser user. (See the SAML V2.0 Profiles [OS 2] specification for more information about SAML web browser SSO.)

Entity metadata

The following code sample illustrates the common technical features of a SAML <md:EntityDescriptor> element:

<md:EntityDescriptorentityID="https://sso.example.info/entity"validUntil="2017-08-30T19:10:29Z"xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"xmlns:mdrpi="urn:oasis:names:tc:SAML:metadata:rpi"xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute"xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><!-- insert ds:Signature element (omitted) --><md:Extensions><mdrpi:RegistrationInforegistrationAuthority="https://registrar.example.net"/><mdrpi:PublicationInfocreationInstant="2017-08-16T19:10:29Z"publisher="https://registrar.example.net"/><mdattr:EntityAttributes><saml:AttributeName="http://registrar.example.net/entity-category"NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"><saml:AttributeValue>https://registrar.example.net/category/self-certified</saml:AttributeValue></saml:Attribute></mdattr:EntityAttributes></md:Extensions><!-- insert one or more concrete instances of the md:RoleDescriptor abstract type (see below) --><md:Organization><md:OrganizationNamexml:lang="en">...</md:OrganizationName><md:OrganizationDisplayNamexml:lang="en">...</md:OrganizationDisplayName><md:OrganizationURLxml:lang="en">https://www.example.info/</md:OrganizationURL></md:Organization><md:ContactPersoncontactType="technical"><md:SurName>SAMLTechnicalSupport</md:SurName><md:EmailAddress>mailto:technical-support@example.info</md:EmailAddress></md:ContactPerson></md:EntityDescriptor>

Note the following details about this general entity descriptor:

The all-important role descriptor has been omitted from this initial example for brevity. The SAML metadata specification defines numerous concrete instances of the md:RoleDescriptor abstract type (section 2.4.1 of SAMLMeta [OS 3] ). The two most important roles are described by the <md:IDPSSODescriptor> element and the <md:SPSSODescriptor> element. Each of these role descriptors is illustrated in the subsections below.

Identity provider metadata

A SAML identity provider manages a Single Sign-On Service endpoint [OS 2] that receives authentication requests from service providers. The entity descriptor for an identity provider in that role contains an <md:IDPSSODescriptor> element, which itself contains at least one <md:SingleSignOnService> endpoint. The following example illustrates two such endpoints:

<md:EntityDescriptorentityID="https://sso.example.org/idp"validUntil="2017-08-30T19:10:29Z"xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"xmlns:mdrpi="urn:oasis:names:tc:SAML:metadata:rpi"xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute"xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui"xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><!-- insert ds:Signature element (omitted) --><md:Extensions><mdrpi:RegistrationInforegistrationAuthority="https://registrar.example.net"/><mdrpi:PublicationInfocreationInstant="2017-08-16T19:10:29Z"publisher="https://registrar.example.net"/><mdattr:EntityAttributes><saml:AttributeName="http://registrar.example.net/entity-category"NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"><saml:AttributeValue>https://registrar.example.net/category/self-certified</saml:AttributeValue></saml:Attribute></mdattr:EntityAttributes></md:Extensions><md:IDPSSODescriptorprotocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"><md:Extensions><mdui:UIInfo><mdui:DisplayNamexml:lang="en">Example.org</mdui:DisplayName><mdui:Descriptionxml:lang="en">TheidentityprovideratExample.org</mdui:Description><mdui:Logoheight="32"width="32"xml:lang="en">https://idp.example.org/myicon.png</mdui:Logo></mdui:UIInfo></md:Extensions><md:KeyDescriptoruse="signing"><ds:KeyInfo>...</ds:KeyInfo></md:KeyDescriptor><md:SingleSignOnServiceBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"Location="https://idp.example.org/SAML2/SSO/Redirect"/><md:SingleSignOnServiceBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"Location="https://idp.example.org/SAML2/SSO/POST"/></md:IDPSSODescriptor><md:Organization><md:OrganizationNamexml:lang="en">Example.orgNon-ProfitOrg</md:OrganizationName><md:OrganizationDisplayNamexml:lang="en">Example.org</md:OrganizationDisplayName><md:OrganizationURLxml:lang="en">https://www.example.org/</md:OrganizationURL></md:Organization><md:ContactPersoncontactType="technical"><md:SurName>SAMLTechnicalSupport</md:SurName><md:EmailAddress>mailto:technical-support@example.org</md:EmailAddress></md:ContactPerson></md:EntityDescriptor>

The content of the <md:IDPSSODescriptor> element describes the Single Sign-On Service at the identity provider. Note the following details about this element:

The values of the md:SingleSignOnService/@Location attributes in identity provider metadata are used by a service provider to route SAML messages, which minimizes the possibility of a rogue identity provider orchestrating a man-in-the-middle attack.

Service provider metadata

A SAML service provider manages an Assertion Consumer Service endpoint [OS 2] that receives authentication assertions from identity providers. The entity descriptor for a service provider in that role contains an <md:SPSSODescriptor> element, which itself contains at least one <md:AssertionConsumerService> endpoint. The following example illustrates such an endpoint:

<md:EntityDescriptorentityID="https://sso.example.com/portal"validUntil="2017-08-30T19:10:29Z"xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"xmlns:mdrpi="urn:oasis:names:tc:SAML:metadata:rpi"xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute"xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui"xmlns:idpdisc="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol"xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><!-- insert ds:Signature element (omitted) --><md:Extensions><mdrpi:RegistrationInforegistrationAuthority="https://registrar.example.net"/><mdrpi:PublicationInfocreationInstant="2017-08-16T19:10:29Z"publisher="https://registrar.example.net"/><mdattr:EntityAttributes><saml:AttributeName="http://registrar.example.net/entity-category"NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"><saml:AttributeValue>https://registrar.example.net/category/self-certified</saml:AttributeValue></saml:Attribute></mdattr:EntityAttributes></md:Extensions><md:SPSSODescriptorWantAssertionsSigned="true"protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"><md:Extensions><mdui:UIInfo><mdui:DisplayNamexml:lang="en">Example.comVendorService</mdui:DisplayName><mdui:InformationURLxml:lang="en">https://service.example.com/about.html</mdui:InformationURL><mdui:PrivacyStatementURLxml:lang="en">https://service.example.com/privacy.html</mdui:PrivacyStatementURL><mdui:Logoheight="32"width="32"xml:lang="en">https://service.example.com/myicon.png</mdui:Logo></mdui:UIInfo><idpdisc:DiscoveryResponseindex="0"Binding="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol"Location="https://service.example.com/SAML2/Login"/></md:Extensions><md:KeyDescriptoruse="encryption"><ds:KeyInfo>...</ds:KeyInfo></md:KeyDescriptor><md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat><md:AssertionConsumerServiceindex="0"Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"Location="https://service.example.com/SAML2/SSO/POST"/><md:AttributeConsumingServiceindex="0"><md:ServiceNamexml:lang="en">Example.comEmployeePortal</md:ServiceName><md:RequestedAttributeisRequired="true"NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.13"FriendlyName="eduPersonUniqueId"/><md:RequestedAttributeNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"Name="urn:oid:0.9.2342.19200300.100.1.3"FriendlyName="mail"/></md:AttributeConsumingService></md:SPSSODescriptor><md:Organization><md:OrganizationNamexml:lang="en">Example.comInc.</md:OrganizationName><md:OrganizationDisplayNamexml:lang="en">Example.com</md:OrganizationDisplayName><md:OrganizationURLxml:lang="en">https://www.example.com/</md:OrganizationURL></md:Organization><md:ContactPersoncontactType="technical"><md:SurName>SAMLTechnicalSupport</md:SurName><md:EmailAddress>mailto:technical-support@example.com</md:EmailAddress></md:ContactPerson></md:EntityDescriptor>

The content of the <md:SPSSODescriptor> element describes the Assertion Consumer Service at the service provider. Note the following details about this element:

The value of the md:AssertionConsumerService/@Location attribute in service provider metadata is used by an identity provider to route SAML messages, which minimizes the possibility of a rogue service provider orchestrating a man-in-the-middle attack.

Metadata-driven SAML web browser

The following SAML protocol flow is intended to illustrate the use of metadata at various stages of SAML web browser SSO. (See the SAML V2.0 Profiles [OS 2] specification for more information about SAML web browser SSO.)

SAML web browser SSO with discovery and login SAML Web Browser SSO.png
SAML web browser SSO with discovery and login

Trusted SAML metadata ensures a secure transaction between a SAML identity provider (IdP) and a SAML service provider (SP). Before metadata, trust information was encoded into the implementation in a proprietary manner. Now the sharing of trust information is facilitated by standard metadata. The SAML 2.0 Metadata Standard [OS 3] provides a well-defined, interoperable metadata format that entities can use to bootstrap the trust process.

The following sequence illustrates the use of SAML metadata to drive the SAML protocol flow.

1. Request the target resource at the SP

A browser user requests a web application resource protected by a SAML service provider:

https://sp.example.com/myresource

If a valid security context for the user principal already exists at the service provider, skip steps 2–13.

2. Redirect to the Discovery Service

Before the service provider can initiate the SAML protocol flow at step 6, the browser user's preferred identity provider must be known. There are numerous ways to do this. For illustration purposes, the service provider will use a local Discovery Service that conforms to the Identity Provider Discovery Service Protocol and Profile. [CS 4]

The service provider redirects the browser user to the Discovery Service:

302 RedirectLocation: https://ds.example.com/idpdisc?entityID=https%3A%2F%2Fsso.example.org%2Fportal

Note that the SP entityID is included in the redirect URL as specified by the discovery protocol.

3. Request the Discovery Service

The browser user requests the Discovery Service by virtue of the redirect:

GET/idpdisc?entityID=https%3A%2F%2Fsso.example.org%2FportalHTTP/1.1Host:ds.example.com

Trusted service providers in metadata
How does the Discovery Service know the service provider is authentic and not some evil impostor trying to learn the user's identity provider for nefarious purposes?

The Discovery Service consults its list of trusted service providers in metadata before issuing a response.

(Discover the user's preferred IdP)

The Discovery Service discovers the browser user's preferred identity provider by unspecified means.

User interface elements in metadata
How does the Discovery Service construct an appropriate discovery interface?

The Discovery Service consults its trusted metadata store to determine an appropriate list of trusted identity providers to present to the browser user. The <mdui:UIInfo> user interface elements in metadata may be used to construct a dynamic discovery interface.

4. Redirect to the Discovery Response endpoint at the SP

The Discovery Service now redirects the browser user to a Discovery Response endpoint at the service provider:

302 RedirectLocation: https://sp.example.com/SAML2/Login?entityID=https%3A%2F%2Fsso.example.org%2Fidp

Note that the IdP entityID is included in the redirect URL as specified by the discovery protocol.

Trusted endpoint locations in metadata
How does the Discovery Service know where to send the user with the IdP entityID?

The Discovery Service looks up a pre-arranged Discovery Response endpoint location of the trusted service provider in metadata.

5. Request the Discovery Response endpoint at the SP

The browser user requests the Discovery Response endpoint at the service provider by virtue of the redirect:

GET/SAML2/Login?entityID=https%3A%2F%2Fsso.example.org%2FidpHTTP/1.1Host:sp.example.com

The Discovery Response endpoint at the service provider conforms to the Identity Provider Discovery Service Protocol and Profile. [CS 4]

Trusted identity providers in metadata

How does the service provider know that the identity provider given by the entityID in the discovery protocol URL is authentic and not some evil identity provider trying to phish the user's password?

The service provider consults its list of trusted identity providers in metadata before issuing a SAML Request at the next step. If the service provider can not determine if the identity provider in question is trusted, the browser user must not be redirected to the IdP. This is why it is imperative that IdP metadata must be trusted metadata.

6. Redirect to SSO Service at the IdP

The service provider generates a relevant <samlp:AuthnRequest> element, encodes a SAML Request in an URL query string, and then redirects the browser user to the Single Sign-On Service at the identity provider:

302 RedirectLocation: https://idp.example.org/SAML2/SSO/Redirect?SAMLRequest=request&RelayState=token

For an outline how to construct the query string, see the corresponding SAML protocol flow in the SAML 2.0 article. Refer to SAMLCore [OS 6] for details.

Trusted endpoint locations in metadata
How does the service provider know where to send the user with the SAML Request?

The service provider looks up a pre-arranged endpoint location of the trusted identity provider in metadata.

7. Request the SSO Service at the IdP

The browser user requests the Single Sign-On Service endpoint at the identity provider by virtue of the redirect:

GET/SAML2/SSO/Redirect?SAMLRequest=request&RelayState=tokenHTTP/1.1Host:idp.example.org

Trusted service providers in metadata
How does the identity provider know the service provider is authentic and not some evil service provider trying to harvest personally identifiable information regarding the user?

The identity provider consults its list of trusted service providers in metadata before issuing a response.

8. Respond with the login page

The identity provider returns a login page to the user's browser. The login page contains an HTML form similar to the following:

<formmethod="post"action="https://idp.example.com/login-response"...>     Username:<br><inputtype="text"name="username"><br>     Password:<br><inputtype="password"name="password">     ...     <inputtype="submit"value="Submit"/></form>

User interface elements in metadata
To reassure the browser user, the IdP personalizes the login page using the <mdui:UIInfo> user interface elements in metadata.

9. Submit the login form

The browser user submits the HTML form to the identity provider:

POST/login-responseHTTP/1.1Host:idp.example.comContent-Type:application/x-www-form-urlencodedContent-Length:nnnusername=username&password=password

(Issue a SAML Assertion for the user)

At this point, the identity provider knows the identity of the user principal and so the identity provider constructs a SAML Assertion on behalf of the user principal. For a concrete example of such an Assertion, see the corresponding SAML protocol flow in the SAML 2.0 article. As always, refer to SAMLCore [OS 6] for details.

The <saml:NameID> element in the SAML Assertion encodes an identifier for the user principal. In this case, the identity provider includes a SAML2 Transient NameID (SAMLCore [OS 6] ) in the SAML Assertion.

NameID format in metadata
Why does the identity provider use a Transient NameID format in the SAML Assertion (as opposed to some other format)?

Assuming the <samlp:AuthnRequest> element issued by the service provider does not request otherwise, a metadata-aware IdP will consult the <md:NameIDFormat> elements in metadata (if any) to determine the NameID format.

The identity provider includes two user attributes in the SAML Assertion: eduPersonUniqueId and mail.

Requested attributes in metadata
Why does the identity provider include attributes eduPersonUniqueId and mail in the assertion and not some other attributes?

A metadata-aware IdP will consult the <md:RequestedAttribute> elements in metadata (if any) to learn the attribute requirements of the service provider.

Operationally, the identity provider digitally signs and encrypts the SAML Assertion, wraps the Assertion in a SAML Response, and then signs the Response object as well. Typically the identity provider signs the Response alone but in this case both the Assertion and the Response are digitally signed.

WantAssertionsSigned attribute in metadata
How does the identity provider know that the service provider wants the Assertion itself to be digitally signed?

At run time, the identity provider observes that the WantAssertionsSigned XML attribute in metadata is set to true.

Trusted encryption certificate in metadata
How does the identity provider encrypt the SAML Assertion so that the service provider (and only the service provider) can decrypt it?

At run time, the identity provider uses the service provider's encryption certificate in metadata to encrypt the Assertion.

10. Respond with the SAML Response page

The identity provider returns an XHTML document to the user's browser. The document contains a SAML Response encoded in an XHTML form as follows:

<formmethod="post"action="https://sp.example.com/SAML2/SSO/POST"...><inputtype="hidden"name="SAMLResponse"value="response"/><inputtype="hidden"name="RelayState"value="token"/>     ...     <inputtype="submit"value="Submit"/></form>

Trusted endpoint locations in metadata
How does the identity provider know where to send the user with the SAML Response?

The identity provider looks up a pre-arranged endpoint location of the trusted service provider in metadata.

11. Request the Assertion Consumer Service at the SP

The XHTML form is automatically submitted by the browser (due to a small bit of JavaScript on the page):

POST/SAML2/SSO/POSTHTTP/1.1Host:sp.example.comContent-Type:application/x-www-form-urlencodedContent-Length:nnnSAMLResponse=response&RelayState=token

Trusted signing certificate in metadata
How does the service provider know that the SAML Response came from a trusted identity provider?

The service provider verifies the digital signature on the Response using the public key of the identity provider in metadata. After decrypting the signature on the Assertion object, the service provider verifies the signature on the Assertion as well.

12. Redirect to the target resource

The service provider creates a security context for the user principal and redirects the browser user to the original web application resource:

302 RedirectLocation: https://sp.example.com/myresource

13. Request the target resource at the SP again

Finally the browser user requests the target resource at the service provider by virtue of the redirect:

https://sp.example.com/myresource

14. Respond with requested resource

Since a security context exists, the service provider returns the resource to the browser user agent as requested.

See also

Related Research Articles

Single sign-on (SSO) is an authentication scheme that allows a user to log in with a single ID to any of several related, yet independent, software systems.

Identity management (IdM), also known as identity and access management, is a framework of policies and technologies to ensure that the right users have the appropriate access to technology resources. IdM systems fall under the overarching umbrellas of IT security and data management. Identity and access management systems not only identify, authenticate, and control access for individuals who will be utilizing IT resources but also the hardware and applications employees need to access.

Security Assertion Markup Language is an open standard for exchanging authentication and authorization data between parties, in particular, between an identity provider and a service provider. SAML is an XML-based markup language for security assertions. SAML is also:

<span class="mw-page-title-main">XBRL</span> Exchange format for business information

XBRL is a freely available and global framework for exchanging business information. XBRL allows the expression of semantics commonly required in business reporting. The standard was originally based on XML, but now additionally supports reports in JSON and CSV formats, as well as the original XML-based syntax. XBRL is also increasingly used in its Inline XBRL variant, which embeds XBRL tags into an HTML document. One common use of XBRL is the exchange of financial information, such as in a company's annual financial report. The XBRL standard is developed and published by XBRL International, Inc. (XII).

A federated identity in information technology is the means of linking a person's electronic identity and attributes, stored across multiple distinct identity management systems.

<span class="mw-page-title-main">Shibboleth (software)</span> Internet identity system

Shibboleth is a single sign-on log-in system for computer networks and the Internet. It allows people to sign in using just one identity to various systems run by federations of different organizations or institutions. The federations are often universities or public service organizations.

The eXtensible Access Control Markup Language (XACML) is an XML-based standard markup language for specifying access control policies. The standard, published by OASIS, defines a declarative fine-grained, attribute-based access control policy language, an architecture, and a processing model describing how to evaluate access requests according to the rules defined in policies.

Catalogue Service for the Web (CSW), sometimes seen as Catalogue Service - Web, is a standard for exposing a catalogue of geospatial records in XML on the Internet. The catalogue is made up of records that describe geospatial data, geospatial services, and related resources.

The Web Application Description Language (WADL) is a machine-readable XML description of HTTP-based web services. WADL models the resources provided by a service and the relationships between them. WADL is intended to simplify the reuse of web services that are based on the existing HTTP architecture of the Web. It is platform and language independent and aims to promote reuse of applications beyond the basic use in a web browser. WADL was submitted to the World Wide Web Consortium by Sun Microsystems on 31 August 2009, but the consortium has no current plans to standardize it. WADL is the REST equivalent of SOAP's Web Services Description Language (WSDL), which can also be used to describe REST web services.

Security Assertion Markup Language (SAML) is an XML standard for exchanging authentication and authorization data between security domains. SAML is a product of the OASIS (organization) Security Services Technical Committee.

Security Assertion Markup Language 2.0 (SAML 2.0) is a version of the SAML standard for exchanging authentication and authorization identities between security domains. SAML 2.0 is an XML-based protocol that uses security tokens containing assertions to pass information about a principal between a SAML authority, named an Identity Provider, and a SAML consumer, named a Service Provider. SAML 2.0 enables web-based, cross-domain single sign-on (SSO), which helps reduce the administrative overhead of distributing multiple authentication tokens to the user. SAML 2.0 was ratified as an OASIS Standard in March 2005, replacing SAML 1.1. The critical aspects of SAML 2.0 are covered in detail in the official documents SAMLCore, SAMLBind, SAMLProf, and SAMLMeta.

XLIFF is an XML-based bitext format created to standardize the way localizable data are passed between and among tools during a localization process and a common format for CAT tool exchange. The XLIFF Technical Committee (TC) first convened at OASIS in December 2001, but the first fully ratified version of XLIFF appeared as XLIFF Version 1.2 in February 2008. Its current specification is v2.1 released on 2018-02-13, which is backwards compatible with v2.0 released on 2014-08-05.

WS-Security Policy is a web services specification, created by IBM and 12 co-authors, that has become an OASIS standard as of version 1.2. It extends the fundamental security protocols specified by the WS-Security, WS-Trust and WS-Secure Conversation by offering mechanisms to represent the capabilities and requirements of web services as policies. Security policy assertions are based on the WS-Policy framework.

<span class="mw-page-title-main">Information card</span> Personal digital identity for online use

An information card is a personal digital identity that people can use online, and the key component of an identity metasystem. Visually, each i-card has a card-shaped picture and a card name associated with it that enable people to organize their digital identities and to easily select one they want to use for any given interaction. The information card metaphor has been implemented by identity selectors like Windows CardSpace, DigitalMe or Higgins Identity Selector.

The extensible resource descriptor sequence (XRDS) is an XML-based file format that provides a list of services.

An identity provider is a system entity that creates, maintains, and manages identity information for principals and also provides authentication services to relying applications within a federation or distributed network.

An Extensible Resource Identifier (XRI) is a scheme and resolution protocol for abstract identifiers compatible with Uniform Resource Identifiers (URI) and Internationalized Resource Identifiers (IRI), developed by the XRI Technical Committee at OASIS. The goal of XRI was a standard syntax and discovery format for abstract, structured identifiers that are domain-, location-, application-, and transport-independent, so they can be shared across any number of domains, directories, and interaction protocols.

Security Assertion Markup Language (SAML) is a set of specifications that encompasses the XML-format for security tokens containing assertions to pass information about a user and protocols and profiles to implement authentication and authorization scenarios. This article has a focus on software and services in the category of identity management infrastructure, which enable building Web-SSO solutions using the SAML protocol in an interoperable fashion. Software and services that are only SAML-enabled do not go here.

A SAML identity provider is a system entity that issues authentication assertions in conjunction with a single sign-on (SSO) profile of the Security Assertion Markup Language (SAML).

A SAML service provider is a system entity that receives and accepts authentication assertions in conjunction with a single sign-on (SSO) profile of the Security Assertion Markup Language (SAML).

References

Liberty metadata specifications

Note: The Liberty metadata schema are listed verbatim in the specification documents listed below. Since the direct link to the Version 1.1 XSD document on the Liberty web site is broken, a copy of the XSD document for Liberty Metadata Version 1.1 has been uploaded to the web. That document is also included in the legacy Liberty ID-FF 1.2 archive.

  1. 1 2 3 P. Davis (Editor). Liberty Metadata Description and Discovery Specification. Version 1.0, 12 November 2003. Document identifier: liberty-metadata-v1.0. http://www.projectliberty.org/liberty/content/download/2024/13989/file/liberty-metadata-v1.0.pdf
  2. ↑ P. Davis (Editor). Liberty Metadata Description and Discovery Specification. Version 1.1, 14 December 2004. Document identifier: liberty-metadata-v1.1. http://www.projectliberty.org/liberty/content/download/1224/7973/file/liberty-metadata-v1.1.pdf
  3. ↑ P. Davis (Editor). Liberty Metadata Description and Discovery Specification. Draft Version 1.0-06, 13 April 2003.

SAML metadata specifications pre-2005

  1. ↑ J. Moreh and S. Cantor (Editors). Metadata for SAML 2.0. Working Draft 01, 15 March 2004. Document ID sstc-saml-Metadata-2.0-draft-01.
  2. 1 2 J. Moreh et al. (editors). Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0. Last-Call Working Draft 08, 13 July 2004. Document ID sstc-saml-metadata-2.0-draft-08. http://xml.coverpages.org/SSTC-SAMLMetadataV20Draft08-7750.pdf (https://drive.google.com/file/d/0B7vociYknAbCelh1TmhjRVBZdmc/view?usp=sharing)
  3. ↑ J. Moreh et al. (editors). Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0. Committee Draft 02e, 11 November 2004. Document ID sstc-saml-metadata-2.0-cd-02e. https://www.oasis-open.org/committees/download.php/10037/sstc-saml-metadata-2.0-cd-02e.pdf
  4. 1 2 J. Moreh (Editor). Metadata for SAML 2.0 Web Browser SSO Profiles. Working Draft 00, 15 September 2003. Document ID sstc-saml-metadata-2.0-draft-00. https://www.oasis-open.org/committees/download.php/4538/sstc-saml-metadata-2.0-draft-00.pdf
  5. ↑ J. Moreh et al. (editors). Metadata for SAML 1.1 Web Browser Profiles. Working Draft 07, 23 July 2003. Document ID sstc-saml-meta-data-draft-07. https://www.oasis-open.org/committees/download.php/3002/draft-sstc-saml-meta-data-07.doc (https://drive.google.com/file/d/0B7vociYknAbCRUJ6UzNuTnNiOW8/view?usp=sharing)
  6. 1 2 J. Moreh et al. (editors). Metadata for SAML 1.1 Web Browser Profiles. Working Draft 02, 23 April 2003. Document ID draft-sstc-saml-meta-data-02. https://www.oasis-open.org/committees/download.php/1735/draft-sstc-saml-meta-data-02.doc (https://drive.google.com/file/d/0B7vociYknAbCYTFRYVdWcGx1Qlk/view?usp=sharing)
  7. ↑ P. Mishra et al. (editors). Metadata for SAML 1.0 Web Browser Profiles. Working Draft 01, 1 February 2003. Document ID draft-sstc-saml-meta-data-01. http://www.oasis-open.org/committees/security/docs/draft-sstc-saml-meta-data-01.pdf (https://drive.google.com/file/d/0B7vociYknAbCLTJWY0p3bXFYS1E/view?usp=sharing) https://www.oasis-open.org/committees/security/docs/draft-sstc-schema-meta-data-01.xsd
  8. ↑ P. Mishra (editor). Metadata for SAML 1.0 Web Browser Profiles. Working Draft 00, 12 November 2002. Document ID draft-sstc-saml-meta-data-00. http://www.oasis-open.org/committees/security/docs/draft-sstc-saml-meta-data-00.pdf (https://drive.google.com/file/d/0B7vociYknAbCNEZIaDVwaWhXLUU/view?usp=sharing)

SAML standards

The original SAML V2.0 standards published in March 2005 have been deprecated in favor of the revised specifications with errata listed further below.

Except for historical references to the original SAML V2.0 Metadata Standard, the following footnotes point to SAML V2.0 specifications with errata. The latter specifications are fully inclusive of all errata approved by the OASIS Security Services (SAML) Technical Committee since the SAML V2.0 standards were published in March 2005. Please refer to the OASIS SAML Wiki for the most recent version of any SAML specification.

  1. 1 2 3 S. Cantor et al. Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS Standard, March 2005. Document ID saml-metadata-2.0-os http://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf
  2. 1 2 3 4 5 J. Hughes et al. Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0 – Errata Composite. Working Draft 07, 8 September 2015. Document ID sstc-saml-profiles-errata-2.0-wd-07 https://www.oasis-open.org/committees/download.php/56782/sstc-saml-profiles-errata-2.0-wd-07.pdf
  3. 1 2 3 4 5 6 S. Cantor et al. Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0 – Errata Composite. Working Draft 05, 8 September 2015. Document ID sstc-saml-metadata-errata-2.0-wd-05 https://www.oasis-open.org/committees/download.php/56785/sstc-saml-metadata-errata-2.0-wd-05.pdf
  4. ↑ Metadata Schema for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS Standard, March 2005. Document ID saml-schema-metadata-2.0 http://docs.oasis-open.org/security/saml/v2.0/saml-schema-metadata-2.0.xsd
  5. 1 2 S. Cantor et al. Bindings for the OASIS Security Assertion Markup Language (SAML) V2.0 – Errata Composite. Working Draft 06, 8 September 2015. Document ID sstc-saml-bindings-errata-2.0-wd-06 https://www.oasis-open.org/committees/download.php/56779/sstc-saml-bindings-errata-2.0-wd-06.pdf
  6. 1 2 3 S. Cantor et al. Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0 – Errata Composite. Working Draft 07, 8 September 2015. Document ID sstc-saml-core-errata-2.0-wd-07 http://www.oasis-open.org/committees/download.php/56776/sstc-saml-core-errata-2.0-wd-07.pdf

Committee specifications post-2005

This is a small subset of the "Post-V2.0" committee specifications published by the OASIS Security Services (SAML) Technical Committee. Please refer to the OASIS SAML Wiki for the most recent version of any SAML specification.

  1. 1 2 3 4 SAML V2.0 Metadata Extensions for Registration and Publication Information Version 1.0. OASIS Security Services (SAML) Technical Committee Specification 01, 03 April 2012. https://wiki.oasis-open.org/security/SAML2MetadataDRI
  2. 1 2 SAML V2.0 Metadata Extension for Entity Attributes. OASIS Security Services (SAML) Technical Committee Specification 01, 4 August 2009. https://wiki.oasis-open.org/security/SAML2MetadataAttr
  3. 1 2 3 SAML V2.0 Metadata Extensions for Login and Discovery User Interface Version 1.0. OASIS Security Services (SAML) Technical Committee Specification 01, 03 April 2012. https://wiki.oasis-open.org/security/SAML2MetadataUI
  4. 1 2 3 4 Identity Provider Discovery Service Protocol and Profile. OASIS Security Services (SAML) Technical Committee Specification 01, 27 March 2008. https://wiki.oasis-open.org/security/IdpDiscoSvcProtonProfile
  5. ↑ Service Provider Request Initiation Protocol and Profile Version 1.0. OASIS Security Services (SAML) Technical Committee Specification 01, 5 November 2010. https://wiki.oasis-open.org/security/RequestInitProtProf
  6. ↑ SAML V2.0 Metadata Profile for Algorithm Support Version 1.0. OASIS Security Services (SAML) Technical Committee Specification 01, 21 February 2011. https://wiki.oasis-open.org/security/SAML2MetadataAlgSupport
  7. ↑ SAML V2.0 Metadata Interoperability Profile. OASIS Security Services (SAML) Technical Committee Specification 01, 4 August 2009. https://wiki.oasis-open.org/security/SAML2MetadataIOP

Miscellaneous

  1. ↑ Hanno Böck. The Problem with OCSP Stapling and Must Staple and why Certificate Revocation is still broken. 19 May 2017. https://blog.hboeck.de/archives/886-The-Problem-with-OCSP-Stapling-and-Must-Staple-and-why-Certificate-Revocation-is-still-broken.html
  2. ↑ SAML Certificates in Federation Metadata. InCommon Federation. https://spaces.internet2.edu/x/boY0
  3. ↑ SAML V2.0 Implementation Profile for Federation Interoperability. Kantara Initiative. https://kantarainitiative.github.io/SAMLprofiles/fedinterop.html
This page is based on this Wikipedia article
Text is available under the CC BY-SA 4.0 license; additional terms may apply.
Images, videos and audio are available under their respective licenses.