SAML metadata: the XML that decides whether SSO works

SAML integrations are configured by exchanging metadata: an XML document that describes an entity's endpoints and keys. When a SAML login fails and the protocol trace looks fine, the cause is usually metadata — a stale certificate, a mismatched entity ID, or an endpoint that changed.

This article explains what is in SAML metadata and how to keep it correct.

What metadata contains

Metadata is one or more EntityDescriptor elements, each with a unique entityID. Inside, role descriptors describe what the entity can do:

• IDPSSODescriptor — this entity is an identity provider.
• SPSSODescriptor — this entity is a service provider.

The interesting fields:

Everything a SAML integration needs from the other party is here — which is why "upload the metadata" is the usual setup step.

URL or file

Metadata is distributed in two ways:

• A URL the other side fetches, often /api/saml/metadata?application=... on the identity provider. Convenient, but it puts availability and refresh behavior on the integration.
• A file uploaded once. Stable, but it goes stale the moment certificates rotate.

Many products accept both. If both sides support a URL, prefer it for the IdP side and be explicit about how often the SP refreshes.

The certificate problem

The signing certificate is the part that expires — and the part that breaks everything when it does.

What happens without planning:

1. The IdP rotates its signing certificate.
2. The SP still has the old one.
3. Every login fails signature validation.
4. Support sees "invalid signature" and starts guessing.

How to avoid it:

• Publish both keys during rotation. Metadata can carry more than one KeyDescriptor. The IdP publishes old and new, both sides keep working, then the old one is removed after the SP has refreshed.
• Know the expiry dates. Put certificate expiry on a calendar with alerts well ahead, and check them during quarterly reviews.
• Refresh metadata deliberately. If the SP caches metadata, document the refresh interval and how to force it.
• Test after every rotation with a real login, not just a metadata fetch.

Casdoor publishes the metadata per application, including the SAML endpoints and certificate, and supports the standard role descriptors the SP needs.

Entity ID mismatches

The second most common failure is the entity ID. Rules of thumb:

• The entity ID is an opaque string; it does not have to be a URL, but most products use one.
• It must match exactly — trailing slashes count.
• The SP's entity ID and the IdP's audience restriction are the same value; if they differ, the SP rejects the assertion with an audience error.

When debugging, print both values side by side before touching anything else.

ACS URL and binding mismatches

The AssertionConsumerService entry includes a URL and a binding (HTTP-POST or HTTP-Redirect). A common broken setup:

• The SP advertises an ACS URL with a path the IdP does not use.
• The IdP is configured to POST, but the SP expects the redirect binding.
• Multiple ACS endpoints exist, and the wrong index is chosen.

Check the binding and URL against the SP's documentation, and make sure the IdP sends to the one that expects the response.

A metadata checklist

1. Entity IDs match exactly on both sides.
2. The signing certificate is current and the expiry is tracked.
3. The SSO URL and ACS URL match the deployment (no staging URLs in production).
4. The binding matches what the SP expects.
5. Single logout is configured if you promise it.
6. Both sides have refreshed metadata after any change.

How Casdoor exposes metadata

Casdoor publishes metadata per application:

<casdoor-host>/api/saml/metadata?application=admin/<application-name>

The admin console's SAML tab has a Copy SAML metadata URL button, and opening the URL downloads the XML. That document is what you upload to the service provider — including the signing certificate and the SingleLogoutService endpoint.

Related reading: what SAML is, SAML assertions and set up Casdoor as a SAML IdP.