Category: Federation & SSO

Federation Metadata

Also known as: Federation Metadata Document, SAML Metadata

Simply put

Federation metadata is a standardized file, typically formatted in XML, that describes an entity such as an identity provider or a service provider participating in a federated identity setup. It acts as a shared configuration document so that the systems in a federation can discover and trust each other without manual, error-prone setup. Products like Microsoft Entra ID and AD FS publish this document for the services and partners that accept or issue their tokens.

Formal definition

Federation metadata is a structured document, most commonly an XML file, that describes a single entity within a federated identity environment (for example a SAML 2.0 identity provider or service provider). Depending on the standard and profile, it typically conveys the entity identifier, service endpoints (such as SSO and endpoint URLs), supported bindings, and the signing/encryption keys used to establish trust between federation partners. Providers such as Microsoft Entra ID publish a federation metadata document for services that accept their tokens, and platforms like AD FS expose the metadata at a service endpoint (for example the FederationMetadata.xml endpoint) so relying parties can be configured. Some publishers support conditional retrieval mechanisms (for example ETag comparison) to avoid re-fetching unchanged metadata. The specific fields, format, and refresh behavior vary by standard, vendor, and deployment configuration; this entry does not cover any single vendor's schema in full.

Why it matters

Federation metadata solves a foundational trust and configuration problem in federated identity: without it, connecting an identity provider to a service provider would require administrators to manually exchange entity identifiers, endpoint URLs, supported bindings, and cryptographic keys, a process that is tedious and prone to transcription errors. By publishing a single standardized document, each entity lets its federation partners discover the endpoints and, critically, the signing and encryption keys needed to establish trust. This makes onboarding new relying parties faster and reduces the risk of misconfiguration that could break single sign-on or, worse, undermine the trust boundary between partners.

Because metadata carries the keys used to validate tokens and assertions, its integrity and freshness are security-relevant. If a relying party trusts stale metadata after a signing key has rotated, valid tokens may be rejected; conversely, failing to consume updated metadata can leave a party trusting a key that should no longer be in use. Publishers such as Microsoft Entra ID and AD FS expose metadata at well-known endpoints (for example the FederationMetadata.xml endpoint in AD FS) so that partners can retrieve current configuration, and some publishers support conditional retrieval mechanisms such as ETag comparison to avoid re-fetching unchanged documents while still detecting changes.

For teams operating at scale, metadata is also the linchpin of automation. Rather than hand-editing per-partner trust configurations, administrators can point tooling at a metadata URL and let the relying party ingest endpoints and keys programmatically. This is why practitioners frequently seek to retrieve provider metadata when wiring an identity provider into downstream services; the exact fields, format, and refresh behavior, however, vary by standard, vendor, and deployment configuration.

Who it's relevant to

Security Architects

Architects designing federated SSO between identity providers and service providers rely on metadata as the trust anchor that carries entity identifiers, endpoints, and signing/encryption keys. Understanding how metadata is published, retrieved, and refreshed is essential to designing trust boundaries that remain valid across key rotation and endpoint changes.

IAM Engineers and System Administrators

Engineers configuring relying parties consume metadata to wire up federation without manual key and endpoint entry. In practice this means locating a publisher's metadata endpoint (for example the AD FS FederationMetadata.xml endpoint under AD FS > Service > Endpoints, or the Microsoft Entra ID federation metadata document) and pointing tooling at it, ideally automating retrieval to keep configuration current.

Automation and Platform Engineers

Teams automating federation setup, such as connecting an identity provider to multiple downstream services, use metadata URLs to ingest configuration programmatically rather than editing trust settings by hand. Support for conditional retrieval mechanisms like ETag comparison, where available, lets automation detect changes efficiently without re-fetching unchanged documents.

Inside Federation Metadata

Entity Identifiers (EntityID)

A globally unique identifier for each participating entity, such as an identity provider or service provider. In SAML 2.0 metadata, the EntityID anchors the trust relationship and is referenced during protocol exchanges to identify the peer.

Roles and Descriptors

Metadata declares the roles an entity plays, typically expressed through descriptor elements such as IDPSSODescriptor and SPSSODescriptor in SAML 2.0. These indicate whether the entity acts as an identity provider, a service provider, or both.

Signing and Encryption Keys

Certificates or public keys used to verify signatures on protocol messages and, where configured, to encrypt assertions or elements. Metadata commonly distinguishes key usage (for example, signing versus encryption). Note that a signed message is not the same as an encrypted one; metadata may reference both purposes separately.

Endpoints (Bindings and Locations)

URLs and their associated protocol bindings that specify where messages are sent, such as single sign-on service, single logout service, and assertion consumer service endpoints in SAML 2.0. Each endpoint typically pairs a location with a binding (for example, HTTP-Redirect or HTTP-POST).

Supported NameID Formats and Attributes

Declarations of the subject identifier formats an entity supports and, in some profiles, the attributes it can provide or requires. This helps peers align on how principals are identified and what claims are exchanged.

Organizational and Contact Information

Descriptive elements identifying the operating organization and technical or support contacts. This information is administrative rather than protocol-critical and supports coordination between federation participants.

Validity and Signature over the Metadata

Metadata documents are often themselves signed and may carry validity windows or expiry indicators, depending on the profile and deployment, so consumers can verify authenticity and freshness before establishing trust.

Common questions

Answers to the questions practitioners most commonly ask about Federation Metadata.

Is federation metadata the same thing as a trust relationship between two parties?

No. Federation metadata is the machine-readable document that describes a party's configuration (such as endpoints, supported bindings, and signing/encryption keys), but exchanging metadata does not by itself establish trust. Trust is established when each party imports, validates, and explicitly accepts the other's metadata, typically by verifying signatures or confirming the source through an out-of-band process. The metadata carries the technical details; the deliberate act of consuming and trusting it is what creates the federation relationship.

Does federation metadata handle authentication or make access decisions?

No. Federation metadata is configuration data used to set up the connection between parties (for example, an IdP and an SP in SAML 2.0). It describes where and how protocol messages should be exchanged, but it does not authenticate users or authorize access. Authentication happens at runtime when the identity provider verifies a principal, and authorization decisions are made separately based on claims or policy. Metadata simply enables the parties to interoperate.

How is federation metadata typically exchanged between parties during onboarding?

In most SAML 2.0 deployments, metadata is exchanged either as a static file shared out-of-band or via a metadata URL that a party can fetch. Some deployments consume metadata dynamically from a published endpoint, while others require manual import of a downloaded document. The exchange method affects how updates propagate, so it is worth confirming with each party whether their metadata is expected to be pulled periodically or configured once as a static import.

What should be validated in a partner's metadata before importing it?

Depending on configuration, teams typically verify the metadata's signature (if signed), confirm the entity identifier matches what was agreed, review the declared endpoints and bindings, and check the certificates or keys used for signing and, where applicable, encryption. It is also worth confirming any validity or expiry attributes on the document. Because a signed metadata document proves integrity and origin but does not encrypt its contents, treat the transport and source of the document with appropriate care.

How are certificate or key rotations handled through federation metadata?

Metadata can list one or more keys, and in many deployments a rotation is coordinated by publishing updated metadata that includes both the old and new keys during a transition window. Parties consuming the metadata then need to refresh their copy for the change to take effect. If metadata is imported statically rather than fetched dynamically, each consuming party may have to re-import manually, so rotation timing should be coordinated to avoid validation failures. Exact behavior varies by vendor and profile.

What typically breaks a federation when metadata becomes stale or out of date?

Common failure modes include signature or assertion validation errors after a key rotation that was not propagated, requests sent to endpoints that have changed, or binding mismatches. In statically imported configurations, an expired or superseded document can cause runtime authentication attempts to fail even though nothing changed on the failing party's side. Establishing a refresh process, or monitoring metadata expiry where such attributes are present, helps reduce these disruptions, depending on how each party consumes the document.

Common misconceptions

Federation metadata authenticates users.

Metadata does not authenticate any principal. It describes the configuration and trust material of federation entities (such as IdPs and SPs) so that authentication and message-verification can occur correctly. Authentication of a user happens during the protocol flow itself, separately from metadata exchange.

Keys published in metadata mean the exchanged messages are encrypted.

Metadata typically publishes certificates or public keys used for signing message verification and, where configured, for encryption, but these are distinct usages. A signature proves integrity and origin; it does not provide confidentiality. Whether assertions are encrypted depends on the deployment and the declared key usage.

Federation metadata is a single universal format across all identity protocols.

The metadata concept described here is most closely associated with the SAML 2.0 federation standard and its XML-based descriptors. Other ecosystems, such as OpenID Connect, use different discovery mechanisms, so metadata structure and semantics vary by protocol and profile rather than being interchangeable.

Best practices

Validate the signature and, where present, the validity window on consumed metadata before trusting its contents, so that stale or tampered configuration is rejected.

Refresh metadata regularly rather than pinning it once, since endpoints, keys, and supported formats can change; the appropriate cadence depends on the deployment and the metadata's declared validity.

Track key rollover carefully by supporting overlapping signing and encryption keys in metadata to avoid outages when certificates are rotated.

Confirm that declared endpoints and bindings (for example, assertion consumer service and single logout locations) match the intended protocol flow before establishing trust with a peer.

Keep signing and encryption key usages clearly distinguished in metadata and verify that each is applied for its intended purpose, remembering that a signed message is not an encrypted one.

Restrict trust to metadata obtained from authenticated, integrity-protected sources, and avoid trusting metadata delivered over unverified channels.