Skip to main content
Version: v0.25.0 (Latest)

OpenID Federation

OpenID Federation 1.1 lets parties that have never met establish trust through a shared hierarchy. Every participant publishes a signed description of itself, every authority signs statements about the participants directly below it, and a verifier follows those statements up to a Trust Anchor it already accepts. The EDK lets a tenant take part in such a federation with its own organization and resources, and lets it run a federation as Trust Anchor or intermediate.

This page explains the model. The task guides build on it:

All administration runs through the OpenID Federation API under /api/platform/config/v1/tenants/{tenantId}/openid-federation. The protocol endpoints that other federation members call are public and answer at each entity's own URL.

Entities and Entity Identifiers​

An entity is something the tenant publishes into a federation: the organization itself, a branch of it, or one of its resources. Each entity has an Entity Identifier, an https URL without query, fragment or user information. The identifier is kept exactly as written. Other members find the entity by appending /.well-known/openid-federation to it (OpenID Federation 1.1 §9), so the identifier must be a URL the deployment actually serves for the tenant. An identifier with a path, such as https://acme.example.com/issuer, is served at https://acme.example.com/issuer/.well-known/openid-federation.

An entity records the authority it is meant to have. LEAF entities only describe themselves. INTERMEDIATE entities also sign statements about subordinates. ROOT entities are Trust Anchors. The recorded kind is a request, not a permission: whether an entity may actually act as an authority is established when it is published, from what the bound resource is allowed to be.

Entities move through DRAFT, ACTIVE, SUSPENDED and ENDED. A caller can ask for DRAFT, SUSPENDED or ENDED. ACTIVE is never set by a request; it follows from published and verified evidence.

Resource bindings​

A resource binding ties an entity to the real resource whose metadata it publishes. The resource is an ORGANIZATION, an AUTHORIZATION_SERVER, a CREDENTIAL_ISSUER or a VERIFIER, hosted on the platform or registered as external. The binding also lists the protocol roles the resource serves and the metadata profile for each role: OpenID Federation for OpenID Connect 1.1 for authorization server roles, and OpenID Federation for Wallet Architectures 1.0 (draft 05) for credential issuer and verifier roles. An organization binding has no roles and contributes only federation_entity metadata.

Binding a resource is what lets the EDK prepare an Entity Configuration from current facts instead of from hand-written JSON. When the entity is published, the metadata comes from the resource as it is served at that moment:

  • an organization contributes federation_entity claims such as organization_name, contacts, organization_uri and policy_uri, and, when the entity is an authority, the URLs of the federation endpoints it serves;
  • a hosted authorization server contributes its authorization server metadata;
  • a credential issuer contributes openid_credential_issuer metadata, read from the Credential Issuer Metadata it serves, so the federation states exactly what wallets resolve. Its Entity Identifier is its Credential Issuer Identifier;
  • a verifier contributes openid_credential_verifier metadata, taken from the Verifier Metadata configured for the client identifier openid_federation:<Entity Identifier>.

One organization can back several entities, for example one per federation it takes part in. Credential issuers and verifiers are always leaves; they never sign statements about others. Wallet provider entities are not supported, because the platform has no wallet provider product to observe openid_wallet_provider metadata from.

Federation contexts​

A federation context is a federation the tenant takes part in. It names the federation's expected Trust Anchors by Entity Identifier and can suggest a default Immediate Superior. Saving a context enrolls nothing and trusts nothing; it records which anchors a chain is expected to end at when the tenant later verifies admission.

Superiors and participations​

A superior relationship declares that one entity sits directly below another. Either side can be LOCAL, an entity of this tenant, or EXTERNAL, an entity identified only by its Entity Identifier. A local entity under an external Trust Anchor, an external member under a local Trust Anchor, and a local branch under a local organization are all expressed this way. A declared superior is an intention. The superior later signs its own Subordinate Statement about the child; a superior never uses the child's private keys, and the child never signs on the superior's behalf.

A participation puts one entity into one federation context. An entity can take part in several federations independently. Each participation names the declared superiors that carry it. A local superior must itself take part in the same federation, and an entity is never placed under a local superior that also belongs to a federation the entity does not take part in. Organizational parentage alone never makes one entity the superior of another.

A resource is bound to an entity, which takes part in a federation context through a participation carried by superior relationships. A Trust Domain admits the federation's Trust Anchor.

Statements​

Two kinds of signed statements carry the federation (OpenID Federation 1.1 §3).

An Entity Configuration is what an entity says about itself: its Federation Entity Keys, its metadata per Entity Type, the authority_hints that point at its superiors, and, for an authority, the Trust Mark types it issues. The EDK signs it with the entity's selected Federation Entity Key and serves it as application/entity-statement+jwt at the entity's well-known URL. Each signed revision is immutable.

A Subordinate Statement is what an authority says about an entity directly below it: the keys it vouches for, any metadata it adds, the metadata policy and constraints it imposes (§3.1.3, §6). An authority signs a statement only over keys an operator has reviewed, and serves it from its fetch endpoint.

Both kinds expire. Their lifetime is set by the deployment, so statements have to be renewed before they lapse. Operate a federation describes renewal.

Saving administration records never signs, publishes, trusts or registers anything. Publishing an Entity Configuration, signing a Subordinate Statement, verifying admission and issuing a Trust Mark are each a separate, explicit operation with its own authorization.

Trust Anchors by reference​

A Trust Anchor is always referenced by its https Entity Identifier. When a chain is verified, the anchor's keys are read from the anchor's own Entity Configuration at its well-known URL. Pinning anchor keys is possible but not required. This keeps anchor key rollover (§11.2) in the hands of the anchor operator instead of in every relying party's configuration.

How Trust Domains decide trust​

The federation administration describes where the tenant sits in a federation. It does not decide whom the tenant's resources trust. That decision belongs to Trust Domains, as it does for X.509, DID and other evidence. A federation's Trust Anchor enters a Trust Domain as an anchor with evidence mechanism OIDFED_ENTITY, whose value is the anchor's Entity Identifier, admitted for the usages it may answer. There is no separate list of trusted federations or trusted issuers.

The usages that accept federation anchors are CREDENTIAL_ISSUER_TRUST, VERIFIER_TRUST, WALLET_PROVIDER_ESTABLISHMENT, AUTHORIZATION_SERVER_TRUST and CLIENT_REGISTRATION_TRUST. The last one is specific to federation: it lists the Trust Anchors under which a hosted authorization server accepts clients that register through OpenID Federation. Its anchors carry the admission class CLIENT, and that admission class only accepts OIDFED_ENTITY anchors. See Accept federation clients.

Effective participation​

A participation becomes effective (ACTIVE) when two things hold at the same time. First, the superior that carries it has been verified: the tenant resolved the entity's Trust Chain through that superior to one of the federation's expected Trust Anchors (§4, §10), and the superior's statement is recorded as evidence on the relationship. Second, a Trust Domain attached to the bound resource, for the trust purpose that resource is governed by, admits that Trust Anchor as an OIDFED_ENTITY anchor. A resource is a Trust Domain consumer, and the usage of its attachment is the purpose. A verifier attached for CREDENTIAL_ISSUER_TRUST, for example, takes part effectively only in federations whose anchor its issuer-trust domain admits.

Either condition can lapse. A superior's statement expires, a Trust Domain is detached or an anchor loses its admission, and the participation stops being effective until the evidence is renewed.

Specifications​

The IDK guide OpenID Federation Trust covers Trust Chain resolution and verification at the library level.