SAML Metadata Exchange and Trust Establishment

In Security Assertion Markup Language (SAML), trust is not a configuration setting; it is a cryptographic state derived from the exchange of metadata. Unlike OAuth 2.0, which often relies on dynamic discovery via OIDC Discovery endpoints or implicit trust in issuer URLs, SAML requires an explicit, machine-readable description of the entity’s capabilities and, crucially, its public keys. This document details the mechanism by which Service Providers (SPs) and Identity Providers (IdPs) establish trust through XML Metadata Documents (MD), focusing on the Entity Descriptor structure, certificate rollover, and refresh protocols.

The Entity Descriptor: A Container for Trust Anchors

According to the SAML Metadata specification, the <md:EntityDescriptor> is the primary XML container used to declare an entity's identity and cryptographic materials. At the heart of SAML metadata is the <md:EntityDescriptor> element. This XML container serves two purposes: declaring the entity’s identity (via entityID) and providing the cryptographic materials necessary to validate its assertions. Without the metadata, an SP cannot distinguish a valid SAML assertion from a forgery because it lacks the public key required to verify the digital signature.

The critical component within the Entity Descriptor is the <md:KeyDescriptor>. This element wraps the <ds:KeyInfo> block, which typically contains an <ds:X509Data> block holding the X.509 certificate. The mechanism of trust establishment begins here: the SP parses the metadata XML, extracts the Base64-encoded certificate from the X.509Data, and converts it into a public key object. This key becomes the trust anchor for all subsequent signature validations.

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                     entityID="https://idp.example.com">
  <md:IDPSSODescriptor ...>
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>
            MIIDXTCCAkWgAwIBAgIJAJC1HiIAZAiUMA0GCSqGSIb3Q...
          </ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
  </md:IDPSSODescriptor>
</md:EntityDescriptor>

The use attribute distinguishes between keys used for signing assertions (signing) and keys used for encrypting assertions (encryption). An IdP may have separate key pairs for these purposes, or a single key may serve both roles. The SP must parse both descriptors if it intends to receive encrypted assertions, ensuring it selects the correct key for the intended operation.

Trust Establishment Workflow

Per the SAML Metadata specification and core profiles, trust establishment in SAML is a pre-flight operation. Before any authentication request is sent, the SP must obtain and process the IdP’s metadata. This process involves three distinct steps: retrieval, parsing, and caching.

First, the SP retrieves the metadata XML from a known URL, typically provided during manual integration or via a federation hub. Second, the SP’s SAML library parses the XML. It validates the XML structure against the SAML Metadata schema (XSD) to ensure integrity of the description itself. Third, and most importantly, the library extracts the public key from the <KeyDescriptor> and stores it in memory or a secure cache.

When the IdP later returns a SAML Response signed with its private key, the SP uses the cached public key to verify the XML Digital Signature. If the signature matches, the SP trusts that the assertion originated from the IdP and has not been tampered with. If the metadata has not been updated since a key rollover, the SP will use an expired or revoked key, leading to signature validation failures. This highlights why metadata freshness is not just a convenience but a security requirement.

Certificate Rollover and KeyDescriptor Management

Certificates expire. When an IdP’s signing certificate approaches its expiration date, it must perform a certificate rollover. In SAML, this is managed through the <md:KeyDescriptor> element. A well-behaved IdP will update its metadata file to include the new certificate while optionally retaining the old certificate for a transition period.

Handling this transition depends on the SP’s implementation, as this is not strictly mandated by the SAML specifications. Some SPs enforce a "strict" policy: they only accept signatures from the most recently issued certificate. Others support a "grace period" where they accept signatures from any certificate listed in the metadata, regardless of its expiration date, provided the signature was valid at the time of issuance. However, relying on grace periods is risky; if an old key is compromised, the SP must immediately revoke it from its local cache.

The <KeyDescriptor> also supports the keyInfo element’s <ds:X509Certificate> chain. In complex trust environments, the metadata may include the full certificate chain (root CA, intermediate CA, and leaf certificate). The SP must validate this chain against its local trust store of root certificates. This ensures that the public key extracted from the metadata is not only valid but also issued by a trusted Certificate Authority.

Automated Metadata Refresh

Manual metadata exchange is error-prone. SAML supports automated metadata refresh via HTTP GET or POST requests to the metadata URL. The <md:IDPSSODescriptor> and <md:SPSSODescriptor> elements contain <md:SingleSignOnService> and <md:AssertionConsumerService> locations, but the metadata URL itself is often a separate endpoint defined by the federation agreement.

The refresh mechanism relies on caching. To avoid network latency on every authentication request, the SP caches the metadata document. The cache lifetime is typically governed by the validUntil attribute in the <md:EntityDescriptor> element. This attribute specifies the exact date and time after which the metadata is considered invalid, as specified in the OASIS SAML Metadata specification.

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                     entityID="https://idp.example.com"
                     validUntil="2025-12-31T23:59:59Z">
  ...
</md:EntityDescriptor>

When the validUntil time approaches, the SP should initiate a background refresh. If the refresh fails, the SP must decide whether to continue using the stale metadata (risking trust issues if keys have changed) or reject authentication attempts. Best practice is to refresh proactively, e.g., when 80% of the validity period has elapsed.

Additionally, the <md:ContactPerson> element provides administrative contact information for reporting issues, but it does not participate in the cryptographic trust mechanism. The trust mechanism is strictly bound to the <KeyDescriptor> content and its validation against the trust store.

Conclusion

SAML metadata exchange is the foundation of trust in SAML-based federations. The <md:EntityDescriptor> acts as a distributed trust anchor, distributing public keys that allow SPs to verify IdP signatures. Trust is established by parsing this XML, extracting the X.509 certificate, and caching it. Certificate rollovers require careful management of the <KeyDescriptor> elements to ensure continuous service, and automated refresh mechanisms based on validUntil timestamps ensure that stale keys do not compromise security. For identity engineers, understanding this XML structure and the lifecycle of the metadata document is essential for building reliable, secure SAML integrations.