SAML Metadata Operations Guide

📥 Importing Metadata

Define how to import and automate it to avoid config drift or expired metadata.

Basics

✅ Enable signature verification when metadata is signed.
✅ Schedule automatic imports to reduce drift between IdP and SP.
✅ Monitor the download URL for changes or expiration.

🔐 Signed Metadata Verification

The OASIS metadata spec recommends verifying signed metadata to establish trust.

What to check

Verify metadata with a separately trusted publisher key. Do not trust a document solely through keys contained within it.
Ensure entityID is unique and not mixed with unintended entities.
Check KeyDescriptor use; omission allows both signing and encryption.
Keep the download URL stable and validate signatures regularly to detect tampering.

🔁 Rotation and Notifications

Plan the steps for certificate or endpoint changes to avoid outages.

Operational points

📌 Share the rotation schedule and test in non-production first.
📌 Run old and new certificates in parallel with a grace period.
📌 Send notifications via email and metadata updates to ensure everyone is informed.

📄 Metadata Structure Basics

Knowing the core elements helps avoid configuration gaps.

Key elements

EntityDescriptor: Top-level element representing the IdP or SP.
KeyDescriptor: Includes signing/encryption certs (use="signing"/"encryption").
SingleSignOnService: IdP login endpoint.
AssertionConsumerService: SP endpoint to receive SAMLResponse.

Best practices

Certificate expiry behavior depends on the trust model and product. Monitor metadata validUntil, refresh timing and key rollover separately.
Double-check endpoint URLs (protocol, typos).
If generating metadata, ensure it conforms to the schema.

📝 Sample IdP / SP Metadata Checks

Keep these checkpoints in mind to troubleshoot faster. Samples below are minimal examples.

Checklist

🧭 EntityID matches the expected value (URL vs URN styles).
🧭 SingleSignOnService / AssertionConsumerService URLs and Bindings are correct.
🧭 KeyDescriptor contains the right signing/encryption certificates.

Minimal SP metadata example

Structural example only: MIIC... placeholders are not certificates and cannot be imported unchanged. Replace them with real Base64 certificate data.

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://sp.example.com/metadata">
  <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data><ds:X509Certificate>MIIC...sign...</ds:X509Certificate></ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:KeyDescriptor use="encryption">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data><ds:X509Certificate>MIIC...enc...</ds:X509Certificate></ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://sp.example.com/acs" index="0" />
  </md:SPSSODescriptor>
</md:EntityDescriptor>

Minimal IdP metadata example

Structural example only. Replace placeholder certificates, entityID and endpoints with the actual IdP configuration before validation.

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://idp.example.com/metadata">
  <md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data><ds:X509Certificate>MIIC...idp-sign...</ds:X509Certificate></ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp.example.com/sso" />
  </md:IDPSSODescriptor>
</md:EntityDescriptor>

Specifications and related guides

OASIS SAML metadata / OASIS Metadata Interoperability Profile
Related SAML guide