OpenID Connect Federation 1.0
(This article is a partial reprint of the article “OpenID Connect Federation 1.0” on the Authlete website.)
OpenID Connect Federation 1.0 defines a mechanism where an identity provider / authorization server and a relying party (client) that have no direct relationship trust each other based on trust chains and the identity provider accepts OAuth/OIDC requests from the relying party without needing prior registration of the relying party.
Trust chains are uni-directional. Therefore, two trust chains are built when an identity provider and a relying party trust each other. One is a trust chain for the relying party to trust the identity provider.
The other is a trust chain for the identity provider to trust the relying party.
A trust chain is built by third-party authorities. An authority that works as the origin of a trust chain is called “trust anchor” and other authorities in between the trust anchor and the target leaf entity (an identity provider or a relying party) are called intermediate authority. Trust anchors and intermediate authorities are conceptually equivalent to root certificate authority (Root CA) and intermediate certificate authority (Intermediate CA) in the Public Key Infrastructure (PKI).
A relying party trusts one or more trust anchors. If any of the trust anchors has a path to the target identity provider, the relying party can trust the identity provider.
Likewise, an identity provider trusts one or more trust anchors. If any of the trust anchors has a path to the target relying party, the identity provider can trust the relying party.
The diagram below illustrates an overview of OpenID Connect Federation 1.0 that has been explained in this section.
Technically speaking, a trust chain is a sequence of JWTs (RFC 7519 JSON Web Token) that are issued by a leaf entity, zero or more intermediate authorities, and a trust anchor.
JWT Issued by Leaf Entity
A leaf entity issues a JWT that is signed by the leaf entity’s private key.
The OIDC Federation specification requires that the payload part of the JWT issued by a leaf entity contain the public key corresponding to the private key which is used to sign the JWT. The
jwks claim is used to include the public key.
As a result, the JWT becomes a self-signed JWT. Therefore, both the
iss claim (Issuer; RFC 7519 Section 4.1.1) and the
sub claim (Subject; RFC 7519 Section 4.1.2) in the payload part of the JWT hold the leaf entity’s identifier.
JWT Issued by Intermediate Authority
An intermediate authority (or a trust anchor if no intermediate authority exists in a trust chain) that authorizes the leaf entity issues a JWT that is signed by the intermediate authority’s private key.
The purpose of the JWT is to indicate that the intermediate authority authorizes the leaf entity. For the purpose, the
sub claim holds the leaf entity’s identifier while the
iss claim holds the intermediate authority’s identifier.
In addition, the
jwks claim holds the public key of the leaf entity.
JWT Issued by Trust Anchor
A trust chain is terminated by a JWT signed by a trust anchor’s private key.
The JWT indicates that the trust anchor authorizes the last intermediate authority. The value of the
sub claim is the last intermediate authority’s identifier and the value of the
iss claim is the trust anchor’s identifier. If no intermediate authorities are involved, the trust anchor issues a JWT that directly authorizes the leaf entity. In that case, the
sub claim holds the leaf entity’s identifier.
The JWT issued by the trust anchor contains the public key of the last intermediate authority.
A trust chain may optionally have one more JWT that is self-signed by the trust anchor at the end.
As it is a self-signed JWT, both the
iss claim and the
sub claim hold the trust anchor’s identifier.
Trust Chain Summary
The following diagram depicts the entire trust chain.
Trust Chain Resolution
The resolution process of a trust chain starts from getting the self-signed JWT of a leaf entity.
The location of the self-signed JWT is defined in the OIDC Federation specification. It is a URL constructed by concatenating the leaf entity’s identifier and the fixed string
Leaf Entity's Identifier + /.well-known/openid-federation
If you know the specifications of OpenID Connect Discovery 1.0 and RFC 8414 OAuth 2.0 Authorization Server Metadata, you will guess that the leaf entity’s identifier is a URL that starts with
https://. Your guess is correct.
Participants of a federation, i.e., identity providers, relying parties, intermediate authorities and trust anchors, are called “federation entity”. Each federation entity has a globally unique identifier. The identifier is called “entity ID”. And, entity IDs must be URLs whose scheme part is either
https. It is expected that Web servers are running on hosts identified by the URLs so that federation entities can issue JWTs that are necessary to build trust chains.
For instance, when the entity ID of a relying party is
https://rp.example.com/123, the self-signed JWT of the relying party is expected to be published at the following URL.
In general, self-signed JWTs of federation entities that are published at their respective
/.well-known/openid-federation are called “entity configuration”.
The payload part of an entity configuration contains the
authority_hints claim. It is a JSON array listing entity IDs of intermediate authorities and/or trust anchors that can issue a JWT indicating that the authority authorizes the federation entity of the entity configuration.
For example, when a relying party whose entity ID is
https://rp.example.com/123 has a direct intermediate authority whose entity ID is
authority_hints claim in the entity configuration of the relying party contains
Likewise, if the intermediate authority has a trust anchor whose entity ID is
https://ta.example.com as a direct authority, the
authority_hints claim in the entity configuration of the intermediate authority contains
On the other hand, because a trust anchor has no upper authority by definition, the entity configuration of a trust anchor does not include the
Federation Fetch Endpoint
The next step after getting the entity configuration of a leaf entity is to get a JWT from the direct authority of the leaf entity that indicates that the authority authorizes the leaf entity.
Authorities are supposed to provide an endpoint that issues JWTs for the purpose. The endpoint is called “federation fetch endpoint”. The table below is a summary of the specification of the endpoint.
For example, when an intermediate authority
https://ia.example.com provides its federation fetch endpoint at
https://ia.example.com/fetch, a JWT that indicates that the intermediate authority authorizes a federation entity
https://rp.example.com/123 can be obtained by making the following HTTP request.
The location of the federation fetch endpoint of an authority is written in its entity configuration. The
federation_fetch_endpoint claim holds the URL of the endpoint, but the claim is put at a bit deep place. It is placed inside the
federation_entity JSON object which is inside the
metadata JSON object.
The process of fetching JWTs from federation fetch endpoints is repeated until a JWT from a trust anchor is obtained. If the trust anchor is one of trusted ones, it means that a trust chain from the leaf entity to the trust anchor can be built. On the other hand, if the trust anchor is unknown, the trust chain cannot be used to trust the leaf entity. In this case, other paths need to be tried. To be concrete, other entries in the
authority_hints claim need to be tried.
Trust Chain Resolution Flow
Let’s review the flow of trust chain resolution.
(1) The first step is to get the entity configuration of a leaf entity.
(2) The entity configuration contains the
authority_hints claim. It is a JSON array listing entity IDs of intermediate authorities or trust anchors. Web servers of authorities can be identified by the entity IDs. In this example, an intermediate authority
https://ia.example.com is included in the
(3) The entity configuration of the intermediate authority is needed to know the URL of its federation fetch endpoint.
(4) An HTTP request with the
sub request parameter is sent to the federation fetch endpoint. In this example, the entity ID of the leaf entity (
https://rp.example.com/123) is specified as the value of the
sub request parameter.
(5) The federation fetch endpoint returns a JWT that indicates that the intermediate authority authorizes the leaf entity.
(6) The upper authorities of the intermediate authority are listed in the
authority_hints claim in the entity configuration of the intermediate authority. In this example, a trust anchor
https://ta.example.com is included in the
(7) The entity configuration of the trust anchor is needed to know the URL of its federation fetch endpoint.
(8) An HTTP request with the
sub request parameter is sent to the federation fetch endpoint. In this example, the entity ID of the intermediate authority (
https://ia.example.com) is specified as the value of the
sub request parameter.
(9) The federation fetch endpoint returns a JWT that indicates that the trust anchor authorizes the intermediate authority.
(10) The entity configuration of the leaf entity and the JWTs issued from the federation fetch endpoints consist of a trust chain.
Trust Chain Resolution Summary
The following diagram depicts the entire flow of trust chain resolution.
All the JWTs that appear in trust chain resolution are called “entity statement”. An entity configuration is a kind of entity statement.
An entity configuration contains metadata of the federation entity.
Identity Provider Metadata
Metadata of an identity provider are put in the
openid_provider JSON object which is in the
metadata JSON object.
Metadata that are defined in OpenID Connect Discovery 1.0, RFC 8414 OAuth 2.0 Authorization Sever Metadata and other standard specifications may appear in the
openid_provider JSON object.
In addition, the OIDC Federation specification defines the following server metadata.
Relying Party Metadata
Metadata of a relying party are put in the
openid_relying_party JSON object which is in the
metadata JSON object.
Metadata that are defined in OpenID Connect Dynamic Client Registration 1.0, RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol and other standard specifications may appear in the
openid_relying_party JSON object.
In addition, the OIDC Federation specification defines the following client metadata.
Metadata of authorities (intermediate authorities and trust anchors) are put in the
federation_entity JSON object which is in the
metadata JSON object.
The OIDC Federation specification defines the following metadata for authorities.
The entity configuration of the leaf entity in a trust chain includes metadata of the leaf entity. The
metadata claim is used to hold the metadata.
On the other hand, other JWTs in the trust chain issued by authorities may include metadata policies that are used to adjust the metadata of the leaf entity. The
metadata_policy claim is used to hold the metadata policy.
The metadata policies are combined before use.
Then, the combined metadata policy is applied to the metadata of the leaf entity. Metadata used by a federation is the metadata after the adjustment.
The following diagram depicts the flow of metadata policy application.
See the OIDC Federation specification for details about metadata policy.
In a typical implementation of identity provider, identifiers of relying parties (clients) are under the management of the identity provider. The identifiers are unique only in the realm of the identity provider. On the other hand, in the OIDC Federation world, every federation entity has a globally unique identifier.
An interesting characteristic of OIDC Federation is that the globally unique identifiers, i.e., entity IDs, can be used as a client ID in OAuth/OIDC requests. For example, an authorization request like below can be made. The point to pay attention to in the example is that the value of the
client_id request parameter is the entity ID of the relying party.
Automatic Client Registration
When the client ID in an OAuth/OIDC request is unknown but looks like an entity ID, an identity provider that supports OIDC Federation tries to find a trust chain that starts from the entity ID and ends with one of trust anchors that the identity provider trusts.
If such a trust chain is found, the identity provider automatically registers a new client with the entity ID and metadata and continues to process the OAuth/OIDC request.
The discovery document (OpenID Connect Discovery 1.0) of an identity provider that supports automatic client registration includes
automatic in the
client_registration_types_supported server metadata. Note that the OIDC Federation specification defines the
client_registration_types_supported server metadata as mandatory.
client_registration_types client metadata of the client being automatically registered must include
automatic. Note that the OIDC Federation specification defines the
client_registration_types client metadata as mandatory.
When an OAuth/OIDC request triggers automatic client registration, the request needs to be authenticated in some way or other. The OIDC Federation specification requires the requester to prove that it has a private key that is paired with a public key in the request. The specification lists the following as available request authentication methods.
request_object- Request object signed with an asymmetric algorithm.
private_key_jwt- Client authentication using client assertion.
tls_client_auth- Client authentication using X.509 certificate.
self_signed_tls_client_auth- Client authentication using X.509 certificate.
- Request Object — Implementer’s note about JAR (JWT-Secured Authorization Request)
- Client Authentication — OAuth 2.0 Client Authentication
- X.509 Certificate — Illustrated X.509 Certificate
Automatic client registration may happen at various endpoints, but available request authentication methods vary depending on characteristics of respective endpoints.
For example, request authentication methods based on client authentication are not usable at the authorization endpoint because client authentication is not performed at the authorization endpoint. Likewise, the request authentication method using a request object is not usable at the token endpoint because the token endpoint recognizes neither the
request request parameter nor the
request_uri request parameter.
The following table shows availability of request authentication methods per endpoint.
- Authorization Endpoint — The OAuth 2.0 Authorization Framework
- Token Endpoint — The OAuth 2.0 Authorization Framework
- PAR Endpoint — RFC 9126 OAuth 2.0 Pushed Authorization Requests
- Backchannel Authentication Endpoint — OpenID Connect Client-Initiated Backchannel Authentication Flow — Core 1.0
- Device Authorization Endpoint — RFC 8628 OAuth 2.0 Device Authorization Grant
The discovery document of an identity provider that supports automatic client registration is supposed to include the
request_authentication_methods_supported server metadata that indicates which request authentication methods are supported at which endpoints.
The value of the server metadata is a JSON object. Property names that appear in the JSON object are endpoint names such as
authorization_endpoint. A property value is a JSON array listing request authentication methods available at the corresponding endpoint.
Explicit Client Registration
In addition to automatic client registration, the OIDC Federation specification defines a way to register a client explicitly. The mechanism is called “explicit client registration”. It is similar to dynamic client registration defined in OpenID Connect Dynamic Client Registration 1.0 and RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol.
An identity provider that supports explicit client registration has the federation registration endpoint that accepts explicit client registration requests.
Input data to the federation registration endpoint is either of the following.
- Entity configuration. Its Content-Type is
- Trust chain, a JSON array listing entity statements. Its Content-Type is
When client registration succeeds, the federation registration endpoint returns an entity statement as a response. A distinctive point of the response is the inclusion of the
trust_anchor_id claim. The value of the claim denotes the entity ID of the trust anchor that has been selected for the client registration.
The value of the
client_id client metadata in the response is the client ID assigned to the relying party by the identity provider. The value may be different from the entity ID.
The discovery document of an identity provider that supports explicit client registration includes
explicit in the
client_registration_types_supported server metadata and advertises the URL of the federation registration endpoint by the
federation_registration_endpoint server metadata.
client_registration_types client metadata of the client being explicitly registered must include
Automatic Client Update
All entity statements in a trust chain include the
exp claim (Expiration Time; RFC 7519 Section 4.1.4) as the OIDC Federation specification requires so. The minimum value among the
exp claims is regarded as the expiration time of the trust chain.
The OIDC Federation specification expects that identity providers treat the expiration time of the trust chain as the expiration time of the client which was registered based on the trust chain.
When an identity provider detects that the trust chain of a client has expired, it tries to refresh the trust chain and update metadata of the client accordingly.
trust_chain Request Parameter
An OAuth/OIDC request may contain the
trust_chain request parameter. The identity provider may use the trust chain specified by the request parameter to update metadata of the client or register the client if it has not been registered yet.
OpenID Connect Federation 1.0 is supported by Authlete 2.3 and newer versions. See “Authlete Implementation” for details.
OpenID Connect Federation 1.0 is one of the most complex standard specifications related to OAuth and OpenID Connect and it is difficult to find commercial-quality implementations. Authlete is a rare example.
If you are interested in trying OpenID Connect Federation 1.0, please contact us.