OpenID Connect Federation 1.1 January 2026
Hedberg, et al. Standards Track [Page]
Workgroup:
OpenID Connect Working Group
Published:
Authors:
R. Hedberg
independent
M.B. Jones, Ed.
Self-Issued Consulting
G. De Marco
independent
A.Å. Solberg
Sikt
J. Bradley
Yubico
V. Dzhuvinov
Connect2id

OpenID Connect Federation 1.1 - draft 00

Abstract

A federation can be expressed as an agreement between parties that trust each other. In bilateral federations, direct trust can be established between two organizations belonging to the same federation. In a multilateral federation, bilateral agreements might not be practical, in which case, trust can be mediated by a third party. That is the model used in this specification.

An Entity in the federation must be able to trust that other Entities it interacts with belong to the same federation. It must also be able to trust that the information the other Entities publish about themselves has not been tampered with during transport and that it adheres to the federation's policies.

This specification contains the protocol-specific functionality defined in OpenID Federation 1.0. This includes Entity Type Identifiers and Metadata for OpenID Connect and OAuth 2.0 Entities and Client Registration flows. These can be used in multilateral federations for the purpose of establishing trust, in combination with the protocol-independent functionality defined in OpenID Federation 1.1. This specification introduces no new functionality not present in OpenID Federation 1.0.

▲

Table of Contents

1. Introduction

This specification describes how two Entities using OpenID Connect [OpenID.Core] or OAuth 2.0 [RFC6749] can participate in multilateral federations for the purpose of establishing trust, using the protocol-independent Federation constructs defined in OpenID Federation 1.1 [OpenID.Federation-1.1].

1.1. Requirements Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

All uses of JSON Web Signature (JWS) [RFC7515] and JSON Web Encryption (JWE) [RFC7516] data structures in this specification utilize the JWS Compact Serialization or the JWE Compact Serialization; the JWS JSON Serialization and the JWE JSON Serialization are not used.

1.2. Terminology

This specification uses the terms "Claim", "Claim Name", "Claim Value", "JSON Web Token (JWT)", and "JWT Claims Set" defined by JSON Web Token (JWT) [RFC7519], the terms "OpenID Provider (OP)" and "Relying Party (RP)" defined by OpenID Connect Core 1.0 [OpenID.Core], and the terms "Authorization Endpoint", "Authorization Server (AS)", "Client", "Client Authentication", "Client Identifier", "Client Secret", "Grant Type", "Protected Resource", "Redirection URI", "Refresh Token", "Resource Server (RS)", and "Token Endpoint" defined by OAuth 2.0 [RFC6749]. It incorporates the terms defined in Section 1.2 of [OpenID.Federation-1.1] by reference.

2. Overall Architecture

This specification defines how the protocol-independent Federation constructs defined in OpenID Federation 1.1 [OpenID.Federation-1.1] can be used with the OpenID Connect [OpenID.Core] and OAuth 2.0 [RFC6749] protocols. Those constructs include Entity Statements, Trust Chains, Trust Anchors, Metadata, and Trust Marks.

Specifically, it defines Entity Types for OpenID Connect and OAuth 2.0 and metadata values for them. It also defines extensions to these protocols used for establishing trust with OpenID Federation 1.1 [OpenID.Federation-1.1].

2.1. Cryptographic Trust Mechanism

The objects defined by this specification that are used to establish cryptographic trust between participants are secured as signed JWTs using public key cryptography, as described in Section 2.1 of [OpenID.Federation-1.1]. Note that this cryptographic trust mechanism intentionally does not rely on Web PKI / TLS [RFC9525] certificates for signing keys.

3. Entity Statement

Entity Statements are used in this specification as defined in Section 3 of [OpenID.Federation-1.1].

3.1. Entity Statement Claims

This specification defines the following additional Claims for use in Entity Statements.

3.1.1. Claims Used in Explicit Registration Requests

aud
OPTIONAL. The "aud" (audience) value MUST be the Entity Identifier of the OP and MUST NOT include any other values. This Claim is used in Explicit Registration requests; it is not a general Entity Statement Claim.

3.1.2. Claims Used in Explicit Registration Responses

aud
OPTIONAL. The "aud" (audience) value MUST be the Entity Identifier of the RP and MUST NOT include any other values. This Claim is used in Explicit Registration responses; it is not a general Entity Statement Claim.
trust_anchor
OPTIONAL. Its value MUST be the Entity Identifier of the Trust Anchor that the OP selected to process the Explicit Registration request, as specified in Section 12.2.3. This Claim is specific to Explicit Registration responses; it is not a general Entity Statement Claim.

3.2. Entity Statement Validation

Entity Statements MUST be validated in the manner defined in Section 3.2 of [OpenID.Federation-1.1]. These additional validation steps are defined by this specification. These steps MAY be performed in a different order, provided that the result - accepting or rejecting the Entity Statement - is the same.

  1. If the aud Claim is present, if the Entity Statement is an Explicit Registration request, validate that the value is the Entity Identifier for an OP, or if the Entity Statement is an Explicit Registration request, validate that the value is the Entity Identifier for an RP. This Claim MUST NOT be present in Entity Statements that are not Explicit Registration requests or responses unless its use is otherwise specified in an extension being employed.

  2. If the trust_anchor Claim is present, validate that its value is a URL using the https scheme. Implementations SHOULD validate that the Entity Identifier matches one of the Trust Anchors configured for the deployment. Furthermore, implementations SHOULD validate that the Entity Configuration for the Entity Identifier contains information compatible with the configured Trust Anchor information - especially the keys. This Claim MUST NOT be present in Entity Statements that are not Explicit Registration responses unless its use is otherwise specified in an extension being employed.

If any of these validation steps fail, the Entity Statement MUST be rejected.

3.3. Entity Statement Example

See Section 3.3 of [OpenID.Federation-1.1] for an example Entity Statement.

4. Trust Chain

Trust Chains are used in this specification as defined in Section 4 of [OpenID.Federation-1.1].

5. Metadata

Metadata is used in this specification as defined in Section 5 of [OpenID.Federation-1.1]. This section extends those definitions by adding Entity Types and metadata values for use with OpenID Connect and OAuth 2.0. It uses existing OpenID Connect and OAuth 2.0 metadata standards that are applicable to each Entity Type.

5.1. Entity Type Identifiers

The Entity Type Identifier uniquely identifies the Entity Type of a federation participant and the metadata format for that Entity Type. This section defines Entity Type Identifiers for OpenID Connect and OAuth 2.0 Federation Entities.

5.1.1. OpenID Connect Relying Party

The Entity Type Identifier is openid_relying_party.

All parameters defined in Section 2 of OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration], in [OpenID.RP.Choices], and in Section 5.2 of [OpenID.Federation-1.1] are applicable, as well as additional parameters registered in the IANA "OAuth Dynamic Client Registration Metadata" registry [IANA.OAuth.Parameters], excluding those parameters that are defined in the registry solely for use in registration responses (for example, client_secret).

In addition, the following RP metadata parameter is defined:

client_registration_types
RECOMMENDED. An array of strings specifying the client registration types the RP supports. Values defined by this specification are automatic and explicit. Additional values MAY be defined and used, without restriction by this specification.

The following is a non-normative example of the JWT Claims Set for an RP's Entity Configuration:

    {
      "iss": "https://openid.sunet.se",
      "sub": "https://openid.sunet.se",
      "iat": 1516239022,
      "exp": 1516298022,
      "metadata": {
        "openid_relying_party": {
          "application_type": "web",
          "redirect_uris": [
            "https://openid.sunet.se/rp/callback"
          ],
          "organization_name": "SUNET",
          "logo_uri": "https://www.sunet.se/sunet/images/32x32.png",
          "grant_types": [
            "authorization_code",
            "implicit"
          ],
          "signed_jwks_uri": "https://openid.sunet.se/rp/signed_jwks.jose",
          "jwks_uri": "https://openid.sunet.se/rp/jwks.json",
          "client_registration_types": ["automatic"]
        }
      },
      "jwks": {
        "keys": [
          {
            "alg": "RS256",
            "e": "AQAB",
            "kid": "key1",
            "kty": "RSA",
            "n": "pnXBOusEANuug6ewezb9J_...",
            "use": "sig"
          }
        ]
      },
      "authority_hints": [
        "https://edugain.org/federation"
      ]
    }
Figure 1: Example Relying Party Entity Configuration JWT Claims Set

5.1.2. OpenID Connect OpenID Provider

The Entity Type Identifier is openid_provider.

All parameters defined in Section 3 of OpenID Connect Discovery 1.0 [OpenID.Discovery] and Section 5.2 of [OpenID.Federation-1.1] are applicable, as well as additional parameters registered in the IANA "OAuth Authorization Server Metadata" registry [IANA.OAuth.Parameters]. For instance, the require_signed_request_object and require_pushed_authorization_requests metadata parameters can be used.

The issuer parameter value in the openid_provider metadata MUST match the Federation Entity identifier (the iss parameter within the Entity Configuration).

In addition, the following OP metadata parameters are defined:

client_registration_types_supported
RECOMMENDED. An array of strings specifying the client registration types the OP supports. Values defined by this specification are automatic and explicit. Additional values MAY be defined and used, without restriction by this specification.
federation_registration_endpoint
OPTIONAL. URL of the OP's federation-specific Dynamic Client Registration Endpoint. If the OP supports Explicit Client Registration Endpoint this URL MUST use the https scheme and MAY contain port, path, and query parameter components; it MUST NOT contain a fragment component. If the OP supports Explicit Client Registration as described in Section 12.2, then this Claim is REQUIRED.

The following is a non-normative example of the JWT Claims Set for an OP's Entity Configuration:

{
   "iss": "https://op.umu.se",
   "sub": "https://op.umu.se",
   "exp": 1568397247,
   "iat": 1568310847,
   "metadata":{
      "openid_provider":{
         "issuer": "https://op.umu.se",
         "signed_jwks_uri": "https://op.umu.se/openid/signed_jwks.jose",
         "authorization_endpoint": "https://op.umu.se/openid/authorization",
         "client_registration_types_supported":[
            "automatic",
            "explicit"
         ],
         "grant_types_supported":[
            "authorization_code",
            "implicit",
            "urn:ietf:params:oauth:grant-type:jwt-bearer"
         ],
         "id_token_signing_alg_values_supported":[
            "ES256",
            "RS256"
         ],
         "logo_uri": "https://www.umu.se/img/umu-logo-left-neg-SE.svg",
         "op_policy_uri": "https://www.umu.se/en/legal-information/",
         "response_types_supported":[
            "code",
            "code id_token",
            "token"
         ],
         "subject_types_supported":[
            "pairwise",
            "public"
         ],
         "token_endpoint": "https://op.umu.se/openid/token",
         "federation_registration_endpoint": "https://op.umu.se/openid/fedreg",
         "token_endpoint_auth_methods_supported":[
            "client_secret_post",
            "client_secret_basic",
            "client_secret_jwt",
            "private_key_jwt"
         ],
         "pushed_authorization_request_endpoint": "https://op.umu.se/openid/par",
         "request_object_signing_alg_values_supported": [
            "ES256",
            "RS256"
         ],
         "token_endpoint_auth_signing_alg_values_supported": [
            "ES256",
            "RS256"
         ]
      }
   },
   "authority_hints":[
      "https://umu.se"
   ],
   "jwks":{
      "keys":[
         {
            "e": "AQAB",
            "kid": "dEEtRjlzY3djcENuT01wOGxrZlkxb3RIQVJlMTY0...",
            "kty": "RSA",
            "n": "x97YKqc9Cs-DNtFrQ7_vhXoH9bwkDWW6En2jJ044yH..."
         }
      ]
   }
}
Figure 2: Example OpenID Provider Entity Configuration JWT Claims Set

5.1.3. OAuth Authorization Server

The Entity Type Identifier is oauth_authorization_server.

All parameters defined in Section 2 of [RFC8414] and Section 5.2 of [OpenID.Federation-1.1] are applicable, as well as additional parameters registered in the IANA "OAuth Authorization Server Metadata" registry [IANA.OAuth.Parameters].

The issuer parameter value in the oauth_authorization_server metadata MUST match the Federation Entity identifier (the iss Claim in the Entity Configuration).

5.1.4. OAuth Client

The Entity Type Identifier is oauth_client.

All parameters defined in Section 2 of OAuth 2.0 Dynamic Client Registration Protocol [RFC7591] and Section 5.2 of [OpenID.Federation-1.1] are applicable, as well as additional parameters registered in the IANA "OAuth Dynamic Client Registration Metadata" registry [IANA.OAuth.Parameters].

5.1.5. OAuth Protected Resource

The Entity Type Identifier is oauth_resource. The common metadata parameters defined in Section 5.2 of [OpenID.Federation-1.1] are applicable. In addition, deployments MAY use the protected resource metadata parameters defined in [RFC9728].

6. Federation Policy

6.1. Metadata Policy

Metadata Policy is used in this specification as defined in Section 6.1 of [OpenID.Federation-1.1].

6.2. Constraints

Constraints are used in this specification as defined in Section 6.2 of [OpenID.Federation-1.1].

7. Trust Marks

Trust Marks are used in this specification as defined in Section 7 of [OpenID.Federation-1.1].

8. Federation Endpoints

This specification uses the Federation Endpoints defined in Section 8 of [OpenID.Federation-1.1].

9. Obtaining Federation Entity Configuration Information

Entity Configurations are obtained in this specification as specified in Section 9 of [OpenID.Federation-1.1].

10. Resolving the Trust Chain and Metadata

Trust Chains are resolved in this specification as specified in Section 10 of [OpenID.Federation-1.1].

11. Updating Metadata, Key Rollover, and Revocation

Entity Statements and Keys are updated in this specification as specified in Section 11 of [OpenID.Federation-1.1].

12. OpenID Connect Client Registration

This section describes how the mechanisms defined in this specification can be used to establish trust between an RP and an OP that have no prior explicit configuration or registration between them. It defines two client registration methods, Automatic Registration and Explicit Registration, that use Trust Chains, per Section 10. Federations can use other appropriate methods for client registration.

Federations with OpenID Connect Entities SHOULD agree on the supported client registration methods.

Note that both Automatic Registration and Explicit Registration can also be used for OAuth 2.0 profiles other than OpenID Connect. To do so, rather than using the Entity Type Identifiers openid_relying_party and openid_provider, one would instead use the Entity Type Identifiers oauth_client and oauth_authorization_server, or possibly other Entity Type Identifiers defined for the specific OAuth 2.0 profile being used.

When using both methods, trust_anchor_hints values can be used to determine Trust Anchors that the RP and OP share. When building Trust Chains, RPs SHOULD choose a Trust Anchor in common with the OP, when possible.

12.1. Automatic Registration

Automatic Registration enables an RP to make Authentication Requests without a prior registration step with the OP. The OP resolves the RP's Entity Configuration from the Client ID in the Authentication Request, following the process defined in Section 10.

The RP MUST perform Trust Chain and metadata resolution for the OP, as specified in Section 10 before it sends the Authentication Request. If the resolution is not successful, the RP MUST NOT attempt further interactions with the OP.

Automatic Registration has the following characteristics:

  • In all interactions with the OP, the RP employs its Entity Identifier as the Client ID. The OP retrieves the RP's Entity Configuration from the URL derived from the Entity Identifier, as described in Section 9.

  • Since there is no registration step prior to the Authentication Request, asymmetric cryptography MUST be used to authenticate requests when using Automatic Registration. Asymmetric cryptography is used to authenticate requests; therefore, the OP neither assigns a Client Secret to the RP nor returns it as a result of the registration process.

An OP that supports Automatic Registration MUST include the automatic keyword in its client_registration_types_supported metadata parameter.

12.1.1. Authentication Request

The Authentication Request is performed by passing a Request Object by value or by reference, as described in Section 6 of OpenID Connect Core 1.0 [OpenID.Core] and The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR) [RFC9101], or using a pushed authorization request, as described in Pushed Authorization Requests [RFC9126].

Authentication requests MUST demonstrate that the requesting Entity controls the Entity's RP keys, using one of the methods described below. Attempted authentication requests that do not do so MUST be rejected.

Deployments MAY choose not to support passing the request object by reference (using the request_uri request parameter) because allowing this would make it easier for attackers to mount denial of service attacks against OAuth 2.0 Authorization Servers or OpenID Providers. They can do this by using the request_uri_parameter_supported OP metadata parameter with the value false. If the request parameters are too large to practically be passed by value as query parameters, the request parameters can instead be sent via HTTP POST or a Pushed Authorization Request [RFC9126], as described in Section 12.1.1.2.

12.1.1.1. Using a Request Object

When a Request Object is used at the Authorization Endpoint or the Pushed Authorization Request Endpoint, the value of the request parameter is a JWT whose Claims are the request parameters specified in Section 3.1.2 in OpenID Connect Core 1.0 [OpenID.Core]. The JWT MUST be signed and MAY be encrypted. The following parameters are used in the Request Object:

aud
REQUIRED. The "aud" (audience) value MUST be the Entity Identifier of the OP and MUST NOT include any other values.
client_id
REQUIRED. The client_id value MUST be the RP's Entity Identifier.
iss
REQUIRED. The iss value MUST be the RP's Entity Identifier.
sub
MUST NOT be present. This prevents reuse of the statement for private_key_jwt client authentication.
jti
REQUIRED. JWT ID. A unique identifier for the JWT, which can be used to prevent reuse of the Request Object. A Request Object MUST only be used once, unless conditions for reuse were negotiated between the parties; any such negotiation is beyond the scope of this specification.
exp
REQUIRED. Number. Expiration time after which the JWT MUST NOT be accepted for processing. This is expressed as Seconds Since the Epoch, per [RFC7519].
iat
OPTIONAL. Number. Time when this Request Object was issued. This is expressed as Seconds Since the Epoch, per [RFC7519].
trust_chain

OPTIONAL. Array containing the sequence of Entity Statements that comprise the Trust Chain between the RP making the request and the selected Trust Anchor. When the RP and the OP are part of the same federation, the RP MUST select a Trust Anchor that it has in common with the OP; otherwise, the RP is free to select the Trust Anchor to use.

NOTE: The use of the trust_chain header parameter, as specified in Section 4.3 of [OpenID.Federation-1.1], is RECOMMENDED over the use of this parameter; it is retained for historical reasons.

12.1.1.1.1. Authorization Request with a Trust Chain

When the trust_chain header parameter is used in the authentication request, the Relying Party informs the OP of the sequence of Entity Statements that proves the trust relationship between it and the selected Trust Anchor.

Due to the large size of a Trust Chain, it may be necessary to use the HTTP POST method, a request_uri, or a Pushed Authorization Request [RFC9126] for the request.

The following is a non-normative example of the header parameters and JWT Claims Set in a Request Object:

{
  "typ": "oauth-authz-req+jwt",
  "alg": "RS256",
  "kid": "that-kid-which-points-to-a-jwk-contained-in-the-trust-chain",
  "trust_chain" : [
    "eyJhbGciOiJSUzI1NiIsImtpZCI6Ims1NEhRdERpYnlHY3M5WldWTWZ2aUhm ...",
    "eyJhbGciOiJSUzI1NiIsImtpZCI6IkJYdmZybG5oQU11SFIwN2FqVW1BY0JS ...",
    "eyJhbGciOiJSUzI1NiIsImtpZCI6IkJYdmZybG5oQU11SFIwN2FqVW1BY0JS ..."
  ]
}
.
{
  "aud": "https://op.example.org",
  "client_id": "https://rp.example.com",
  "exp": 1589699162,
  "iat": 1589699102,
  "iss": "https://rp.example.com",
  "jti": "4d3ec0f81f134ee9a97e0449be6d32be",
  "nonce": "4LX0mFMxdBjkGmtx7a8WIOnB",
  "redirect_uri": "https://rp.example.com/authz_cb",
  "response_type": "code",
  "scope": "openid profile email address phone",
  "state": "YmX8PM9I7WbNoMnnieKKBiptVW0sP2OZ"
}
Figure 3: Request Object JWT Claims Set

The following is a non-normative example of an Authentication Request using the request parameter (with line wraps within values for display purposes only):

Host: server.example.com
GET /authorize?
    redirect_uri=https%3A%2F%2Frp.example.com%2Fauthz_cb
    &scope=openid+profile+email+address+phone
    &response_type=code
    &client_id=https%3A%2F%2Frp.example.com
    &request=eyJ0eXAiOiJvYXV0aC1hdXRoei1yZXErand0IiwiYWxnIjoiUlMyNTYiLCJ
        raWQiOiJOX19EOThJdkI4TmFlLWt3QTZuck90LWlwVGhqSGtEeDM3bmljRE1IM04
        0In0.
        eyJhdWQiOiJodHRwczovL29wLmV4YW1wbGUub3JnIiwiY2xpZW50X2lkIjoiaHR0
        cHM6Ly9ycC5leGFtcGxlLmNvbSIsImV4cCI6MTU4OTY5OTE2MiwiaWF0IjoxNTg5
        Njk5MTAyLCJpc3MiOiJodHRwczovL3JwLmV4YW1wbGUuY29tIiwianRpIjoiNGQz
        ZWMwZjgxZjEzNGVlOWE5N2UwNDQ5YmU2ZDMyYmUiLCJub25jZSI6IjRMWDBtRk14
        ZEJqa0dtdHg3YThXSU9uQiIsInJlZGlyZWN0X3VyaSI6Imh0dHBzOi8vcnAuZXhh
        bXBsZS5jb20vYXV0aHpfY2IiLCJyZXNwb25zZV90eXBlIjoiY29kZSIsInNjb3Bl
        Ijoib3BlbmlkIHByb2ZpbGUgZW1haWwgYWRkcmVzcyBwaG9uZSIsInN0YXRlIjoi
        WW1YOFBNOUk3V2JOb01ubmllS0tCaXB0Vlcwc1AyT1oiLCJ0cnVzdF9jaGFpbiI6
        WyJleUpoYkdjaU9pSlNVekkxTmlJc0ltdHBaQ0k2SW1zMU5FaFJkRVJwWW5sSFkz
        TTVXbGRXVFdaMmFVaG0gLi4uIiwiZXlKaGJHY2lPaUpTVXpJMU5pSXNJbXRwWkNJ
        NklrSllkbVp5Ykc1b1FVMTFTRkl3TjJGcVZXMUJZMEpTIC4uLiIsImV5SmhiR2Np
        T2lKU1V6STFOaUlzSW10cFpDSTZJa0pZZG1aeWJHNW9RVTExU0ZJd04yRnFWVzFC
        WTBKUyAuLi4iXX0.
        Rv0isfuku0FcRFintgxgKDk7EnhFkpQRg3Tm6N6fCHAHEKFxVVdjy4
        9JboJtxKcQVZKN9TKn3lEYM1wtF1e9PQrNt4HZ21ICfnzxXuNx1F5SY1GXCU2n2y
        FVKtz3N0YkAFbTStzy-sPRTXB0stLBJH74RoPiLs2c6dDvrwEv__GA7oGkg2gWt6
        VDvnfDpnvFi3ZEUR1J8MOeW_VFsayrT9sNjyjsz62Po4LzvQKQMKxq0dNwPNYuuS
        fUmb-YvmFguxDb3weYl8WS-
        48EIkP1h4b_KGU9x9n7a1fUOHrS02ATQZmaL8jUil7yLJqx5MiCsPr4pCAXV0doA
        4pwhs_FIw HTTP/1.1
Figure 4: Authentication Request using Request Object

When the trust_chain header parameter is included, the peer_trust_chain header parameter MAY also be included to provide a Trust Chain between the OP and the Trust Anchor the RP selected. The Peer Trust Chain contains metadata and policy values that the RP has chosen for the OP to use during the registration. The Trust Anchors selected in both Trust Chains MUST be the same. Inclusion of both Trust Chains enables achieving the Federation Integrity and Metadata Integrity properties, as defined in [App-Fed-Linkage].

12.1.1.1.2. Processing the Authentication Request

When the OP receives an incoming Authentication Request, the OP supports OpenID Federation, the incoming Client ID is a valid URL, and the OP does not have the Client ID registered as a known client, then the OP SHOULD resolve the Trust Chains related to the requestor.

An RP MAY include a Trust Chain from itself to the Trust Anchor that it selected in the Request Object using the trust_chain header parameter defined in Section 4.3 of [OpenID.Federation-1.1]. If the OP does not have a valid registration for the RP or its registration has expired, the OP MAY use the received Trust Chain as a hint for which path to take from the RP's Entity to the Trust Anchor. The OP MAY evaluate the statements in the provided Trust Chain to make its Federation Entity Discovery procedure more efficient, especially if the RP contains multiple authority hints in its Entity Configuration. If the OP already has a valid registration for the RP, it MAY use the received Trust Chain to update the RP's registration.

A Trust Chain may be relied upon by the OP because it has validated all of its statements. This is true whether these statements are retrieved from their URLs or whether they are provided via the trust_chain request parameter in the Request Object. In both cases, the OP MUST fully verify the Trust Chain including every Entity Statement contained in it.

The RP MAY likewise include a Trust Chain from the OP to the Trust Anchor that the RP selected in the Request Object using the peer_trust_chain header parameter defined in Section 4.4 of [OpenID.Federation-1.1]. The OP SHOULD use the metadata and policy values that the RP has chosen during the registration. Inclusion of both Trust Chains enables achieving the Federation Integrity and Metadata Integrity properties, as defined in [App-Fed-Linkage].

If the RP does not include the trust_chain header parameter in the Request Object, the OP for some reason decides not to use the provided Trust Chain, or the OP does not support this feature, it then MUST validate the possible Trust Chains, starting with the RP's Entity Configuration, as described in Section 10.1 of [OpenID.Federation-1.1], and resolve the RP metadata with Entity Type openid_relying_party.

The OP SHOULD furthermore verify that the Resolved Metadata of the RP complies with the client metadata specification OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration].

Once the OP has the RP's metadata, it MUST verify that the client was actually the one sending the Authentication Request by verifying the signature of the Request Object using the key material the client published in its metadata for the openid_relying_party Entity Type. If the signature does not verify, the OP MUST reject the request.

12.1.1.2. Using Pushed Authorization

Pushed Authorization Requests [RFC9126] provide an interoperable way to push authentication request parameters directly to the AS in exchange for a one-time-use request_uri. The standard PAR metadata parameters are used in the RP and OP metadata to indicate its use.

When using PAR with Automatic Registration, either a Request Object MUST be used as a PAR parameter, with the Request Object being as described in Section 12.1.1.1, or a client authentication method for the PAR endpoint MUST be used that proves possession of one of the RP's private keys. Furthermore, the corresponding public key MUST be in the Entity's RP JWK Set [RFC7517].

The two applicable PAR client authentication methods are:

  • JWT Client authentication, as described for private_key_jwt in Section 9 of OpenID Connect Core 1.0 [OpenID.Core]. In this case, the audience of the client authentication JWT MUST be the Entity Identifier of the OP and MUST NOT include any other values.

  • mTLS using self-signed certificates, as described in Section 2.2 of [RFC8705]. In this case, the self-signed certificate MUST be present as the value of an x5c Claim for a key in the Entity's RP JWK Set. In this case, the server MUST omit certificate chain validation.

A Pushed Authorization Request to the OP could look like this:

POST /par HTTP/1.1
Host: op.example.org
Content-Type: application/x-www-form-urlencoded

redirect_uri=https%3A%2F%2Frp.example.com%2Fauthz_cb
&scope=openid+profile+email+address+phone
&response_type=code
&nonce=4LX0mFMxdBjkGmtx7a8WIOnB
&state=YmX8PM9I7WbNoMnnieKKBiptVW0sP2OZ
&client_id=https%3A%2F%2Frp.example.com
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3A
  client-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6ImRVTjJ
  hMDF3Umtoa1NXcGxRVGh2Y1ZCSU5VSXdUVWRPVUZVMlRtVnJTbW
  hFUVhnelpYbHBUemRRTkEifQ.
  eyJzdWIiOiAiaHR0cHM6Ly9ycC5leGFtcGxlLmNvbSIsICJpc3M
  iOiAiaHR0cHM6Ly9ycC5leGFtcGxlLmNvbSIsICJpYXQiOiAxNT
  g5NzA0NzAxLCAiZXhwIjogMTU4OTcwNDc2MSwgImF1ZCI6ICJod
  HRwczovL29wLmV4YW1wbGUub3JnIiwgImp0aSI6ICIzOWQ1YWU1
  NTJkOWM0OGYwYjkxMmRjNTU2OGVkNTBkNiJ9.
  oUt9Knx_lxb4V2S0tyNFH
  CNZeP7sImBy5XDsFxv1cUpGkAojNXSy2dnU5HEzscMgNW4wguz6
  KDkC01aq5OfN04SuVItS66bsx0h4Gs7grKAp_51bClzreBVzU4g
  _-dFTgF15T9VLIgM_juFNPA_g4Lx7Eb5r37rWTUrzXdmfxeou0X
  FC2p9BIqItU3m9gmH0ojdBCUX5Up0iDsys6_npYomqitAcvaBRD
  PiuUBa5Iar9HVR-H7FMAr7aq7s-dH5gx2CHIfM3-qlc2-_Apsy0
  BrQl6VePR6j-3q6JCWvNw7l4_F2UpHeanHb31fLKQbK-1yoXDNz
  DwA7B0ZqmuSmMFQ
Figure 5: Pushed Authorization Request to the OP
12.1.1.2.1. Processing the Pushed Authentication Request

The requirements specified in Section 12.1.1.1.2 also apply to Pushed Authorization Requests [RFC9126].

Once the OP has the RP's metadata, it MUST verify the client is using the keys published for the openid_relying_party Entity Type Identifier. If the RP does not verify, the OP MUST reject the request.

The means of verification depends on the client authentication method used:

private_key_jwt
If this method is used, then the OP verifies the signature of the signed JWT using the key material published by the RP in its metadata. If the authentication is successful, then the registration is valid. The audience of the signed JWT MUST be the Authorization Server's Entity Identifier and MUST NOT include any other values.
self_signed_tls_client_auth
If mTLS is used with a self-signed certificate, then the certificate MUST be present as the value of an x5c Claim for a key in the JWK Set containing the RP's keys.

12.1.2. Successful Authentication Response

The response to a successful authentication request when using Automatic Registration is the same as the successful authentication responses defined in [OpenID.Core]. It is a successful OAuth 2.0 authorization response sent to the Client's redirection URI.

12.1.3. Authentication Error Response

The error response to an unsuccessful authentication request when using Automatic Registration is the same as the error authentication responses defined in [OpenID.Core]. It is an OAuth 2.0 authorization error response sent to the Client's redirection URI, unless a Pushed Authorization Request [RFC9126] was used for the request.

However, as in both [OpenID.Core] and [RFC6749], if the redirection URI is invalid, redirection MUST NOT be performed, and instead the Authorization Server SHOULD inform the End-User of the error in the user interface. The Authorization Server MAY also choose to do this if it has reason to believe that the redirection URI might be being used as a component of an open redirector.

If the OP fails to establish trust with the RP or finds the RP metadata to be invalid or in conflict with metadata policy, it MUST treat the redirection URI as invalid and not perform redirection. This means that the error codes invalid_trust_anchor, invalid_trust_chain, and invalid_metadata, which are about reasons trust failed to be established, SHOULD only be returned in Pushed Authorization Request [RFC9126] error responses, and not to the Client's redirection URI.

In addition to the error codes contained in the IANA "OAuth Extensions Error Registry" registry [IANA.OAuth.Parameters], this specification also uses the error codes defined in Section 8.9 of [OpenID.Federation-1.1].

The following is a non-normative example authentication error response:

HTTP/1.1 302 Found
  Location: https://client.example.org/cb?
    error=consent_required
    &error_description=
      Consent%20by%20the%20End-User%20required
    &state=af0ifjsldkj
Figure 6: Authentication Error Response

12.1.4. Automatic Registration and Client Authentication

Note that when using Automatic Registration, the client authentication methods that the client can use are declared to the OP using RP Metadata parameters: either the token_endpoint_auth_methods_supported parameter defined in [OpenID.RP.Choices] or the token_endpoint_auth_method parameter. Those that the OP can use are likewise declared to the RP using OP Metadata parameters. However, if there are multiple methods supported by both the RP and the OP, the OP does not know which one the RP will pick in advance of it being used, since this is not declared at the time the Automatic Registration occurs.

OPs SHOULD accept any client authentication method that is mutually supported and RPs MUST only use mutually supported methods. Because some OPs may be coded in such a way that they expect the RP to always use the same client authentication method for subsequent interactions, note that interoperability may be improved by the RP doing so.

12.1.5. Possible Other Uses of Automatic Registration

Automatic Registration is designed to be able to be employed for OAuth 2.0 use cases beyond OpenID Connect, as noted in Section 12. For instance, ecosystems using bare OAuth 2.0 [RFC6749] or FAPI [FAPI] can utilize Automatic Registration.

Also note that Client ID values that are Entity Identifiers could be used to identify clients using Automatic Registration at endpoints other than the Authorization Endpoint and Token Endpoint in OAuth 2.0 deployments, such as the Pushed Authorization Request (PAR) Endpoint and Introspection Endpoint. Describing particular such scenarios is beyond the scope of this specification.

12.2. Explicit Registration

Using this method, the RP establishes its client registration with the OP by means of a dedicated registration request, similar to [OpenID.Registration], but instead of its metadata, the RP submits its Entity Configuration or an entire Trust Chain. When the Explicit Registration is completed, the RP can proceed to make regular OpenID authentication requests to the OP.

An OP that supports Explicit Registration MUST include the explicit keyword in its client_registration_types_supported metadata parameter and set the federation_registration_endpoint metadata parameter to the URL at which it receives Explicit Registration requests.

Explicit Registration is suitable for implementation on top of the OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration] endpoint of an OP deployment. In contrast to Automatic Registration, it enables an OP to provision a Client ID, potentially a Client Secret, and other metadata parameters.

An example of an Explicit Registration is provided in Appendix A.3.2.

12.2.1. Explicit Client Registration Request

The RP performs Explicit Client Registration as follows:

  1. Once the RP has determined a set of Trust Anchors it has in common with the OP, it chooses the subset it wants to proceed with. This may be a single Trust Anchor, or it can also be more than one. The RP MUST perform Trust Chain and metadata resolution for the OP, as specified in Section 10. If the resolution is not successful, the RP MUST abort the request.

  2. Using this subset of Trust Anchors, the RP chooses a set of authority_hints from the hints that are available to it. Each hint MUST, when used as a starting point for Trust Chain collection, lead to at least one of the Trust Anchors in the subset. If the RP has more than one Trust Anchor in common with the OP it MUST select a subset of Trust Anchors to proceed with. The subset may be as small as a single Trust Anchor, or include multiple ones.

  3. The RP will then construct its Entity Configuration, where the metadata statement chosen is influenced by the OP's metadata and where the authority_hints included are picked by the process described above. From its Immediate Superiors, the RP MUST select one or more authority_hints so that every hint, when used as the starting point for a Trust Chain collection, leads to at least one of the Trust Anchors in the subset selected above.

  4. The RP MAY include its Entity Configuration in a Trust Chain regarding itself. There are two ways to do this. The first way is for the Registration Request to contain an array with the sequence of Entity Statements that compose the Trust Chain between the RP that is making the request and the selected Trust Anchor. The second way is to use the trust_chain header parameter, as specified in Section 4.3 of [OpenID.Federation-1.1].

    NOTE: The use of the trust_chain header parameter in the request JWT is RECOMMENDED over the first syntax; it is retained for historical reasons.

  5. The RP MUST include its metadata in its Entity Configuration and use the authority_hints selected above.

    The RP SHOULD select its metadata parameters to comply with the OP's Resolved Metadata and thus ensure a successful registration with the OP. Note that if the submitted RP metadata is not compliant with the metadata of the OP, the OP may choose to modify it to make it compliant rather than reject the request with an error response.

  6. The Entity Configuration, or the entire Trust Chain, is sent, using HTTP POST, to the federation_registration_endpoint. The Entity Configuration or Trust Chain is the entire POST body. The RP MUST sign its Entity Configuration with a current Federation Entity Key in its possession.

  7. The content type of the Registration Request MUST be application/entity-statement+jwt when it is the Entity Configuration of the requestor. Otherwise, when it is a Trust Chain, the content type of the Registration Request MUST be application/trust-chain+json. The RP MAY include its Entity Configuration in a Trust Chain that leads to the RP. In this case, the registration request will contain an array consisting of the sequence of statements that make up the Trust Chain between the RP and the Trust Anchor the RP selected.

  8. The trust_chain header parameter MAY be included to provide a Trust Chain between the RP and the Trust Anchor the RP selected when the request is the Entity Configuration of the RP. This is equivalent to providing the Trust Chain as the request body. When the trust_chain header parameter is included, the peer_trust_chain header parameter MAY also be included to provide a Trust Chain between the OP and the Trust Anchor the RP selected. The Peer Trust Chain contains metadata and policy values that the RP has chosen for the OP to use during the registration. The peer_trust_chain header parameter MUST NOT be used when the request body is a Trust Chain. The Trust Anchors selected in both Trust Chains MUST be the same. Inclusion of both Trust Chains enables achieving the Federation Integrity and Metadata Integrity properties, as defined in [App-Fed-Linkage].

The following Entity Configuration Claims are specified for use in Explicit Registration requests. Their full descriptions are in Section 3.

iss
REQUIRED. Its value MUST be the Entity Identifier of the RP.
sub
REQUIRED. Its value MUST be the Entity Identifier of the RP.
iat
REQUIRED.
exp
REQUIRED.
jwks
REQUIRED.
aud
REQUIRED. The "aud" (audience) value MUST be the Entity Identifier of the OP and MUST NOT include any other values. This Claim is used in Explicit Registration requests; it is not a general Entity Statement Claim.
authority_hints
REQUIRED.
metadata
REQUIRED. It MUST contain the RP metadata under the openid_relying_party Entity Type Identifier.
crit
OPTIONAL.
trust_marks
OPTIONAL.

The request MUST be an HTTP request to the federation_registration_endpoint of the OP, using the POST method.

When the RP submits an Entity Configuration the content type of the request MUST be application/entity-statement+jwt. When the RP submits a Trust Chain, the content type MUST be application/trust-chain+json.

12.2.2. Processing Explicit Client Registration Request by OP

The OP processes the request as follows:

  1. Upon receiving a registration request, the OP MUST inspect the content type to determine whether it contains an Entity Configuration or an entire Trust Chain.

  2. The OP MUST validate the RP's explicit registration request JWT. All the normal Entity Statement validation rules apply. In addition, if the aud (audience) Claim Value is not the Entity Identifier of the OP, then the request MUST be rejected.

  3. If no Trust Chain is provided from the RP to the Trust Anchor in the request, the OP MUST use the provided Entity Configuration to complete the Federation Entity Discovery by collecting and evaluating the Trust Chains that start with the authority_hints in the Entity Configuration of the RP. After validating at least one Trust Chain, the OP MUST verify the signature of the received Entity Configuration. If the OP finds more than one acceptable Trust Chain, it MUST choose one Trust Chain from among them as the one to proceed with.

  4. If the request body is a Trust Chain, the OP MAY evaluate the statements in the Trust Chain to save the HTTP calls that are necessary to perform the Federation Entity Discovery, especially if the RP included more than one authority hint in its Entity Configuration. Otherwise, the OP MUST extract the RP's Entity Configuration from the Trust Chain and proceed according to Step 3, as if only an Entity Configuration was received.

  5. When a Trust Chain is provided using the trust_chain header parameter in the request's Entity Configuration, the OP MAY likewise evaluate the statements in the Trust Chain to save the HTTP calls that are necessary to perform the Federation Entity Discovery. Note that in this case, the RP's Entity Configuration in the Trust Chain is only used to establish that there is a path from the RP to the Trust Anchor; it is the metadata, etc. in the request Entity Configuration, which may be tailored by the RP for the OP, that is used when processing the registration request. If the provided Trust Chain is not used, the OP MUST proceed according to Step 3, using the request Entity Configuration.

  6. If the request uses the peer_trust_chain header parameter to include a Trust Chain from the OP to the Trust Anchor that the RP selected, verify that it begins at the OP. Furthermore, verify that it ends at the same Trust Anchor as any provided Trust chain from the RP to the Trust Anchor. The OP SHOULD use the metadata and policy values that the RP has chosen during the registration.

  7. At this point, if the OP finds that it already has an existing client registration for the requesting RP, then that registration MUST be invalidated. The precise time of the invalidation is at the OP's discretion, as the OP may want to ensure the completion of concurrent OpenID authentication requests initiated by the RP while the registration request is being processed.

    The OP MAY retain client credentials and key material from the invalidated registration in order to verify past RP signatures and perform other cryptographic operations on past RP data.

  8. The OP uses the Resolved Metadata for the RP to create a client registration compliant with its own OP metadata and other applicable policies.

    The OP MAY provision the RP with a client_id other than the RP's Entity Identifier. This enables Explicit Registration to be implemented on top of the OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration] endpoint of an OP.

    If the RP is provisioned with a client_secret it MUST NOT expire before the expiration of the registration Entity Statement that will be returned to the RP.

    The OP SHOULD NOT provision the RP with a registration_access_token and a registration_client_uri because the expected way for the RP to update its registration is to make a new Explicit Registration request. If the RP is provisioned with a registration_access_token for some purpose, for example, to let it independently check its registered metadata, the token MUST NOT allow modification of the registration.

    The OP MAY modify the received RP metadata, for example, by substituting an invalid or unsupported parameter, to make it compliant with its own OP metadata and other policies. If the OP does not accept the RP metadata or is unwilling to modify it to make it compliant, it MUST return a client registration error response, with an appropriate error, such as invalid_client_metadata or invalid_redirect_uri, as specified in Section 3.3 of [OpenID.Registration].

  9. The OP MUST assign an expiration time to the created registration. This time MUST NOT exceed the expiration time of the Trust Chain that the OP selected to process the request.

12.2.3. Successful Explicit Client Registration Response

If the OP created a client registration for the RP, it MUST then construct a success response in the form of an Entity Statement.

The OP MUST set the trust_anchor Claim of the Entity Statement to the Trust Anchor it selected to process the request. The authority_hints Claim MUST be set to the RP's Immediate Superior in the selected Trust Chain.

The OP MUST set the exp Claim to the expiration time of the created registration. The OP MAY choose to invalidate the registration before that, as explained in Section 12.2.6.

The OP MUST express the client registration it created for the RP by means of the metadata Claim, by placing the metadata parameters under the openid_relying_party Entity Type Identifier. The parameters MUST include the client_id that was provisioned for the RP. If the RP was provisioned with credentials, for example, a client_secret, these MUST be included as well.

The OP SHOULD include metadata parameters that have a default value, for example token_endpoint_auth_method which has a default value of client_secret_basic, to simplify the processing of the response by the RP.

The OP MUST sign the registration Entity Statement with a current Federation Entity Key in its possession.

The following Entity Statement Claims are used in Explicit Registration responses, as specified in Section 3:

iss
REQUIRED. Its value MUST be the Entity Identifier of the OP.
sub
REQUIRED. Its value MUST be the Entity Identifier of the RP.
iat
REQUIRED. Time when this statement was issued.
exp
REQUIRED. Expiration time after which the statement MUST NOT be accepted for processing.
jwks
OPTIONAL. If present, it MUST be a verbatim copy of the jwks Entity Statement Claim from the received Entity Configuration of the RP. Note that this is distinct from the identically named RP metadata parameter.
aud
REQUIRED. The "aud" (audience) value MUST be the Entity Identifier of the RP and MUST NOT include any other values. This Claim is used in Explicit Registration responses; it is not a general Entity Statement Claim.
trust_anchor
REQUIRED. Its value MUST be the Entity Identifier of the Trust Anchor that the OP selected to process the Explicit Registration request. If complete Trust Chains to the Trust Anchor selected by the RP were provided in the request and/or by using the peer_trust_chain header parameter, this MUST match the Trust Anchors at the roots of those Trust Chains. This Claim is specific to Explicit Registration responses; it is not a general Entity Statement Claim.
authority_hints
REQUIRED. It MUST be a single-element array, whose value references the Immediate Superior of the RP in the Trust Chain that the OP selected to process the request.
metadata
REQUIRED. It MUST contain the registered RP metadata under the openid_relying_party Entity Type Identifier.
crit
OPTIONAL. Set of Claims that MUST be understood and processed, as specified in Section 3.1 of [OpenID.Federation-1.1].

A successful response MUST have an HTTP status code 200 and the content type application/explicit-registration-response+jwt. Furthermore, the typ header parameter value in the response MUST be explicit-registration-response+jwt (and not entity-statement+jwt) to prevent cross-JWT confusion between the Explicit Registration response and other kinds of Entity Statements, per Section 3.11 of [RFC8725].

12.2.4. Explicit Client Registration Error Response

For a client registration error, the response is as defined in Section 8.9 of [OpenID.Federation-1.1] and MAY use errors defined there and in Section 3.3 of [OpenID.Registration] and Section 3.2.2 of [RFC7591].

12.2.5. Processing Explicit Client Registration Response by RP

  1. If the response indicates success, the RP MUST verify that its content is a valid Entity Statement and issued by the OP.

    The RP MUST ensure the signing Federation Entity Key used by the OP is present in the jwks Claim of the Subordinate Statement issued by the OP's Immediate Superior in a Trust Chain that the RP successfully resolved for the OP when it prepared the Explicit Registration request.

  2. The RP MUST verify that the aud (audience) Claim Value is its Entity Identifier.

  3. The RP MUST verify that the trust_anchor represents one of its own Trust Anchors. If complete Trust Chains to the Trust Anchor selected by the RP were provided in the request and/or by using the peer_trust_chain header parameter, the RP MUST verify that this matches the Trust Anchors at the root of those Trust Chains.

  4. The RP MUST verify that at least one of the authority_hints it specified in the Explicit Registration request leads to the Trust Anchor that the OP set in the trust_anchor Claim.

  5. The RP MUST first ensure that the information it was registered with at the OP contains the same set of Entity Types as the request does. After having collected a Trust Chain using the response Claim trust_anchor as the Entity Identifier for the Trust Anchor and authority_hints as starting points for the Trust Chain collection, the RP SHOULD verify that the response metadata for each entity type is valid by applying the resolved policies to the received metadata, as specified in Section 6.1.4.1 of [OpenID.Federation-1.1].

  6. If the received registration Entity Statement does not pass the above checks, the RP MUST reject it. The RP MAY choose to retry the Explicit Registration request to work around a transient exception, for example, due to a recent change of Entity metadata or metadata policy causing temporary misalignment of metadata.

12.2.6. Explicit Client Registration Lifetime

An RP can utilize the exp Claim of the registration Entity Statement to devise a suitable strategy for renewing its client registration. RP implementers should note that if the the RP's registration has expired at the OP, this can cause OpenID Connect authentication requests, token requests, and/or UserInfo requests to fail. Renewing the RP's registration prior to its expiration can prevent such errors from occurring and ensure the end-user experience is not disrupted.

An OP MAY invalidate a client registration before the expiration that is indicated in the registration Entity Statement for the RP. An example reason could be the OP leaving the federation that was used to register the RP.

12.3. Registration Validity and Trust Reevaluation

The validity of an Automatic or Explicit Registration at an OP MUST NOT exceed the lifetime of the Trust Chain the OP used to create the registration. An OP MAY choose to expire the registration at some earlier time, or choose to perform additional periodic reevaluations of the Trust Chain for the registered RP before the Trust Chain reaches its expiration time.

Similarly, an RP that obtained an Automatic or Explicit Registration MUST NOT use it past the expiration of the Trust Chain the RP used to establish trust in the OP. For an RP using Automatic Registration, the trust in the OP MUST be successfully reevaluated before continuing to make requests to the OP. For an RP using Explicit Registration, the RP MUST successfully renew its registration. An RP MAY choose to perform additional periodic reevaluations of the Trust Chain for the OP before the Trust Chain reaches its expiration time.

12.4. Differences between Automatic Registration and Explicit Registration

The primary differences between Automatic Registration and Explicit Registration are:

  • With Automatic Registration, there is no registration step prior to the Authentication Request, whereas with Explicit Registration, there is. (OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration] and OAuth 2.0 Dynamic Client Registration [RFC7591] also employ a prior registration step.)

  • With Automatic Registration, the Client ID value is the RP's Entity Identifier and is supplied to the OP by the RP, whereas with Explicit Registration, a Client ID is assigned by the OP and supplied to the RP.

  • With Automatic Registration, the Client is authenticated by means of the RP proving that it controls a private key corresponding to one of its Entity Configuration's public keys. Whereas with Explicit Registration, a broader set of options is available for authenticating the Client, including the use of a Client Secret.

12.5. Rationale for Trust Chains in the Request

Both Automatic and Explicit Client Registration support the submission of the Trust Chain embedded in the Request, calculated by the requestor, and related to itself. This provides the following benefits:

  • It solves the problem of OPs using RP metadata that has become stale. This stale data may occur when the OP uses cached RP metadata from a Trust Chain that has not reached its expiration time yet. The RP MAY notify the OP that a change has taken place by including the trust_chain header parameter or the trust_chain request parameter in the request, thus letting the OP update its Client Registration and preventing potential temporary faults due to stale metadata.

  • It enables the RP to pass a verifiable hint for which trust path to take to build the Trust Chain. This can reduce the costs of RP Federation Entity Discovery for OPs in complex federations where the RP has multiple Trust Anchors or the Trust Chain resolution may result in dead-ends.

  • It enables direct passing of the Entity Configuration, including any present Trust Marks, thus saving the OP from having to make an HTTP request to the RP /.well-known/openid-federation endpoint.

Both also support the submission of the Peer Trust Chain, which provides a Trust Chain between the OP and the Trust Anchor the RP selected. As described in Section 4.4 of [OpenID.Federation-1.1], inclusion of both Trust Chains enables achieving the Federation Integrity and Metadata Integrity properties, as defined in [App-Fed-Linkage].

13. General-Purpose JWT Claims

This specification defines no general-purpose JWT Claims. Those defined in Section 13 of [OpenID.Federation-1.1] are used by this specification.

14. Claims Languages and Scripts

Human-readable Claim Values and Claim Values that reference human-readable values MAY be represented in multiple languages and scripts. This specification enables such representations in the same manner as defined in Section 5.2 of OpenID Connect Core 1.0 [OpenID.Core].

As described in OpenID Connect Core, to specify the languages and scripts, BCP47 [RFC5646] language tags are added to member names, delimited by a # character. For example, family_name#ja-Kana-JP expresses the Family Name in Katakana in Japanese, which is commonly used to index and represent the phonetics of the Kanji representation of the same name represented as family_name#ja-Hani-JP.

Language tags can be used in any data structures containing or referencing human-readable values, including metadata parameters and Trust Mark parameters. For instance, both organization_name and organization_name#de might occur together in metadata.

15. Media Types

This media type [RFC2046] is defined by this specification.

15.1. "application/explicit-registration-response+jwt" Media Type

The application/explicit-registration-response+jwt media type is used to specify that the associated content is an Explicit Registration response, as defined in Section 12.2.3. No parameters are used with this media type.

16. String Operations

Processing some OpenID Federation messages requires comparing values in the messages to other values. For example, the Entity Identifier in an iss Claim might be compared to the Entity Identifier in a sub Claim. Comparing Unicode [UNICODE] strings, however, has significant security implications.

Therefore, comparisons between JSON strings and other Unicode strings MUST be performed as specified below:

  1. Remove any JSON applied escaping to produce an array of Unicode code points.

  2. Unicode Normalization [USA15] MUST NOT be applied at any point to either the JSON string or to the string it is to be compared against.

  3. Comparisons between the two strings MUST be performed as a Unicode code point to code point equality comparison.

Note that this is the same comparison procedure as specified in Section 14 of OpenID Connect Core 1.0 [OpenID.Core].

17. Implementation Considerations

The Implementation Considerations described in Section 17 of [OpenID.Federation-1.1] apply to this specification.

18. Security Considerations

The Security Considerations described in Section 18 of [OpenID.Federation-1.1] apply to this specification. These additional Security Considerations also apply.

18.1. Denial-of-Service Attack Prevention

Some of the interfaces defined in this specification could be used for Denial-of-Service attacks (DoS), most notably, Explicit Client Registration (Section 12.2), and Automatic Client Registration (Section 12.1) can be exploited as vectors of HTTP propagation attacks. Below is an explanation of how such an attack can occur and the countermeasures to prevent it.

An adversary, providing hundreds of fake authority_hints in its Entity Configuration, could exploit the Federation Entity Discovery mechanism to propagate many HTTP requests. Imagine an adversary controlling an RP that sends an authorization request to an OP. For each request crafted by the adversary, the OP produces one request for the adversary's Entity Configuration and another one for each URL found in the authority_hints.

If these endpoints are provided, some adequate defense methods are required, such as those described below and in [RFC4732].

Entities may be required to include a Trust Chain in their requests, as explained in Section 12.1.1.1. The static Trust Chain gives a predefined trust path, meaning that Federation Entity Discovery need not be performed. In this case, the propagation attacks will be prevented since the Trust Chain can be statically validated with a public key of the Trust Anchor.

Passing request objects by reference (using the request_uri request parameter) may not be supported by some deployments, as described in Section 12.1.1, to eliminate a mechanism by which an attacker could otherwise require OPs to retrieve arbitrary content under the control of the attacker.

19. Privacy Considerations

The Privacy Considerations described in Section 19 of [OpenID.Federation-1.1] apply to this specification.

20. IANA Considerations

This specification makes no requests of IANA. It relies on the IANA registrations already made in Section 20 of [OpenID.Federation-1.0].

21. References

21.1. Normative References

[OpenID.Core]
Sakimura, N., Bradley, J., Jones, M.B., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0", , <https://openid.net/specs/openid-connect-core-1_0.html>.
[OpenID.Discovery]
Sakimura, N., Bradley, J., Jones, M.B., and E. Jay, "OpenID Connect Discovery 1.0", , <https://openid.net/specs/openid-connect-discovery-1_0.html>.
[OpenID.Federation-1.1]
Hedberg, R., Jones, M.B., Ed., De Marco, G., Solberg, A.Å., Bradley, J., and V. Dzhuvinov, "OpenID Federation 1.1", , <https://openid.github.io/federation-1.1/main.html>.
[OpenID.Registration]
Sakimura, N., Bradley, J., and M.B. Jones, "OpenID Connect Dynamic Client Registration 1.0", , <https://openid.net/specs/openid-connect-registration-1_0.html>.
[OpenID.RP.Choices]
Jones, M.B., Hedberg, R., Bradley, J., and F. Skokan, "OpenID Connect Relying Party Metadata Choices 1.0", , <https://openid.net/specs/openid-connect-rp-metadata-choices-1_0.html>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC4732]
Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet Denial-of-Service Considerations", RFC 4732, DOI 10.17487/RFC4732, , <https://www.rfc-editor.org/info/rfc4732>.
[RFC5646]
Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, , <https://www.rfc-editor.org/info/rfc5646>.
[RFC6749]
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/info/rfc6749>.
[RFC7515]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, , <https://www.rfc-editor.org/info/rfc7515>.
[RFC7516]
Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", RFC 7516, DOI 10.17487/RFC7516, , <https://www.rfc-editor.org/info/rfc7516>.
[RFC7517]
Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, , <https://www.rfc-editor.org/info/rfc7517>.
[RFC7519]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, , <https://www.rfc-editor.org/info/rfc7519>.
[RFC7591]
Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, , <https://www.rfc-editor.org/info/rfc7591>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC8414]
Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, , <https://www.rfc-editor.org/info/rfc8414>.
[RFC8705]
Campbell, B., Bradley, J., Sakimura, N., and T. Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens", RFC 8705, DOI 10.17487/RFC8705, , <https://www.rfc-editor.org/info/rfc8705>.
[RFC9101]
Sakimura, N., Bradley, J., and M. Jones, "The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR)", RFC 9101, DOI 10.17487/RFC9101, , <https://www.rfc-editor.org/info/rfc9101>.
[RFC9126]
Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", RFC 9126, DOI 10.17487/RFC9126, , <https://www.rfc-editor.org/info/rfc9126>.
[RFC9728]
Jones, M.B., Hunt, P., and A. Parecki, "OAuth 2.0 Protected Resource Metadata", RFC 9728, DOI 10.17487/RFC9728, , <https://www.rfc-editor.org/info/rfc9728>.
[UNICODE]
The Unicode Consortium, "The Unicode Standard", <http://www.unicode.org/versions/latest/>.
[USA15]
Whistler, K., "Unicode Normalization Forms", Unicode Standard Annex 15, , <https://www.unicode.org/reports/tr15/>.

21.2. Informative References

[App-Fed-Linkage]
Dzhuvinov, V., "How to link an application protocol to an OpenID Federation 1.0 trust layer", , <https://connect2id.com/blog/how-to-link-an-app-protocol-to-an-openid-federation-trust-layer>.
[FAPI]
Sakimura, N., Bradley, J., and E. Jay, "Financial-grade API Security Profile 1.0 - Part 2: Advanced", , <https://openid.net/specs/openid-financial-api-part-2-1_0.html>.
[IANA.OAuth.Parameters]
IANA, "OAuth Parameters", <https://www.iana.org/assignments/oauth-parameters>.
[OpenID.Federation-1.0]
Hedberg, R., Ed., Jones, M.B., Solberg, A.Å., Bradley, J., De Marco, G., and V. Dzhuvinov, "OpenID Federation 1.0", , <https://openid.net/specs/openid-federation-1_0.html>.
[RFC2046]
Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, DOI 10.17487/RFC2046, , <https://www.rfc-editor.org/info/rfc2046>.
[RFC8725]
Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best Current Practices", BCP 225, RFC 8725, DOI 10.17487/RFC8725, , <https://www.rfc-editor.org/info/rfc8725>.
[RFC9525]
Saint-Andre, P. and R. Salz, "Service Identity in TLS", RFC 9525, DOI 10.17487/RFC9525, , <https://www.rfc-editor.org/info/rfc9525>.

Appendix A. Examples Building and Using Trust Chains

Let us assume the following: The project LIGO would like to offer access to its wiki to all OPs in eduGAIN. LIGO is registered with the InCommon federation.

The following depicts a federation under the eduGAIN Trust Anchor:

                       eduGAIN
                          |
       +------------------+------------------+
       |                                     |
    SWAMID                               InCommon
       |                                     |
     umu.se                                  |
       |                                     |
   op.umu.se                           wiki.ligo.org
Figure 7: Participants in the eduGAIN Federation

Both SWAMID and InCommon are identity federations in their own right. They also have in common that they are both members of the eduGAIN federation.

SWAMID and InCommon are different in how they register Entities. SWAMID registers organizations and lets the organizations register Entities that belong to the organization, while InCommon registers all Entities directly and not beneath any organization Entity. Hence the differences in depth in the federations.

Let us assume a researcher from Umeå University would like to login to the LIGO Wiki. At the Wiki, the researcher will use some kind of discovery service to find the home identity provider (op.umu.se).

Once the RP part of the Wiki knows which OP it SHOULD talk to, it has to find out a few things about the OP. All those things can be found in the metadata. But finding the metadata is not enough; the RP also has to trust the metadata.

Let us make a detour and start with what it takes to build a federation.

A.1. Setting Up a Federation

These are the steps to set up a federation infrastructure:

  • Generation of Trust Anchor signing keys. These MUST be public/private key pairs.

  • Set up a signing service that can sign JWTs/Entity Statements using the Federation Entity Keys.

  • Set up web services that can publish signed Entity Statements, one for the URL corresponding to the federation's Entity Identifier returning an Entity Configuration and the other one providing the fetch endpoint, as described in Section 8.1.1 of [OpenID.Federation-1.1].

Once these requirements have been satisfied, a Federation Operator can add Entities to the federation. Adding an Entity comes down to:

  • Providing the Entity with the federation's Entity Identifier and the public part of the key pairs used by the federation operator for signing Entity Statements.

  • Getting the Entity's Entity Identifier and the JWK Set that the Entity plans to publish in its Entity Configuration.

Before the federation operator starts adding Entities, there must be policies on who can be part of the federation and the layout of the federation. Is it supposed to be a one-layer federation like InCommon, a two-layer one like the SWAMID federation, or a multi-layer federation? The federation may also want to consider implementing other policies using the federation policy framework, as described in Section 6.

With the federation in place, things can start happening.

A.2. The LIGO Wiki Discovers the OP's Metadata

Federation Entity Discovery is a sequence of steps that starts with the RP fetching the Entity Configuration of the OP's Entity (in this case, https://op.umu.se) using the process defined in Section 9. What follows that is this sequence of steps:

  1. Pick out the Immediate Superior Entities using the authority hints.

  2. Fetch the Entity Configuration for each such Entity. This uses the process defined in Section 9.

  3. Use the fetch endpoint of each Immediate Superior to obtain Subordinate Statements about the Immediate Subordinate Entity, per Section 8.1.1 of [OpenID.Federation-1.1].

How many times this has to be repeated depends on the depth of the federation. What follows below is the result of each step the RP has to take to find the OP's metadata using the federation setup described above.

When building the Trust Chain, the Subordinate Statements issued by each Immediate Superior about their Immediate Subordinates are used together with the Entity Configuration of the Trust Chain subject.

The Entity Configurations of Intermediates are not part of the Trust Chain.

A.2.1. Entity Configuration for https://op.umu.se

The LIGO WIKI RP fetches the Entity Configuration from the OP (op.umu.se) using the process defined in Section 9.

The result is this Entity Configuration:

{
  "authority_hints": [
    "https://umu.se"
  ],
  "exp": 1568397247,
  "iat": 1568310847,
  "iss": "https://op.umu.se",
  "sub": "https://op.umu.se",
  "jwks": {
    "keys": [
      {
        "e": "AQAB",
        "kid": "dEEtRjlzY3djcENuT01wOGxrZlkxb3RIQVJlMTY0...",
        "kty": "RSA",
        "n": "x97YKqc9Cs-DNtFrQ7_vhXoH9bwkDWW6En2jJ044yH..."
      }
    ]
  },
  "metadata": {
    "openid_provider": {
      "issuer": "https://op.umu.se/openid",
      "signed_jwks_uri": "https://op.umu.se/openid/jwks.jose",
      "authorization_endpoint":
        "https://op.umu.se/openid/authorization",
      "client_registration_types_supported": [
        "automatic",
        "explicit"
      ],
      "request_parameter_supported": true,
      "grant_types_supported": [
        "authorization_code",
        "implicit",
        "urn:ietf:params:oauth:grant-type:jwt-bearer"
      ],
      "id_token_signing_alg_values_supported": [
        "ES256", "RS256"
      ],
      "logo_uri":
        "https://www.umu.se/img/umu-logo-left-neg-SE.svg",
      "op_policy_uri":
        "https://www.umu.se/en/website/legal-information/",
      "response_types_supported": [
        "code",
        "code id_token",
        "token"
      ],
      "subject_types_supported": [
        "pairwise",
        "public"
      ],
      "token_endpoint": "https://op.umu.se/openid/token",
      "federation_registration_endpoint":
        "https://op.umu.se/openid/fedreg",
      "token_endpoint_auth_methods_supported": [
        "client_secret_post",
        "client_secret_basic",
        "client_secret_jwt",
        "private_key_jwt"
      ]
    }
  }
}
Figure 8: Entity Configuration Issued by https://op.umu.se

The authority_hints points to the Intermediate Entity https://umu.se. So that is the next step.

This Entity Configuration is the first link in the Trust Chain.

A.2.2. Entity Configuration for https://umu.se

The LIGO RP fetches the Entity Configuration from https://umu.se using the process defined in Section 9.

The request will look like this:

GET /.well-known/openid-federation HTTP/1.1
Host: umu.se
Figure 9: Entity Configuration Issued by https://umu.se

And the GET will return:

{
  "authority_hints": [
    "https://swamid.se"
  ],
  "exp": 1568397247,
  "iat": 1568310847,
  "iss": "https://umu.se",
  "sub": "https://umu.se",
  "jwks": {
    "keys": [
      {
        "e": "AQAB",
        "kid": "endwNUZrNTJsX2NyQlp4bjhVcTFTTVltR2gxV2RV...",
        "kty": "RSA",
        "n": "vXdXzZwQo0hxRSmZEcDIsnpg-CMEkor50SOG-1XUlM..."
      }
    ]
  },
  "metadata": {
    "federation_entity": {
      "contacts": ["ops@umu.se"],
      "federation_fetch_endpoint": "https://umu.se/oidc/fedapi",
      "organization_uri": "https://www.umu.se",
      "organization_name": "UmU"
    }
  }
}
Figure 10: Entity Configuration JWT Claims Set

The only piece of information that is used from this Entity Configuration in this process is the federation_fetch_endpoint, which is used in the next step.

A.2.3. Subordinate Statement Published by https://umu.se about https://op.umu.se

The RP uses the fetch endpoint provided by https://umu.se to fetch information about https://op.umu.se.

The request will look like this:

GET /oidc/fedapi?sub=https%3A%2F%2Fop.umu.se&
iss=https%3A%2F%2Fumu.se HTTP/1.1
Host: umu.se
Figure 11: Request Subordinate Statement from https://umu.se about https://op.umu.se

And the result is this:

{
  "exp": 1568397247,
  "iat": 1568310847,
  "iss": "https://umu.se",
  "sub": "https://op.umu.se",
  "source_endpoint": "https://umu.se/oidc/fedapi",
  "jwks": {
    "keys": [
      {
        "e": "AQAB",
        "kid": "dEEtRjlzY3djcENuT01wOGxrZlkxb3RIQVJlMTY0...",
        "kty": "RSA",
        "n": "x97YKqc9Cs-DNtFrQ7_vhXoH9bwkDWW6En2jJ044yH..."
      }
    ]
  },
  "metadata_policy": {
    "openid_provider": {
      "contacts": {
        "add": [
          "ops@swamid.se"
        ]
      },
      "organization_name": {
        "value": "University of Umeå"
      },
      "subject_types_supported": {
        "value": [
          "pairwise"
        ]
      },
      "token_endpoint_auth_methods_supported": {
        "default": [
          "private_key_jwt"
        ],
        "subset_of": [
          "private_key_jwt",
          "client_secret_jwt"
        ],
        "superset_of": [
          "private_key_jwt"
        ]
      }
    }
  }
}
Figure 12: Subordinate Statement Issued by https://umu.se about https://op.umu.se

This Subordinate Statement is the second link in the Trust Chain.

A.2.4. Entity Configuration for https://swamid.se

The LIGO Wiki RP fetches the Entity Configuration from https://swamid.se using the process defined in Section 9.

The request will look like this:

GET /.well-known/openid-federation HTTP/1.1
Host: swamid.se
Figure 13: Request Entity Configuration from https://swamid.se

And the GET will return:

{
  "authority_hints": [
    "https://edugain.geant.org"
  ],
  "exp": 1568397247,
  "iat": 1568310847,
  "iss": "https://swamid.se",
  "sub": "https://swamid.se",
  "jwks": {
    "keys": [
      {
        "e": "AQAB",
        "kid": "N1pQTzFxUXZ1RXVsUkVuMG5uMnVDSURGRVdhUzdO...",
        "kty": "RSA",
        "n": "3EQc6cR_GSBq9km9-WCHY_lWJZWkcn0M05TGtH6D9S..."
      }
    ]
  },
  "metadata": {
    "federation_entity": {
      "contacts": ["ops@swamid.se"],
      "federation_fetch_endpoint":
        "https://swamid.se/fedapi",
      "organization_uri": "https://www.sunet.se/swamid/",
      "organization_name": "SWAMID"
    }
  }
}
Figure 14: Entity Configuration Issued by https://swamid.se

The only piece of information that is used from this Entity Configuration in this process is the federation_fetch_endpoint, which is used in the next step.

A.2.5. Subordinate Statement Published by https://swamid.se about https://umu.se

The LIGO Wiki RP uses the fetch endpoint provided by https://swamid.se to fetch information about https://umu.se.

The request will look like this:

GET /fedapi?sub=https%3A%2F%2Fumu.se&
iss=https%3A%2F%2Fswamid.se HTTP/1.1
Host: swamid.se
Figure 15: Request to https://swamid.se for Subordinate Statement about https://umu.se

And the result is this:

{
  "exp": 1568397247,
  "iat": 1568310847,
  "iss": "https://swamid.se",
  "sub": "https://umu.se",
  "source_endpoint": "https://swamid.se/fedapi",
  "jwks": {
    "keys": [
      {
        "e": "AQAB",
        "kid": "endwNUZrNTJsX2NyQlp4bjhVcTFTTVltR2gxV2RV...",
        "kty": "RSA",
        "n": "vXdXzZwQo0hxRSmZEcDIsnpg-CMEkor50SOG-1XUlM..."
      }
    ]
  },
  "metadata_policy": {
    "openid_provider": {
      "id_token_signing_alg_values_supported": {
        "subset_of": [
          "RS256",
          "ES256",
          "ES384",
          "ES512"
        ]
      },
      "token_endpoint_auth_methods_supported": {
        "subset_of": [
          "client_secret_jwt",
          "private_key_jwt"
        ]
      },
      "userinfo_signing_alg_values_supported": {
        "subset_of": [
          "ES256",
          "ES384",
          "ES512"
        ]
      }
    }
  }
}
Figure 16: Subordinate Statement Issued by https://swamid.se about https://umu.se

This Subordinate Statement is the third link in the Trust Chain.

If we assume that the issuer of this Subordinate Statement is not in the list of Trust Anchors the LIGO Wiki RP has access to, we have to go one step further.

A.2.6. Entity Configuration for https://edugain.geant.org

The RP fetches the Entity Configuration from https://edugain.geant.org using the process defined in Section 9.

The request will look like this:

GET /.well-known/openid-federation HTTP/1.1
Host: edugain.geant.org
Figure 17: Entity Configuration Requested from https://edugain.geant.org

And the GET will return:

{
  "exp": 1568397247,
  "iat": 1568310847,
  "iss": "https://edugain.geant.org",
  "sub": "https://edugain.geant.org",
  "jwks": {
    "keys": [
      {
        "e": "AQAB",
        "kid": "Sl9DcjFxR3hrRGdabUNIR21KT3dvdWMyc2VUM2Fr...",
        "kty": "RSA",
        "n": "xKlwocDXUw-mrvDSO4oRrTRrVuTwotoBFpozvlq-1q..."
      }
    ]
  },
  "metadata": {
    "federation_entity": {
      "federation_fetch_endpoint": "https://geant.org/edugain/api"
    }
  }
}
Figure 18: Entity Configuration issued by https://edugain.geant.org

Within the Trust Anchor Entity Configuration, the Relying Party looks for the federation_fetch_endpoint and gets the updated Federation Entity Keys of the Trust Anchor. Each Entity within a Federation may change their Federation Entity Keys, or any other attributes, at any time. See Section 11.2 of [OpenID.Federation-1.1] for further details.

A.2.7. Subordinate Statement Published by https://edugain.geant.org about https://swamid.se

The LIGO Wiki RP uses the fetch endpoint of https://edugain.geant.org to fetch information about "https://swamid.se".

The request will look like this:

GET /edugain/api?sub=https%3A%2F%2Fswamid.se&
iss=https%3A%2F%2Fedugain.geant.org HTTP/1.1
Host: geant.org
Figure 19: Request to https://edugain.geant.org for Subordinate Statement about https://swamid.se

And the result is this:

{
  "exp": 1568397247,
  "iat": 1568310847,
  "iss": "https://edugain.geant.org",
  "sub": "https://swamid.se",
  "source_endpoint": "https://edugain.geant.org/edugain/api",
  "jwks": {
    "keys": [
      {
        "e": "AQAB",
        "kid": "N1pQTzFxUXZ1RXVsUkVuMG5uMnVDSURGRVdhUzdO...",
        "kty": "RSA",
        "n": "3EQc6cR_GSBq9km9-WCHY_lWJZWkcn0M05TGtH6D9S..."
      }
    ]
  },
  "metadata_policy": {
    "openid_provider": {
      "contacts": {
        "add": ["ops@edugain.geant.org"]
      }
    },
    "openid_relying_party": {
      "contacts": {
        "add": ["ops@edugain.geant.org"]
      }
    }
  }
}
Figure 20: Subordinate Statement issued by https://edugain.geant.org about https://swamid.se

If we assume that the issuer of this statement appears in the list of Trust Anchors the LIGO Wiki RP has access to, this Subordinate Statement would be the fourth link in the Trust Chain. The Trust Anchor's Entity Configuration MAY also be included in the Trust Chain; in this case, it would be the fifth and final link.

We have now retrieved all the members of the Trust Chain. Recapping, these Entity Statements were obtained:

  • Entity Configuration for the Leaf Entity https://op.umu.se - the first link in the Trust Chain

  • Entity Configuration for https://umu.se - not included in the Trust Chain

  • Subordinate Statement issued by https://umu.se about https://op.umu.se - the second link in the Trust Chain

  • Entity Configuration for https://swamid.se - not included in the Trust Chain

  • Subordinate Statement issued by https://swamid.se about https://umu.se - the third link in the Trust Chain

  • Entity Configuration for https://edugain.geant.org - optionally, the fifth and last link in the Trust Chain

  • Subordinate Statement issued by https://edugain.geant.org about https://swamid.se - the fourth link in the Trust Chain

Using the public keys of the Trust Anchor that the LIGO Wiki RP has been provided within some secure out-of-band way, it can now verify the Trust Chain as described in Section 10.2 of [OpenID.Federation-1.1].

A.2.8. OP Resolved Metadata for https://op.umu.se

Having verified the chain, the LIGO Wiki RP can proceed with the next step.

Combining the metadata policies from the three Subordinate Statements we have by Immediate Superiors about their Immediate Subordinates and applying the combined policy to the metadata statement that the Leaf Entity presented, we get the following Resolved Metadata for the openid_provider Entity Type:

{
  "authorization_endpoint":
    "https://op.umu.se/openid/authorization",
  "contacts": [
    "ops@swamid.se",
    "ops@edugain.geant.org"
  ],
  "federation_registration_endpoint":
    "https://op.umu.se/openid/fedreg",
  "client_registration_types_supported": [
    "automatic",
    "explicit"
  ],
  "grant_types_supported": [
    "authorization_code",
    "implicit",
    "urn:ietf:params:oauth:grant-type:jwt-bearer"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256",
    "ES256"
  ],
  "issuer": "https://op.umu.se/openid",
  "signed_jwks_uri": "https://op.umu.se/openid/jwks.jose",
  "logo_uri":
    "https://www.umu.se/img/umu-logo-left-neg-SE.svg",
  "organization_name": "University of Umeå",
  "op_policy_uri":
    "https://www.umu.se/en/website/legal-information/",
  "request_parameter_supported": true,
  "response_types_supported": [
    "code",
    "code id_token",
    "token"
  ],
  "subject_types_supported": [
    "pairwise"
  ],
  "token_endpoint": "https://op.umu.se/openid/token",
  "token_endpoint_auth_methods_supported": [
    "private_key_jwt",
    "client_secret_jwt"
  ]
}
Figure 21: OP Resolved Metadata Derived from Trust Chain by Applying Metadata Policies

We have now reached the end of the Provider Discovery process.

A.3. Client Registration Method Examples

Section 12 defines two methods for performing client registration:

Automatic
No negotiation between the RP and the OP is made regarding what features the client SHOULD use in future communication occurs. The RP's published metadata filtered by the chosen Trust Chain's metadata policies defines the metadata that is to be used.
Explicit
The RP will access the federation_registration_endpoint, which provides the RP's metadata. The OP MAY return a metadata policy that adds restrictions over and above what the Trust Chain already has defined.

A.3.1. RP Sends Authentication Request (Automatic Client Registration)

The LIGO Wiki RP does not do any registration but goes directly to sending an Authentication Request.

Here is an example of such an Authentication Request:

GET /openid/authorization?
  request=eyJ0eXAiOiJvYXV0aC1hdXRoei1yZXErand0IiwiYWxnIjoiU
    lMyNTYiLCJraWQiOiJkVU4yYTAxd1JraGtTV3BsUVRodmNWQklOVUl3
    VFVkT1VGVTJUbVZyU21oRVFYZ3paWGxwVHpkUU5BIn0.
    eyJyZXNwb25zZV90eXBlIjogImNvZGUiLCAic2NvcGUiOiAib3Blbml
    kIHByb2ZpbGUgZW1haWwiLCAiY2xpZW50X2lkIjogImh0dHBzOi8vd2
    lraS5saWdvLm9yZyIsICJzdGF0ZSI6ICIyZmY3ZTU4OS0zODQ4LTQ2Z
    GEtYTNkMi05NDllMTIzNWU2NzEiLCAibm9uY2UiOiAiZjU4MWExODYt
    YWNhNC00NmIzLTk0ZmMtODA0ODQwODNlYjJjIiwgInJlZGlyZWN0X3V
    yaSI6ICJodHRwczovL3dpa2kubGlnby5vcmcvb3BlbmlkL2NhbGxiYW
    NrIiwgImlzcyI6ICJodHRwczovL3dpa2kubGlnby5vcmciLCAiaWF0I
    jogMTU5MzU4ODA4NSwgImF1ZCI6ICJodHRwczovL29wLnVtdS5zZSJ9
    .cRwSFNcDx6VsacAQDcIx
    5OAt_Pj30I_uUKRh04N4QJd6MZ0f50sETRv8uspSt9fMa-5yV3uzthX
    _v8OtQrV33gW1vzgOSRCdHgeCN40StbzjFk102seDwtU_Uzrcsy7KrX
    YSBp8U0dBDjuxC6h18L8ExjeR-NFjcrhy0wwua7Tnb4QqtN0QCia6DD
    8QBNVTL1Ga0YPmMdT25wS26wug23IgpbZB20VUosmMGgGtS5yCI5AwK
    Bhozv-oBH5KxxHzH1Oss-RkIGiQnjRnaWwEOTITmfZWra1eHP254wFF
    2se-EnWtz1q2XwsD9NSsOEJwWJPirPPJaKso8ng6qrrOSgw
  &response_type=code
  &client_id=https%3A%2F%2Fwiki.ligo.org
  &redirect_uri=https%3A%2F%2Fwiki.ligo.org/openid/callback
  &scope=openid+profile+email
  HTTP/1.1
Host: op.umu.se
Figure 22: Authentication Request using Automatic Client Registration

The OP receiving this Authentication Request will, unless the RP is already registered, start to dynamically fetch and establish trust with the RP.

A.3.1.1. OP Fetches Entity Statements

The OP needs to establish a Trust Chain for the RP (wiki.ligo.org). The OP in this example is configured with public keys of two federations:

  • https://edugain.geant.org

  • https://swamid.se

The OP starts to resolve metadata for the Client Identifier https://wiki.ligo.org by fetching the Entity Configuration using the process described in Section 9.

The process is the same as described in Appendix A.2 and will result in a Trust Chain with the following Entity Statements:

  1. Entity Configuration for the Leaf Entity https://wiki.ligo.org

  2. Subordinate Statement issued by https://incommon.org about https://wiki.ligo.org

  3. Subordinate Statement issued by https://edugain.geant.org about https://incommon.org

A.3.1.2. OP Evaluates the RP Metadata

Using the public keys of the Trust Anchor that the LIGO Wiki RP has been provided within some secure out-of-band way, it can now verify the Trust Chain as described in Section 10.2 of [OpenID.Federation-1.1].

We will not list the complete Entity Statements but only the metadata and metadata_policy parts. There are two metadata policies:

edugain.geant.org:
"metadata_policy": {
  "openid_provider": {
    "contacts": {
      "add": ["ops@edugain.geant.org"]
    }
  },
  "openid_relying_party": {
    "contacts": {
      "add": ["ops@edugain.geant.org"]
    }
  }
}
Figure 23: Metadata Policies Related to Multiple Metadata Types
incommon.org:
"metadata_policy": {
  "openid_relying_party": {
    "application_type": {
      "one_of": [
        "web",
        "native"
      ]
    },
    "contacts": {
      "add": ["ops@incommon.org"]
    },
    "grant_types": {
      "subset_of": [
        "authorization_code",
        "refresh_token"
      ]
    }
  }
}
Figure 24: Metadata Policy Related to the RP

Next, combine these and apply them to the metadata for wiki.ligo.org:

"metadata": {
  "openid_relying_party": {
    "application_type": "web",
    "client_name": "LIGO Wiki",
    "contacts": [
      "ops@ligo.org"
    ],
    "grant_types": [
      "authorization_code",
      "refresh_token"
    ],
    "id_token_signing_alg_values_supported":
      ["ES256", "PS256", "RS256"],
    "signed_jwks_uri": "https://wiki.ligo.org/jwks.jose",
    "redirect_uris": [
      "https://wiki.ligo.org/openid/callback"
    ],
    "response_types": [
      "code"
    ],
    "subject_type": "public",
    "token_endpoint_auth_method": "private_key_jwt"
  }
}
Figure 25: Combined Metadata with Metadata Policy Yet to be Applied

The final result is:

"metadata": {
  "openid_relying_party": {
    "application_type": "web",
    "client_name": "LIGO Wiki",
    "contacts": [
      "ops@ligo.org",
      "ops@edugain.geant.org",
      "ops@incommon.org"
    ],
    "grant_types": [
      "refresh_token",
      "authorization_code"
    ],
    "id_token_signing_alg_values_supported":
      ["ES256", "PS256", "RS256"],
    "signed_jwks_uri": "https://wiki.ligo.org/jwks.jose",
    "redirect_uris": [
      "https://wiki.ligo.org/openid/callback"
    ],
    "response_types": [
      "code"
    ],
    "subject_type": "public",
    "token_endpoint_auth_method": "private_key_jwt"
  }
}
Figure 26: Resolved Metadata After Metadata Policy has been Applied

Once the Trust Chain and the final Relying Party metadata have been obtained, the OpenID Provider has everything needed to validate the signature of the Request Object in the Authentication Request, using the public keys made available at the signed_jwks_uri endpoint.

A.3.2. RP Starts with Client Registration (Explicit Client Registration)

Here the LIGO Wiki RP sends an Explicit Registration request to the federation_registration_endpoint of the OP (op.umu.se). The request contains the RP's Entity Configuration.

An example JWT Claims Set for the RP's Entity Configuration is:

{
  "iss": "https://wiki.ligo.org",
  "sub": "https://wiki.ligo.org",
  "iat": 1676045527,
  "exp": 1676063610,
  "aud": "https://op.umu.se",
  "metadata": {
    "openid_relying_party": {
      "application_type": "web",
      "client_name": "LIGO Wiki",
      "contacts": ["ops@ligo.org"],
      "grant_types": ["authorization_code"],
      "id_token_signed_response_alg": "RS256",
      "signed_jwks_uri": "https://wiki.ligo.org/jwks.jose",
      "redirect_uris": [
        "https://wiki.ligo.org/openid/callback"
      ],
      "response_types": ["code"],
      "subject_type": "public"
    }
  },
  "jwks": {
    "keys": [
      {
        "kty": "RSA",
        "use": "sig",
        "kid":
          "U2JTWHY0VFg0a2FEVVdTaHptVDJsNDNiSDk5MXRBVEtNSFVkeXZwb",
        "e": "AQAB",
        "n":
          "4AZjgqFwMhTVSLrpzzNcwaCyVD88C_Hb3Bmor97vH-2AzldhuVb8K..."
      }
    ]
  },
  "authority_hints": ["https://incommon.org"]
}
Figure 27: RP's Entity Configuration JWT Claims Set

The OP receives the RP's Entity Configuration and proceeds with the sequence of steps laid out in Appendix A.2.

The OP successfully resolves the same RP metadata described in Appendix A.3.1.2. It then registers the RP in compliance with its own OP metadata and returns the result in a registration Entity Statement.

Assuming the OP does not support refresh tokens it will register the RP for the authorization_code grant type only. This is reflected in the metadata returned to the RP.

The returned metadata also includes the client_id, the client_secret and other parameters that the OP provisioned for the RP.

Here is an example JWT Claims Set of the registration Entity Statement returned by the OP to the RP after successful explicit client registration:

{
  "iss": "https://op.umu.se",
  "sub": "https://wiki.ligo.org",
  "aud": "https://wiki.ligo.org",
  "iat": 1601457619,
  "exp": 1601544019,
  "trust_anchor": "https://edugain.geant.org",
  "metadata": {
    "openid_relying_party": {
      "client_id": "m3GyHw",
      "client_secret_expires_at": 1604049619,
      "client_secret":
        "cb44eed577f3b5edf3e08362d47a0dc44630b3dc6ea99f7a79205",
      "client_id_issued_at": 1601457619,
      "application_type": "web",
      "client_name": "LIGO Wiki",
      "contacts": [
        "ops@edugain.geant.org",
        "ops@incommon.org",
        "ops@ligo.org"
      ],
      "grant_types": [
        "authorization_code"
      ],
      "id_token_signed_response_alg": "RS256",
      "signed_jwks_uri": "https://wiki.ligo.org/jwks.jose",
      "redirect_uris": [
        "https://wiki.ligo.org/openid/callback"
      ],
      "response_types": [
        "code"
      ],
      "subject_type": "public"
    }
  },
  "authority_hints": [
    "https://incommon.org"
  ],
  "jwks": {
    "keys": [
      {
        "kty": "RSA",
        "use": "sig",
        "kid":
          "U2JTWHY0VFg0a2FEVVdTaHptVDJsNDNiSDk5MXRBVEtNSFVkeXZwb",
        "e": "AQAB",
        "n":
          "4AZjgqFwMhTVSLrpzzNcwaCyVD88C_Hb3Bmor97vH-2AzldhuVb8K..."
      },
      {
        "kty": "EC",
        "use": "sig",
        "kid": "LWtFcklLOGdrW",
        "crv": "P-256",
        "x": "X2S1dFE7zokQDST0bfHdlOWxOc8FC1l4_sG1Kwa4l4s",
        "y": "812nU6OCKxgc2ZgSPt_dkXbYldG_smHJi4wXByDHc6g"
      }
    ]
  }
}
Figure 28: JWT Claims Set of Registration Entity Statement Returned by OP to RP after Explicit Client Registration

Appendix B. Notices

Copyright (c) 2026 The OpenID Foundation.

The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft, Final Specification, or Final Specification Incorporating Errata Corrections solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts, Final Specifications, and Final Specification Incorporating Errata Corrections based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.

The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy (found at openid.net) requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. OpenID invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.

Appendix C. Document History

[[ To be removed from the final specification ]]

-00

Acknowledgements

OpenID Connect Federation 1.1 Acknowledgements

The authors wish to acknowledge the contributions of the following individuals and organizations to this specification: the SIROS Foundation.

OpenID Federation 1.0 Acknowledgements

The authors wish to acknowledge the contributions of the following individuals and organizations to this specification: Marcus Almgren, Patrick Amrein, Pål Axelsson, Pasquale Barbaro, Ralph Bragg, Peter Brand, Brian Campbell, David Chadwick, Michele D'Amico, Kushal Das, Andrii Deinega, Erick Domingues, Heather Flanagan, Michael Fraser, Samuel Gulliksson, Joseph Heenan, Pedram Hosseyni, Marko Ivančić, Łukasz Jaromin, Leif Johansson, Takahiko Kawasaki, Ralf Küsters, Torsten Lodderstedt, Josh Mandel, Francesco Marino, John Melati, Alexey Melnikov, Henri Mikkonen, Aaron Parecki, Eduardo Perottoni, Chris Phillips, Roberto Polli, Justin Richer, Jouke Roorda, Nat Sakimura, Mischa Sallé, Stefan Santesson, Marcos Sanz, Michael Schwartz, Giada Sciarretta, Amir Sharif, Yaron Sheffer, Sean Turner, Davide Vaghetti, Niels van Dijk, Tim Würtele, Kristina Yasuda, Gabriel Zachmann, the JRA3T3 task force of GEANT4-2, and the SIROS Foundation.

Authors' Addresses

Roland Hedberg
independent
Michael B. Jones (editor)
Self-Issued Consulting
URI: https://self-issued.info/
Giuseppe De Marco
independent
URI: https://www.linkedin.com/in/giuseppe-de-marco-bb054245/
Andreas Åkre Solberg
Sikt
URI: https://www.linkedin.com/in/andreassolberg/
John Bradley
Yubico
URI: https://www.linkedin.com/in/ve7jtb/
Vladimir Dzhuvinov
Connect2id
URI: https://www.linkedin.com/in/vladimirdzhuvinov/