All posts

OpenID Federation Spec: Because Exchanging Metadata Spreadsheets Was Apparently Not a Great…

by Robert Broeckelmann

Or: How the Identity Industry Invented a Cryptographically Signed Phone Book

Identity federations are one of those things that sound incredibly sophisticated until you learn how many of them historically operated.

People often imagine a grand system of automated trust, cryptographic validation, and mathematically elegant relationships between organizations.

Sometimes that’s true.

Other times it’s a collection of emails, spreadsheets, PDFs, help desk tickets, and one person named Steve who everyone trusts because he’s been maintaining the federation since 2008.

The OpenID Federation spec exists because the identity industry finally looked at this situation and decided_,_ “Perhaps we should automate trust before Steve retires.” Well, at my last long-term client, it was Patrick, but this is not terribly important. It provides a policy language to describe the requirements for federation relationships.

OpenID Federation is to OAuth2/OIDC what WS-SecurityPolicy was to WS-Security, except it also incorporates automated trust establishment, metadata distribution, and federation management that required several separate WS- specifications.

For engineers with a WS-* background, that comparison is often enough to make the architecture “click.” The next step is to point out that OpenID Federation deliberately folds together responsibilities that, in the WS-* ecosystem, were divided among:

  • WS-SecurityPolicy
  • WS-MetadataExchange
  • WS-Federation metadata
  • PKI-based trust distribution

That’s one of the reasons the OpenID stack feels both simpler to deploy and more cohesive despite providing comparable federation capabilities.

Note, this spec isn’t changing the wire-level mechanics of how the OIDC protocol authenticates a user between two Identity Provider systems for the purposes of Single Sign On; it’s just making it a little easier to setup and maintain.

The Original Problem

Imagine you’re building an application that trusts users from dozens, hundreds, or even thousands of organizations.

You need to know:

  • Which identity providers are legitimate?
  • Which OAuth authorization servers are allowed?
  • Which certificates are valid?
  • Which metadata can be trusted?
  • Who approved all of this?

For a small federation, you can manage this manually.

For a large federation, this becomes the digital equivalent of herding cats while blindfolded.

  • Every participant has metadata.
  • Every participant has signing keys.
  • Every participant changes things occasionally.
  • Every participant swears they’ll notify everyone before making changes. They won’t.

The Traditional Solution

Historically, many federations worked something like this:

Organization A: “Can we join the federation?”

Federation Operator: “Sure. Please fill out this form.”

Organization A: “Done.”

Federation Operator: “Excellent. We have now manually entered your information into a giant XML file.”

Organization A: “That sounds fragile.”

Federation Operator: “It is.”

Organization A: “What happens if we rotate our keys?”

Federation Operator: “We send emails.”

Organization A: “To whom?”

Federation Operator: “Everyone.”

Organization A: “Oh no.”

Enter OpenID Federation

OpenID Federation approaches the problem differently.

Instead of manually distributing trust information, it creates a cryptographically verifiable chain of trust between organizations.

Think of it as a certificate authority model that was designed specifically for identity systems rather than web servers.

The specification defines several key concepts:

  • Trust Anchors
  • Intermediate Entities
  • Leaf Entities
  • Entity Statements
  • Trust Chains
  • Trust Marks

Which sounds intimidating until you realize it’s basically a family tree with digital signatures.

Trust Anchors: The Adults in the Room

Every federation starts with a Trust Anchor.

This is the organization everyone agrees to trust.

If a federation were a medieval kingdom, the Trust Anchor would be the king.

Or queen.

Or dragon.

Whatever your governance model requires.

The Trust Anchor publishes cryptographically signed information about itself and the entities beneath it.

Everyone else ultimately traces their trust back to this root authority.

In other words_,_ I trust Alice because Bob vouched for her, and I trust Bob because Carol vouched for him, and I trust Carol because she’s the federation authority.

This is surprisingly similar to how humans have operated for thousands of years.

The difference is that OpenID Federation uses digital signatures instead of gossip.

Entity Statements: Cryptographically Signed Business Cards

Every participant publishes signed metadata called an Entity Statement.

These statements contain information such as:

  • Entity identifiers
  • Public keys
  • Metadata
  • Federation information
  • Trust relationships

Most importantly, the statements are signed.

This means an attacker cannot simply alter the metadata and hope nobody notices. The signatures will fail validation.

It’s like handing someone a business card that immediately bursts into flames if anybody edits it.

Trust Chains: Following the Breadcrumbs

The real magic is the Trust Chain.

Suppose an application encounters an unfamiliar identity provider.

Instead of blindly trusting it, the application follows a chain of signed statements:

Identity Provider →

University →

National Research Federation →

Trust Anchor

Each participant cryptographically signs statements about the entities below them.

If every signature validates correctly and the chain terminates at a trusted anchor, trust is established.

This is remarkably similar to certificate validation in TLS.

The difference is that we’re validating identity-system metadata rather than website certificates.

Or put another way:

TLS answers:

“Can I trust this server?”

OpenID Federation answers:

“Can I trust this identity provider, and who says I should?”

Trust Marks: Digital Gold Stars

OpenID Federation also introduces Trust Marks.

A Trust Mark is essentially a signed statement saying:

“This organization meets a particular set of requirements.”

Perhaps the entity passed a security audit.

Perhaps it complies with a specific regulatory framework.

Perhaps it completed a certification process.

Trust Marks are cryptographically signed and can be validated by federation participants.

They’re basically the identity federation equivalent of those stickers restaurants receive after passing a health inspection.

Only harder to fake.

And significantly less likely to involve refrigeration requirements.

Federation Policies: The Rulebook

Another useful feature is federation-wide policy enforcement.

A federation can specify requirements that participating entities must follow.

For example:

  • Supported signing algorithms
  • Required security features
  • Metadata constraints
  • Protocol requirements

Instead of every participant inventing their own interpretation of security best practices, the federation can define them centrally and distribute them through signed policy metadata.

Security teams everywhere briefly experienced a feeling unfamiliar to them.

Hope.

An example:

{  "metadata_policy": {    "openid_provider": {      "issuer": {        "essential": true      },      "jwks_uri": {        "essential": true      },      "authorization_endpoint": {        "essential": true      },      "token_endpoint": {        "essential": true      },      "userinfo_endpoint": {        "essential": false      },      "pushed_authorization_request_endpoint": {        "essential": true      },      "authorization_response_iss_parameter_supported": {        "value": true      },      "require_pushed_authorization_requests": {        "value": true      },      "require_request_uri_registration": {        "value": true      },      "request_object_signing_alg_values_supported": {        "subset_of": [          "PS256",          "ES256"        ]      },      "id_token_signing_alg_values_supported": {        "subset_of": [          "PS256",          "ES256"        ]      },      "token_endpoint_auth_methods_supported": {        "subset_of": [          "private_key_jwt",          "tls_client_auth"        ]      },      "grant_types_supported": {        "superset_of": [          "authorization_code"        ]      },      "response_types_supported": {        "subset_of": [          "code"        ]      },      "code_challenge_methods_supported": {        "superset_of": [          "S256"        ]      },      "acr_values_supported": {        "add": [          "urn:example:loa:high"        ]      },      "scopes_supported": {        "add": [          "openid",          "profile",          "email"        ]      },      "subject_types_supported": {        "subset_of": [          "pairwise"        ]      },      "default_max_age": {        "max": 900      }    },    "oauth_authorization_server": {      "authorization_endpoint": {        "essential": true      },      "token_endpoint": {        "essential": true      },      "pushed_authorization_request_endpoint": {        "essential": true      },      "dpop_signing_alg_values_supported": {        "subset_of": [          "ES256",          "PS256"        ]      },      "token_endpoint_auth_methods_supported": {        "subset_of": [          "private_key_jwt",          "tls_client_auth"        ]      }    },    "oauth_client": {      "grant_types": {        "subset_of": [          "authorization_code"        ]      },      "response_types": {        "subset_of": [          "code"        ]      },      "token_endpoint_auth_method": {        "subset_of": [          "private_key_jwt",          "tls_client_auth"        ]      },      "id_token_signed_response_alg": {        "subset_of": [          "PS256",          "ES256"        ]      },      "request_object_signing_alg": {        "subset_of": [          "PS256",          "ES256"        ]      },      "authorization_signed_response_alg": {        "subset_of": [          "PS256",          "ES256"        ]      },      "require_pkce": {        "value": true      },      "dpop_bound_access_tokens": {        "value": true      }    },    "openid_relying_party": {      "client_registration_types": {        "subset_of": [          "automatic"        ]      },      "require_signed_request_object": {        "value": true      },      "default_max_age": {        "max": 600      }    }  }}

Reading this as prose instead of JSON:

Every OpenID Provider must:

  • Publish all required endpoints
  • Support PAR (Pushed Authorization Requests)
  • Require pre-registered Request URIs
  • Only issue Authorization Code flows
  • Support PKCE using S256
  • Support only PS256 or ES256 signatures
  • Support only private_key_jwt or mTLS client authentication
  • Use pairwise subject identifiers
  • Limit authentication freshness (max_age) to 15 minutes.

Every Authorization Server must:

  • Publish PAR
  • Support DPoP
  • Allow only strong client authentication.

Every OAuth2 Client must:

  • Use Authorization Code flow.
  • Use PKCE
  • Use DPoP-bound access tokens
  • Sign Request Objects
  • Authenticate with either mTLS or private_key_jwt
  • Never use client secrets

Every Relying Party must:

  • Require signed Request Objects
  • Support only automatic registration
  • Reauthenticate users after 10 minutes

A request to the federation metadata configuration endpoint would look like:

  GET /.well-known/openid-federation HTTP/1.1  Host: op.sunet.se

Automatic Registration

OpenID Federation 1.0 transforms client onboarding from a manual administrative process into an automated trust evaluation process. In a traditional OAuth2 deployment, every new client typically requires exchanging redirect URIs, signing algorithms, client authentication methods, and security requirements through email, spreadsheets, or administrative portals before creating a client registration. OpenID Federation replaces this with a model where the client presents only its Entity Identifier (or, in Explicit Registration, its signed Entity Configuration or Trust Chain). The authorization server retrieves the client’s published Entity Configuration, validates its Trust Chain to a trusted Trust Anchor, resolves all applicable metadata and federation policies, and determines whether the client is permitted to participate in the federation.

The authorization server does more than simply verify trust — it also derives the client’s effective configuration from the federation’s published policies. During metadata resolution, policies from trust anchors and intermediate authorities are combined with the client’s own metadata to produce a compliant configuration. For example, if the federation requires Pushed Authorization Requests (PAR), PKCE, ES256 signatures, private_key_jwt client authentication, or pairwise subject identifiers, those requirements are automatically enforced without requiring the client administrator to understand or manually configure every federation rule. If the client proposes unsupported or non-compliant metadata, the authorization server may either reject the registration or normalize the metadata into a compliant configuration, depending on the registration method and local policy.

OpenID Federation defines two complementary onboarding models. Automatic Registration eliminates the registration step entirely: the client’s Entity Identifier serves as its Client ID, the authorization server retrieves and validates the client’s Entity Configuration on demand, and authentication relies exclusively on asymmetric cryptography rather than shared client secrets. Explicit Registration, by contrast, more closely resembles OAuth Dynamic Client Registration, but instead of submitting static metadata, the client submits its signed Entity Configuration or complete Trust Chain. The authorization server then validates the federation, applies federation policy, and provisions a client registration that is guaranteed to comply with the federation’s requirements. Both approaches dramatically reduce operational overhead while enabling organizations to onboard thousands of clients consistently and securely across a large federation.

Perhaps the most significant architectural shift is that trust becomes dynamic rather than static. Client registrations are no longer permanent configuration objects created once and forgotten. Their validity is tied to the underlying Trust Chain and published federation metadata. As policies evolve, cryptographic keys rotate, entities are removed from the federation, or trust relationships change, newly resolved metadata automatically reflects those updates. This allows security requirements to evolve across an entire federation without requiring administrators to manually revisit every individual client registration — a capability that makes OpenID Federation particularly attractive for large government, financial, healthcare, and cross-organizational identity ecosystems.

Federation Made Easier

Modern identity ecosystems are becoming increasingly interconnected.

Government services trust universities.

Universities trust research organizations.

Research organizations trust cloud providers.

Cloud providers trust identity providers.

Identity providers trust certificate authorities.

Certificate authorities trust cryptography.

Cryptography trusts mathematics.

Mathematics trusts nobody.

As these ecosystems grow, manual trust management becomes impossible at scale.

OpenID Federation provides a mechanism for discovering, validating, and maintaining trust relationships automatically.

Instead of exchanging spreadsheets, organizations exchange signed metadata.

Instead of manually configuring every relationship, trust chains are evaluated automatically.

Instead of trusting Steve’s inbox, systems trust cryptographic signatures.

This is generally considered progress.

Summary

OpenID Federation isn’t a replacement for OpenID Connect or OAuth.

It’s the infrastructure that helps large groups of organizations decide who should be trusted in the first place.

If OpenID Connect is the process of checking someone’s passport at the border, OpenID Federation is the system that determines which governments are allowed to issue passports.

It’s trust about trust.

Authentication for authentication.

Metadata for metadata.

A cryptographically signed directory of organizations all vouching for one another.

And perhaps most importantly, it dramatically reduces the number of federation administrators who spend their afternoons emailing XML files to each other.

Humanity may never completely eliminate spreadsheets, but OpenID Federation is at least putting up a fight.

Notes

  • AI / GenAI / ChatGPT / etc were not used to generate the text of this article.
  • ChatGPT was used to generate the images.
  • I used em dashes in my writing before the current GenAI wave was a thing. Not planning on changing now.
  • Names have been changed to protect the guilty.
  • None of the hostnames or users used in examples actually exist.
  • Feel free to post any comments or suggestions below.

Originally published on Medium.

More articles