OpenID Connect Federation 1.0

(This article is a partial reprint of the article “OpenID Connect Federation 1.0” on the Authlete website.)

Overview

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.

Trust Chain

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

Entity Configuration

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 "/.well-known/openid-federation".

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 http:// or 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 http or 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.

https://rp.example.com/123/.well-known/openid-federation

In general, self-signed JWTs of federation entities that are published at their respective /.well-known/openid-federation are called “entity configuration”.

Authority Hints

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 https://ia.example.com, the authority_hints claim in the entity configuration of the relying party contains https://ia.example.com.

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 https://ta.example.com.

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 authority_hints claim.

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.

https://ia.example.com/fetch?sub=https://rp.example.com/123

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 authority_hints claim.

(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 authority_hints claim.

(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.

Metadata

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.

• client_registration_types_supported
• organization_name
• federation_registration_endpoint
• request_authentication_methods_supported
• request_authentication_signing_alg_values_supported
• signed_jwks_uri
• jwks

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.

• client_registration_types
• organization_name
• signed_jwks_uri

Authority 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.

• federation_fetch_endpoint
• federation_list_endpoint
• federation_resolve_endpoint
• federation_trust_mark_status_endpoint
• organization_name
• contacts
• logo_uri
• policy_uri
• homepage_uri

Metadata Policy

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.

Client Registration

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.

https://idp.example.com/authorize?request_uri=...&client_id=https://rp.example.com/123

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.

Also, the 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.

Request Authentication

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.

1. request_object - Request object signed with an asymmetric algorithm.
2. private_key_jwt - Client authentication using client assertion.
3. tls_client_auth - Client authentication using X.509 certificate.
4. self_signed_tls_client_auth - Client authentication using X.509 certificate.

References:

• 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.

References:

• 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.

1. Entity configuration. Its Content-Type is application/entity-statement+jwt.
2. Trust chain, a JSON array listing entity statements. Its Content-Type is application/trust-chain+json.

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.

Also, the client_registration_types client metadata of the client being explicitly registered must include explicit.

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.

The 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.

Authlete Implementation

OpenID Connect Federation 1.0 is supported by Authlete 2.3 and newer versions. See “Authlete Implementation” for details.

Finally

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.