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

OpenID Federation 1.0 - draft 36

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 defines basic components used to build multilateral federations and describes how to apply them when the underlying authentication protocol used is OpenID Connect or the underlying authorization protocol is OAuth 2.0.

Table of Contents

1. Introduction

This specification describes how two Entities that would like to interact can establish trust between them by means of a trusted third party called a Trust Anchor. A Trust Anchor is an Entity whose main purpose is to issue statements about Entities. An identity federation can be realized using this specification using one or more levels of authorities. Examples of authorities are federation operators, organizations, departments within organizations, and individual sites. This specification provides the basic technical trust infrastructure building blocks needed to create a dynamic and distributed trust network, such as a federation.

Note that this specification only concerns itself with how Entities in a federation get to know about each other. An organization MAY be represented by more than one Entity in a federation. An Entity MAY also belong to more than one federation. Determining that two Entities belong to the same federation is the basis for establishing trust between them in this specification.

Of course, the word "trust" is also used in the vernacular to encompass confidence in the security, reliability, and integrity of entities and their actions. This kind trust is often established through empirical proof, such as past performance, security certifications, or transparent operational practices, which demonstrate a track record of adherence to security standards and ethical conduct. To be clear, this broader meaning of trust, while important, is largely beyond the scope of what this specification accomplishes.

Below is an example of two federations rooted at two different Trust Anchors with some members in common. Every Entity is able to establish mutual trust with any other Entity by means of having at least one common Trust Anchor between them.

.-----------------.            .-----------------.
|  Trust Anchor A |            |  Trust Anchor B |
'------.--.-------'            '----.--.--.------'
       |  |                         |  |  |
    .--'  '---. .-------------------'  |  |
    |         | |                      |  |
.---v.  .-----v-v------.   .-----------'  |
| OP |  | Intermediate |   |              |
'----'  '--.--.--.-----'   |    .---------v----.
           |  |  |         |    | Intermediate |
   .-------'  |  '------.  |    '---.--.--.----'
   |          |         |  |        |  |  |
.--v-.      .-v--.     .v--v.   .---'  |  '----.
| RP |      | RS |     | OP |   |      |       |
'----'      '----'     '----'   |   .--v-.   .-v--.
                                |   | RP |   | RP |
                                |   '----'   '----'
                                |
                        .-------v------.
                        | Intermediate |
                        '----.--.--.---'
                             |  |  |
                       .-----'  |  '----.
                       |        |       |
                    .--v-.   .--v-.   .-v--.
                    | OP |   | RP |   | AS |
                    '----'   '----'   '----'

Figure 1: Two Coexisting Federations with Some Members in Common

1.1. Requirements Language

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

1.2. Terminology

This specification uses the terms "Claim Name", "Claim Value", "JSON Web Token (JWT)", and "JWT Claims Set" defined by JSON Web Token (JWT) [RFC7519] and the terms "OpenID Provider (OP)" and "Relying Party (RP)" defined by OpenID Connect Core 1.0 [OpenID.Core].

This specification also defines the following terms:

Entity
Something that has a separate and distinct existence and that can be identified in a context.
Entity Identifier
A globally unique URI that is bound to one Entity.
Trust Anchor
An Entity that represents a trusted third party.
Federation Entity
An Entity for which it is possible to construct a Trust Chain from the Entity to a Trust Anchor.
Entity Statement
A signed JWT that contains the information needed for an Entity to participate in federation(s), including metadata about itself and policies that apply to other Entities that it is authoritative for.
Entity Configuration
An Entity Statement issued by an Entity about itself. It contains the Entity's signing keys and further data used to control the Trust Chain resolution process, such as authority hints.
Subordinate Statement
An Entity Statement issued by a Superior Entity about an Entity that is its Immediate Subordinate.
Entity Type
A role and function that an Entity plays within a federation. An Entity MUST be of at least one type and MAY be of many types. For example, an Entity can be both an OpenID Provider and Relying Party at the same time.
Entity Type Identifier
String identifier for an Entity Type.
Federation Operator
An organization that is authoritative for a federation. A federation operator administers the Trust Anchor(s) for Entities in its federation.
Intermediate Entity
An Entity that issues an Entity Statement appearing somewhere in between those issued by the Trust Anchor and the subject of a Trust Chain (which is typically a Leaf Entity). The terms Intermediate Entity and Intermediate are used interchangeably in this specification.
Leaf Entity
An Entity with no Subordinate Entities. Leaf Entities typically play a protocol role, such as an OpenID Connect Relying Party or OpenID Provider. The terms Leaf Entity and Leaf are used interchangeably in this specification.
Subordinate Entity
An Entity that is somewhere below a Superior Entity (a Trust Anchor or Intermediate) in the trust hierarchy, possibly with Intermediates between them. The terms Subordinate Entity and Subordinate are used interchangeably in this specification.
Superior Entity
An Entity that is somewhere above one or more Entities (a Leaf or Intermediate) in the trust hierarchy, possibly with Intermediates between them. The terms Superior Entity and Superior are used interchangeably in this specification.
Immediate Subordinate Entity
An Entity that is immediately below a Superior Entity in the trust hierarchy, with no Intermediates between them. The terms Immediate Subordinate Entity and Immediate Subordinate are used interchangeably in this specification.
Immediate Superior Entity
An Entity that is immediately above one or more Subordinate Entities in the trust hierarchy, with no Intermediates between them. The terms Immediate Superior Entity and Immediate Superior are used interchangeably in this specification.
Federation Entity Discovery
A process that starts with the Entity Identifier for the subject of the Trust Chain and collects Entity Statements until the chosen Trust Anchor is reached. From the collected Entity Statements, a Trust Chain is constructed and verified. The result of the Federation Entity Discovery is that the metadata for the Trust Chain subject is constructed from the Trust Chain.
Trust Chain
A sequence of Entity Statements that represents a chain starting at an Entity Configuration that is the subject of the chain (typically of a Leaf Entity) and ending in a Trust Anchor.
Trust Mark
Statement of conformance to a well-scoped set of trust and/or interoperability requirements as determined by an accreditation authority.
Federation Entity Keys
Keys used for the cryptographic signatures required by the trust mechanisms defined in this specification. Every participant in a Federation publishes its Federation Entity Keys in its Entity Configuration.

2. Overall Architecture

The basic component is the Entity Statement, which is a cryptographically signed JSON Web Token (JWT) [RFC7519]. A set of Entity Statements can form a path from an Entity (typically a Leaf Entity) to a Trust Anchor. Entity Configurations issued by Entities about themselves control the Trust Chain resolution process.

The Entity Configuration of a Leaf or Intermediate Entity contains one or more references to its Immediate Superiors in the authority_hints parameter described in Section 3. These references can be used to download the Entity Configuration of each Immediate Superior. One or more Entity Configurations are traversed during the Federation Entity Discovery until the Trust Anchor is reached.

The Trust Anchor and its Intermediates issue Entity Statements about their Immediate Subordinate Entities called Subordinate Statements. The sequence of Entity Configurations and Subordinate Statements that validate the relationship between a Superior and a Subordinate, along a path towards the Trust Anchor, forms the proof that the subject of Trust Chain (typically a Leaf Entity) is a member of the federation rooted at the Trust Anchor.

The chain that links the statements to one another is verified with the signature of each statement, as described in Section 4.

Once there is a verified Trust Chain, the federation policy is applied and the metadata for the Trust Chain subject within the Federation is derived, as described in Section 6.

This specification deals with trust operations; it does not cover or touch protocol operations other than metadata derivation and exchange. In OpenID Connect terms, these are the protocol operations specified in OpenID Connect Discovery 1.0 [OpenID.Discovery] and OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration].

OpenID Connect is used in many of the examples in this specification, however this does not mean that this specification can only be used with OpenID Connect. On the contrary, it can also be used to build federations for any other protocols.

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. In particular, the keys used for securing these objects are managed by the Entities controlling those objects, with the public keys securing them being distributed through those objects themselves. This kind of trust mechanism has been utilized by research and academic federations for over a decade.

Note that this cryptographic trust mechanism intentionally does not rely on Web PKI / TLS certificates for signing keys. Which TLS certificates are considered trusted can vary considerably between systems depending upon which certificate authorities are considered trusted and there are have been notable examples of ostensibly trusted certificates being compromised. For those reasons, this specification explicitly eschews reliance on Web PKI in favor of self-managed public keys, in this case, keys represented as JSON Web Keys (JWKs) [RFC7517].

3. Entity Statement

An Entity Statement contains the information needed for the Entity that is the subject of the Entity Statement to participate in federation(s). An Entity Statement is a signed JWT. The subject of the JWT is the Entity itself. The issuer of the JWT is the party that issued the Entity Statement. All Entities in a federation publish an Entity Statement about themselves called an Entity Configuration. Superior Entities in a federation publish Entity Statements about their Immediate Subordinate Entities called Subordinate Statements.

Entity Statement JWTs MUST be explicitly typed, by setting the typ header parameter to entity-statement+jwt to prevent cross-JWT confusion, per Section 3.11 of [RFC8725].

The Entity Statement is signed using one of the private keys of the issuer Entity in the form of a JSON Web Signature (JWS) [RFC7515]. Implementations SHOULD support signature verification with the RSA SHA-256 algorithm because OpenID Connect Core requires support for it (alg value of RS256). Federations MAY also specify different mandatory-to-implement algorithms.

Entity Statement JWTs MUST include the kid (Key ID) header parameter with its value being the Key ID of the signing key used.

The claims in an Entity Statement are:

iss
REQUIRED. The Entity Identifier of the issuer of the Entity Statement. If the iss and the sub are identical, the issuer is making an Entity Statement about itself called an Entity Configuration.
sub
REQUIRED. The Entity Identifier of the subject.
iat
REQUIRED. Number. Time when this statement was issued. This is expressed as Seconds Since the Epoch, as defined in [RFC7519].
exp
REQUIRED. Number. Expiration time after which the statement MUST NOT be accepted for processing. This is expressed as Seconds Since the Epoch, as defined in [RFC7519].
jwks
REQUIRED. A JSON Web Key Set (JWKS) [RFC7517] representing the public part of the subject's Federation Entity signing keys. The corresponding private key is used by the Entity to sign the Entity Configuration about itself, and by Trust Anchors and Intermediate Entities to sign Subordinate Statements about their Immediate Subordinates. The public keys are used to verify the signatures of the issued Entity Statements and Trust Marks and SHOULD NOT be used in other protocols. (Keys to be used in other protocols, such as OpenID Connect, are conveyed in the metadata elements of the respective Entity Statements.) This claim is only OPTIONAL for the Entity Statement returned from an OP when the client is doing Explicit Registration. In all other cases, it is REQUIRED. Every JWK in the JWK Set MUST have a unique kid (Key ID) value. It is RECOMMENDED that the Key ID be the JWK Thumbprint [RFC7638] using the SHA-256 hash function of the key.
authority_hints
OPTIONAL. An array of strings representing the Entity Identifiers of Intermediate Entities or Trust Anchors that MAY issue Subordinate Statements about the Entity. This claim is REQUIRED in Entity Configurations of the Entities that have at least one Superior above them, such as Leaf and Intermediate Entities. Its value MUST NOT be the empty array []. This claim MUST NOT be present in Entity Configurations of Trust Anchors with no Superiors. It MUST NOT be present in Subordinate Statements.
metadata

OPTIONAL. JSON object that represents the Entity's Types and the metadata for those Entity Types. Each member name of the JSON object is an Entity Type Identifier, and each value MUST be a JSON object containing metadata parameters according to the metadata schema of the Entity Type.

When an Entity participates in a federation or federations with one or more Entity Types, its Entity Configuration MUST contain a metadata claim with JSON object values for each of the corresponding Entity Type Identifiers, even if the values are the empty JSON object {} (when the Entity Type has no associated metadata or Immediate Superiors supply any needed metadata).

An Immediate Superior MAY provide selected or all metadata parameters for an Immediate Subordinate, by using the metadata claim in a Subordinate Statement. When metadata is used in a Subordinate Statement, it applies only to those Entity Types that are present in the subject's Entity Configuration. Furthermore, the metadata applies only to the subject of the Subordinate Statement and has no effect on the subject's Subordinates. Metadata parameters in a Subordinate Statement have precedence and override identically named parameters under the same Entity Type in the subject's Entity Configuration. If both metadata and metadata_policy appear in a Subordinate Statement, then the stated metadata MUST be applied before the metadata_policy, as described in Section 6.1.4.2.

metadata_policy
OPTIONAL. JSON object that defines a metadata policy, as described in Section 6.1. Only Subordinate Statements MAY include this claim. The metadata policy applies to the Entity that is the subject of this Subordinate Statement as well as to all Entities that are Subordinate to it. Applying to Subordinate Entities distinguishes metadata_policy from metadata, which only applies to the subject itself.
constraints
OPTIONAL. JSON object that defines Trust Chain constraints, as described in Section 6.2. Only Subordinate Statements MAY include this claim. The constraints apply to the Entity that is the subject of this Subordinate Statement as well as to all Entities that are Subordinate to it.
crit
OPTIONAL. Entity Statements require that the crit (critical) claim defined in Section 13.1 be understand and processed. Claims specified for use in Entity Statements by this specification MUST NOT be included in the list.
metadata_policy_crit
OPTIONAL. Array of strings specifying critical metadata policy operators other than the standard ones defined in Section 6.1.3.1 that MUST be understood and processed. Only Subordinate Statements MAY include this claim and when included its value MUST NOT be the empty array []. If any of the listed policy operators are not understood and supported, then the Subordinate Statement and thus the Trust Chain that includes it MUST be considered invalid.
trust_marks

OPTIONAL. An array of JSON objects, each representing a Trust Mark. Each JSON object MUST contain the following two claims and MAY contain other claims. All the claims in the JSON object MUST have the same values as those contained in the Trust Mark JWT.

id
The Trust Mark identifier. It MUST be the same value as the id claim contained in the Trust Mark JWT.
trust_mark
A signed JSON Web Token that represents a Trust Mark.

Trust Marks are described in Section 7. This claim SHOULD only be used in Entity Configurations.

trust_mark_issuers
OPTIONAL. A Trust Anchor MAY use this claim to tell which combination of Trust Mark identifiers and issuers are trusted by the federation. This claim MUST be ignored if present in an Entity Configuration for an Entity that is not a Trust Anchor. It is a JSON object with member names that are Trust Mark identifiers and each corresponding value being an array of Entity Identifiers that are trusted to represent the accreditation authority for Trust Marks with that identifier. If the array following a Trust Mark identifier is empty, anyone MAY issue Trust Marks with that identifier. This claim MUST NOT be present in Subordinate Statements. Trust Marks are described in Section 7.
trust_mark_owners

OPTIONAL. If a Federation Operator knows that a Trust Mark identifier is owned by an Entity different from the Trust Mark issuer, then that knowledge MUST be expressed in this claim. This claim MUST be ignored if present in an Entity Configuration for an Entity that is not a Trust Anchor. It is a JSON object with member names that are Trust Mark identifiers and each corresponding value being a JSON object with these members:

sub
REQUIRED Identifier of the Trust Mark owner.
jwks
REQUIRED JSON Web Key Set (JWKS) [RFC7517] containing the owner's Federation Entity Keys used for signing.

Other members MAY also be defined and used. This claim MUST NOT be present in Subordinate Statements.

source_endpoint
OPTIONAL. String containing the fetch endpoint URL from which the Entity Statement was issued, as specified in Section 8.1. This parameter enables an optimized refresh of the Subordinate Statements and hence the Trust Chain, by skipping the request to the Entity Configuration that is normally required to discover the federation_fetch_endpoint of the issuing authority. If an Entity Statement cannot be retrieved from the source_endpoint, which can occur if the endpoint URL has changed, the current federation_fetch_endpoint location can be determined by retrieving the Entity Configuration of the issuer.

Applications and protocols utilizing Entity Statements MAY specify and use additional claims.

The following is a non-normative example of the JWT Claims Set for an Entity Statement. The example contains a critical extension jti (JWT ID) to the Entity Statement and one critical extension to the policy language regexp (Regular expression).

{
  "iss": "https://feide.no",
  "sub": "https://ntnu.no",
  "iat": 1516239022,
  "exp": 1516298022,
  "jwks": {
    "keys": [
      {
        "kty": "RSA",
        "alg": "RS256",
        "use": "sig",
        "kid": "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs",
        "n": "pnXBOusEANuug6ewezb9J_...",
        "e": "AQAB"
      }
    ]
  },
  "metadata": {
    "openid_provider": {
      "issuer": "https://ntnu.no",
      "organization_name": "NTNU"
    },
    "oauth_client": {
      "organization_name": "NTNU"
    }
  },
  "metadata_policy": {
    "openid_provider": {
      "id_token_signing_alg_values_supported":
        {"subset_of": ["RS256", "RS384", "RS512"]},
      "op_policy_uri": {
        "regexp":
          "^https:\/\/[\\w-]+\\.example\\.com\/[\\w-]+\\.html"}
    },
    "oauth_client": {
      "grant_types": {
        "one_of": ["authorization_code", "client_credentials"]
      }
    }
  },
  "constraints": {
    "max_path_length": 2
  },
  "crit": ["jti"],
  "metadata_policy_crit": ["regexp"],
  "source_endpoint": "https://feide.no/federation_api/fetch",
  "jti": "7l2lncFdY6SlhNia"
}
Figure 2: Example Entity Statement JWT Claims Set

The following is a non-normative example of a trust_mark_owners claim value:

{
  "https://refeds.org/wp-content/uploads/2016/01/Sirtfi-1.0.pdf":
    {
      "sub": "https://refeds.org/sirtfi",
      "jwks" : {
        "keys": [
          {
            "alg": "RS256",
            "e": "AQAB",
            "kid": "key1",
            "kty": "RSA",
            "n": "pnXBOusEANuug6ewezb9J_...",
            "use": "sig"
          }
        ]
      }
    }
}
Figure 3: Example trust_mark_owners Claim Value

The following is a non-normative example of a trust_mark_issuers claim value:

{
  "https://openid.net/certification/op": [],
  "https://refeds.org/wp-content/uploads/2016/01/Sirtfi-1.0.pdf":
    ["https://swamid.se"]
}
Figure 4: Example trust_mark_issuers Claim Value

4. Trust Chain

Entities whose statements build a Trust Chain are categorized as:

Trust Anchor
An Entity that represents a trusted third party.
Leaf
In an OpenID Connect identity federation, an RP or an OP, or in an OAuth 2.0 federation, a Client, Authorization Server, or Protected Resource.
Intermediate
Neither a Leaf Entity nor a Trust Anchor.

A Trust Chain begins with an Entity Configuration that is the subject of the Trust Chain, which is typically a Leaf Entity. The Trust Chain has zero or more Subordinate Statements issued by Intermediates about their Immediate Subordinates, and includes the Subordinate Statement issued by the Trust Anchor about the top-most Intermediate (if there are Intermediates) or the Trust Chain subject (if there are no Intermediates). The Trust Chain logically always ends with the Entity Configuration of the Trust Anchor, even though it MAY be omitted from the JSON array representing the Trust Chain in some cases.

The Trust Chain contains the configuration of the federation as it applies to the Trust Chain subject at the time of the evaluation of the chain.

A simple example: If we have an RP that belongs to Organization A that is a member of Federation F, the Trust Chain for such a setup will contain the following Entity Statements:

  1. an Entity Configuration about the RP published by itself,

  2. a Subordinate Statement about the RP published by Organization A,

  3. a Subordinate Statement about Organization A published by the Trust Anchor for F,

  4. an Entity Configuration about the Trust Anchor for F published by itself.

Let us refer to the Entity Statements in the Trust Chain as ES[j], where j = 0,...,i, with 0 being the index of the first Entity Statement and i being the zero-based index of the last. Then:

The Trust Anchor's public keys are used to verify the signatures on ES[i] (the Trust Anchor's Entity Configuration) and ES[i-1] (the Trust Anchor's Subordinate Statement about its Immediate Subordinate in the Trust Chain). The Trust Anchor's public keys are distributed to Entities that need to verify a Trust Chain in some secure out-of-band way not described in this document.

4.1. Beginning and Ending Trust Chains

A Trust Chain begins with the Entity Configuration of an Entity for which trust is being established. This is the subject of the Trust Chain. This Entity typically plays a protocol role, such as being an OpenID Provider or OpenID Relying Party.

While such Entities are typically Leaf Entities, other topologies are possible. For instance, an Entity might simultaneously be an OpenID Provider and an Intermediate Entity, with OpenID Relying Parties and/or other Intermediates being Subordinate to it. This is a case in which the subject of a Trust Chain would not be a Leaf Entity.

A Trust Chain ends with the Entity Configuration of a Trust Anchor. While Trust Anchors typically have no Superiors, a Trust Anchor will have a Superior when the Trust Anchor also acts as an Intermediate Entity in another federation. This will be the case when there is a hierarchy of federations.

Thus, while it is typical for a Trust Chain to end with a Trust Anchor with no Superiors, there are situations in which the Trust Chain will end with a Trust Anchor that nonetheless has Superior Entities.

4.2. Trust Chain Example

The following is an example of a Trust Chain consisting of a Leaf's Entity Configuration and Subordinate Statements issued by an Intermediate Entity and a Trust Anchor. It shows the relationship between the three Entities, their Entity Configurations, and their Subordinate Statements. The Subordinate Statements are obtained from the federation_fetch_endpoint of the subject's Immediate Superior. The URL of the federation_fetch_endpoint is discovered in the Immediate Superior's Entity Configuration. Note that the first member of the Trust Chain (the Leaf) is depicted at the bottom of the diagram and that the last member (the Trust Anchor) is depicted at the top.

.----------------.  .---------------------------.         .---------------------------.
| Role           |  | .well-known/              |         | Trust Chain               |
|                |  | openid-federation         |         |                           |
.----------------.  .---------------------------.         .---------------------------.
| .------------. |  | .-----------------------. |         | .-----------------------. |
| |            | |  | | Entity Configuration  | |         | | Entity Configuration  | |
| |Trust Anchor+-+--+->                       +-+---------+->                       | |
| |            | |  | | Federation Entity Keys| |         | | Federation Entity Keys| |
| '-----.------' |  | | Metadata              | |         | | Metadata              | |
|       |        |  | | Trust Mark Issuers    | |         | | Trust Mark Issuers    | |
|       |        |  | | constraints           | |         | | constraints           | |
|       |        |  | |                       | |         | |                       | |
|       |        |  | '-----------------------' |         | '-----------------------' |
|       |        |  |                           |         |                           |
|       |        |  |                           |Fetch    | .-----------------------. |
|       |        |  |                           |endpoint | | Subordinate Statement | |
|       +--------+--+---------------------------+---------+->                       | |
|                |  |                           |         | | Federation Entity Keys| |
|                |  |                           |         | | Metadata Policy       | |
|                |  |                           |         | | Metadata              | |
|                |  |                           |         | |                       | |
|                |  |                           |         | '-----------.-----------' |
| .------------. |  | .-----------------------. |         |             |             |
| |            | |  | | Entity Configuration  | |         |             |             |
| |Intermediate+-+--+->                       | |         |             |sub and key  |
| |            | |  | | Federation Entity Keys| |         |             | binding     |
| '------.-----' |  | | Metadata              | |         | .-----------v-----------. |
|        |       |  | | Trust Marks           | |         | | Subordinate Statement | |
|        |       |  | |                       | |         | |                       | |
|        |       |  | |                       | |         | | Federation Entity Keys| |
|        |       |  | '-----------------------' |Fetch    | | Metadata Policy       | |
|        |       |  |                           |endpoint | | Metadata              | |
|        +-------+--+---------------------------+---------+->                       | |
|                |  |                           |         | '-----------.-----------' |
|                |  |                           |         |             |sub and key  |
|                |  |                           |         |             | binding     |
| .------------. |  | .-----------------------. |         | .-----------v-----------. |
| |            | |  | | Entity Configuration  | |         | | Entity Configuration  | |
| | Leaf       +-+--+->                       +-+---------+->                       | |
| |            | |  | | Federation Entity Keys| |         | | Federation Entity Keys| |
| '------------' |  | | Metadata              | |         | | Metadata              | |
|                |  | | Trust Marks           | |         | | Trust Marks           | |
|                |  | |                       | |         | |                       | |
|                |  | |                       | |         | |                       | |
|                |  | '-----------------------' |         | '-----------------------' |
'----------------'  '---------------------------'         '---------------------------'

Figure 5: Relationships between Federation Entities and Statements Issued in a Trust Chain

4.3. Trust Chain Header Parameter

The trust_chain JWS header parameter is a JSON array containing the sequence of the statements that proves the trust relationship between the issuer of the JWS [RFC7515] and the selected Trust Anchor, sorted as shown in Section 4. The Trust Chain contains the public key used to verify the JWS [RFC7515]. The issuer of the JWS SHOULD select the Trust Anchor that it has in common with the audience of the JWS. Otherwise, the issuer is free to select a Trust Anchor. All signed JWTs MAY include the trust_chain JWS header parameter. However, there are exceptions to this rule. The Entity Configurations and Subordinate Statements MUST NOT contain the trust_chain header parameter, as they are integral components of a Trust Chain. Additionally, the Authorization Signed Request Object SHOULD NOT contain the trust_chain header parameter, because the trust_chain parameter is intended to be part of its JWS payload, as defined in Section 12.1.1.1. Use of this header parameter is OPTIONAL.

The following is a non-normative example of a JWS header with the trust_chain parameter.

{
  "alg": "RS256",
  "kid": "SUdtUndEWVY2cUFDeDV5NVlBWDhvOXJodVl2am1mNGNtR0pmd",
  "trust_chain": [
      "eyJhbGciOiJSUzI1NiIsImtpZCI6ImMzWnlUR1ZTY0RNeFowd3dka1pQVVZZMFMyRkVRMnBYVjE4dFVFd3ROVlZIV21WVVEwTmlTM2xVU1EiLCJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCJ9.eyJleHAiOjE2OTY1ODMzMzQsImlhdCI6MTY5NjI4MzMzNCwiaXNzIjoiaHR0cHM6Ly9jcmVkZW50aWFsX2lzc3Vlci5leGFtcGxlLm9yZyIsInN1YiI6Imh0dHBzOi8vY3JlZGVudGlhbF9pc3N1ZXIuZXhhbXBsZS5vcmciLCJqd2tzIjp7ImtleXMiOlt7Imt0eSI6IlJTQSIsImtpZCI6ImMzWnlUR1ZTY0RNeFowd3dka1pQVVZZMFMyRkVRMnBYVjE4dFVFd3ROVlZIV21WVVEwTmlTM2xVU1EiLCJlIjoiQVFBQiIsIm4iOiIwNmZfWUd0ejhyY29WQWZSUnlNbldYbmNteVRFc3lmUHh6OVlXdlRjT0c1WGtIQ244c1ZCa3hjVENleDFvdWtxZVlVLU0xcUE3ZXE4RmNMRDJHUEVxVHNITDBRNVNMLXVYSUlYd2hSSmx3bWpRNWh1dEdnV3ptMUVOc0g0SENyV3EwNmJGLTRpUFFpUVUxRm1kVXdxVTI5clVqTnlmeUlLTmd1cFJPZ2p1Y3ozcWYtWE1ZdU5SRnFFcld0b3N0dHE1bm4zdFlSNWh5UWpVWnVwNHZPUnFhUUROMUxiVEk5d2cxRzlxRjlxQUxDcGk0WlNmclJyWEphZDUtamwtS1VOdFM1cG5hbGlHRFF2a3AxTnJCaXBJT19haTFvR21BMTlHd1E4VGpNVkNFc3ZXUXpKcTVrd0N1eHVKZTlBODE1RzRuU2I1WFp1RXZ6anhNU1M4b3hpLVEifV19LCJtZXRhZGF0YSI6eyJvcGVuaWRfY3JlZGVudGlhbF9pc3N1ZXIiOnsiandrcyI6eyJrZXlzIjpbeyJrdHkiOiJSU0EiLCJraWQiOiJSMlJ6UlhBMFJWQnlkekZPVkcxZmRXUlRNVFozWVRSbU5uRTFWM0ZmTUUxb01VWkxla2xpWTFOWU9BIiwiZSI6IkFRQUIiLCJuIjoiNUhfWGg3eGdEV1R4UVZiSnFtT0d1cm9rRThrcjJlMUtnTVdjWU9BNzRPXzFQWGQydWdqeUlxOXQxbVZQU3V3eC10eVNrMlBLcGpwLS1XckhuM0E0VUtKa3VSMTF6aG1kTEJzVThUT0JCdTVNWjhhdER1amZSd0lMWGRLc0VYa2x2YUI2UExUNHpkWm9kZ0NzMDVLeTJlNXNiNXo2X0NpRHFnVVZuV1BtSkxNa2dwQnRaLWtNZF9sYjlTb29abGxmVUdsVGtzYXVKMl9nVlEtVnBGVU1YWWpvSmpOeDk3ZXVrYVluUkVvQ0MzVGFfLThiY1Jvc2x4MnhySWJ1X1VHVnFpcGVOM05QLW1lZmY5VlRaV1lNM2dtb2x3dXBuTUNYWGlpa2NSNVVTTFZnMGVfZ3o2T2ZvUlZHS0FXSXBSUkxUejJhaXF1a1ZIWmRaWDl0Tm16MG13In1dfX0sImZlZGVyYXRpb25fZW50aXR5Ijp7Im9yZ2FuaXphdGlvbl9uYW1lIjoiT3BlbklEIENyZWRlbnRpYWwgSXNzdWVyIGV4YW1wbGUiLCJob21lcGFnZV91cmkiOiJodHRwczovL2NyZWRlbnRpYWxfaXNzdWVyLmV4YW1wbGUub3JnL2hvbWUiLCJwb2xpY3lfdXJpIjoiaHR0cHM6Ly9jcmVkZW50aWFsX2lzc3Vlci5leGFtcGxlLm9yZy9wb2xpY3kiLCJsb2dvX3VyaSI6Imh0dHBzOi8vY3JlZGVudGlhbF9pc3N1ZXIuZXhhbXBsZS5vcmcvc3RhdGljL2xvZ28uc3ZnIiwiY29udGFjdHMiOlsidGVjaEBjcmVkZW50aWFsX2lzc3Vlci5leGFtcGxlLm9yZyJdfX0sImF1dGhvcml0eV9oaW50cyI6WyJodHRwczovL2ludGVybWVkaWF0ZS5laWRhcy5leGFtcGxlLm9yZyJdfQ.WM0dOdLOhC9UTRi_y6lwwu6PmUWv1wc5f8MhKP2qz6b1haa-eyf4Y60iZ2SDeFeg105wHwPSKN8AfRoNyqubOGZMAFmP-sYBeqZatNsGNWjFEHzI9dJwx1oBab5_TDoULarpKSdvuub4NBOBTKFUSDffBG6jzlaK5JiQzMR30-jqSt9qPPWrJepyLQvyFxmvn94OiNQQwJ0oYB1MecJ7r8gmQMCAH4LixD6amKQoCuN0UeN7iEHTs3z_8ZUDihQ7BHf0dtwDCmG_G7xvaNkLPkG6cP2e2-l5kcYbNaUaK0IsX2yB0BkoQOOHlT-_M2TC2Zzg6Nmmw8WpTeraMrSkIQ",
      "eyJhbGciOiJSUzI1NiIsImtpZCI6IlpsSndObTQ1VDJsVWNYbEhUR2cxWldobGJsZGpVV2xsY21RdFNVbFFXWHBIUzFKRVEwOHlUV1Z2TkEiLCJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCJ9.eyJleHAiOjE2OTY1ODMzMzQsImlhdCI6MTY5NjI4MzMzNCwiaXNzIjoiaHR0cHM6Ly9pbnRlcm1lZGlhdGUuZWlkYXMuZXhhbXBsZS5vcmciLCJzdWIiOiJodHRwczovL2NyZWRlbnRpYWxfaXNzdWVyLmV4YW1wbGUub3JnIiwiandrcyI6eyJrZXlzIjpbeyJrdHkiOiJSU0EiLCJraWQiOiJjM1p5VEdWU2NETXhaMHd3ZGtaUFVWWTBTMkZFUTJwWFYxOHRVRXd0TlZWSFdtVlVRME5pUzNsVVNRIiwiZSI6IkFRQUIiLCJuIjoiMDZmX1lHdHo4cmNvVkFmUlJ5TW5XWG5jbXlURXN5ZlB4ejlZV3ZUY09HNVhrSENuOHNWQmt4Y1RDZXgxb3VrcWVZVS1NMXFBN2VxOEZjTEQyR1BFcVRzSEwwUTVTTC11WElJWHdoUkpsd21qUTVodXRHZ1d6bTFFTnNINEhDcldxMDZiRi00aVBRaVFVMUZtZFV3cVUyOXJVak55ZnlJS05ndXBST2dqdWN6M3FmLVhNWXVOUkZxRXJXdG9zdHRxNW5uM3RZUjVoeVFqVVp1cDR2T1JxYVFETjFMYlRJOXdnMUc5cUY5cUFMQ3BpNFpTZnJSclhKYWQ1LWpsLUtVTnRTNXBuYWxpR0RRdmtwMU5yQmlwSU9fYWkxb0dtQTE5R3dROFRqTVZDRXN2V1F6SnE1a3dDdXh1SmU5QTgxNUc0blNiNVhadUV2emp4TVNTOG94aS1RIn1dfX0.GxUAOCfVHTyBvJzq9BIV76fX-bRqIVcL-Y36B8NLO17lE0rkfDQQGUh-Vh1JmF_MF3Q4QhXjW-agXoKST3q9x5nDoYHTleQ-10Lw9qiU9I6K8mn1JMNXahzNaX_MLOA7R3_O0-HhxtARIEKpiGQTjup_f5PyqBLrwcERxhnbg0YrpgsvVQHC1SUgXiMtKxMZDWLUtk7q8YaNNhJ4nuEV2M1ZWcEVFloWYKWBJbJvmZ9jqsop6svMDOqusih3sNGWKZ9XmPqtUeGR8o1vsKsOk0WKVnEMH9ESGu54pUJahX05jd4UmTPOzfRJ61k9-_te6xNZUwJqtU9wJ--IrHz7ig",
      "eyJhbGciOiJSUzI1NiIsImtpZCI6IlpXRlRRbWhmVFdaSVRuRlRZM0ZTV2pKdU5HMWZWV05hZWxkNmNtUjFRa0pEYlhaWlRYQm1hM1JWUVEiLCJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCJ9.eyJleHAiOjE2OTY1ODMzMzQsImlhdCI6MTY5NjI4MzMzNCwiaXNzIjoiaHR0cHM6Ly90cnVzdC1hbmNob3IuZXhhbXBsZS5vcmciLCJzdWIiOiJodHRwczovL2ludGVybWVkaWF0ZS5laWRhcy5leGFtcGxlLm9yZyIsImp3a3MiOnsia2V5cyI6W3sia3R5IjoiUlNBIiwia2lkIjoiWmxKd05tNDVUMmxVY1hsSFRHZzFaV2hsYmxkalVXbGxjbVF0U1VsUVdYcEhTMUpFUTA4eVRXVnZOQSIsImUiOiJBUUFCIiwibiI6ImtSQUlzLVRBblF6T29lc195RW9oaDNUeGlaWFlPRC1xekI2T25JalZCaVI0WFNGbkw4djhRQ0IxamJiSlZTQ1hBZmdObTlBZjdVRDNBX0E2T1pQOUtacldSUk00NEp0TVAzZmxVSU5CQ2xzNFBrdVd2RklmWEtaaWVUNGhBMzNYdUlTSndqT2NlNnRrbUZTUl9wQmI3S0JHbnB4d3dnRlJjeUM2RU1VQWtWUGdQRl9mbXM3NEEyTF83TGVaNzh2X053VUhsY2VxVHB1OUx6VTRuTTd1RTZQY0JPSmJweXI2SFFuUTR1VHN6WThsWHVmT3pHZ2IzVXNDNmRnQWVVVERIZlFROE4xYXV2bkJUNmR0SHNHNWMxS2NCT2QzLVp6ZTZ5WVE5c2JLUlUtWVoydDZKdUJIbS1xLTVOamxiRWVwNDAwbFgxSXlKdG9Tc3F0d3lCX1djdyJ9XX19.CvBvN0aG-r13UG4uITH72tC5CbAG0rT4qYQ5wwHOtGE021etZFQd40RFnQT5e-Gy_Y8Wiin-Zmc1hWW2rVyZ1RRInjYGUt26QI6ujR-5w9Y_LHVp-6RzYEF0lg9otpAyszQE4hf5qBZYAj8t39FvCYWTYVci6mtpovJQ380ha8I4QL__fZtEgDLQ-7VKS58nN1DOVdcIICMMfxpDR81bkY5i5Qxcy7AaZTN6xxE2SlCO-pKKub0jBUtnug20-BL2YgcPhLFOYWfj2cuyapOA9Omwu6CPhmZHgsL1P2oK_f4jA9JxNDYcV0losDbD86r8Wg3anM2lVM5BTHkiUr2grg",
      "eyJhbGciOiJSUzI1NiIsImtpZCI6IlpXRlRRbWhmVFdaSVRuRlRZM0ZTV2pKdU5HMWZWV05hZWxkNmNtUjFRa0pEYlhaWlRYQm1hM1JWUVEiLCJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCJ9.eyJleHAiOjE2OTY1ODMzMzQsImlhdCI6MTY5NjI4MzMzNCwiaXNzIjoiaHR0cHM6Ly90cnVzdC1hbmNob3IuZXhhbXBsZS5vcmciLCJzdWIiOiJodHRwczovL3RydXN0LWFuY2hvci5leGFtcGxlLm9yZyIsImp3a3MiOnsia2V5cyI6W3sia3R5IjoiUlNBIiwia2lkIjoiWldGVFFtaGZUV1pJVG5GVFkzRlNXakp1TkcxZlZXTmFlbGQ2Y21SMVFrSkRiWFpaVFhCbWEzUlZRUSIsImUiOiJBUUFCIiwibiI6InhPQnN0YnJUUE9SQ3JnTXowQ254Skk4cjd4TkwwYjZITExKY05NSkNQbGl0SmUzNUZUdGw1bVdMVXFoeFdiRXFYYnpVLW80VHd1ZHA5NHFrckI3Zks5cEk0bDBldEoxMFZTbTQ0dXNiakxoMTUwVXFlSnlmQmdyMzRWbWhINWo3ZFMzS3V5bjNvOEdER2ZjNDVjcmdsR3lNOUgzbFp6SGl6SXdncDVzSUhCeGFPRWQ1eXlOdXhBLXFFQU4zaFIxQi1LQ2JYaWVDRVRrcWNMWU1zX2psRHVsTVE0MzI5TEgwNkhaclhINElfUHVnWXd0WldUN0VqZUR6c3Y2Ny14TFFhOEg3cnV1N3JVME1FREl0TkVpS3ljdVk5b0pLWWtrX2hBQzFMNkt2VkNmeXpVOGVvem9KQzM4eGhXUklNTXJZd2hiSmFaa3dUdDZCRDByalNNRUp6USJ9XX0sIm1ldGFkYXRhIjp7ImZlZGVyYXRpb25fZW50aXR5Ijp7ImZlZGVyYXRpb25fZmV0Y2hfZW5kcG9pbnQiOiJodHRwczovL3RydXN0LWFuY2hvci5leGFtcGxlLm9yZy9mZXRjaCIsImZlZGVyYXRpb25fcmVzb2x2ZV9lbmRwb2ludCI6Imh0dHBzOi8vdHJ1c3QtYW5jaG9yLmV4YW1wbGUub3JnL3Jlc29sdmUiLCJmZWRlcmF0aW9uX2xpc3RfZW5kcG9pbnQiOiJodHRwczovL3RydXN0LWFuY2hvci5leGFtcGxlLm9yZy9saXN0Iiwib3JnYW5pemF0aW9uX25hbWUiOiJUQSBleGFtcGxlIiwiaG9tZXBhZ2VfdXJpIjoiaHR0cHM6Ly90cnVzdC1hbmNob3IuZXhhbXBsZS5vcmcvaG9tZSIsInBvbGljeV91cmkiOiJodHRwczovL3RydXN0LWFuY2hvci5leGFtcGxlLm9yZy9wb2xpY3kiLCJsb2dvX3VyaSI6Imh0dHBzOi8vdHJ1c3QtYW5jaG9yLmV4YW1wbGUub3JnL3N0YXRpYy9sb2dvLnN2ZyIsImNvbnRhY3RzIjpbInRlY2hAdHJ1c3QtYW5jaG9yLmV4YW1wbGUub3JnIl19fSwiY29uc3RyYWludHMiOnsibWF4X3BhdGhfbGVuZ3RoIjoxfX0.ZenICRAm4zrd65A3tsSN77VLjheJAK09s8sBXQVo2l3r7RrN8pXFKqulZebxfSALF4am58Ry8GeK2N1ZK7B1GlfskAnnIINfi-IpjqquvPW_MXrSo0bLoXnnmruHJ1D0KbONbwdZaOZg4oJRo2PBU009pojheUwcRcNDujCRiQimsvEYlL4YLwpPHjEmt46WviPESnZCgez_oEdoXkNjN3PsOta9de_abjkASYdGgAlBTIbUjAutmErbubjKptxpvycibBLuJ58nkiQZ_KesLRPnDY9hbPf0ZMbtCB_gx8yLlQ9-8nE5_fuxICz1uKR4536txsQFmrCvireBchaZ1A"
  ]
}

Figure 6: Example JWS Header with a trust_chain Parameter

5. Metadata

This section defines how to represent and use metadata about Entities. It reuses existing OpenID Connect and OAuth 2.0 metadata standards that are applicable to each Entity Type.

As described in Section 3, Entity metadata is located in the metadata claim of an Entity Statement, whose value is a JSON object. The member names of this object are Entity Type Identifiers, as specified in Section 5.1. The metadata data structure following each Entity Type Identifier is a JSON object; it MAY be the empty JSON object {}, which may be the case when Superiors supply any needed metadata values.

Top-level JSON object members in the metadata data structures MAY use any JSON value other than null; the use of null is prohibited to prevent likely implementation errors caused by confusing members having null values with omitted members.

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 a federation_entity Entity Type Identifier as well as identifiers for OpenID Connect and OAuth 2.0 Federation Entities.

Additional Entity Type Identifiers MAY be defined to support use cases outside OpenID Connect and OAuth 2.0 federations.

5.1.1. Federation Entity

The Entity Type Identifier is federation_entity.

All Entities in a federation MAY use this Entity Type. The Entities that provide federation API endpoints MUST use this Entity Type.

The following Federation Entity properties are defined:

federation_fetch_endpoint
OPTIONAL. The fetch endpoint described in Section 8.1. This URL MUST use the https scheme and MAY contain port, path, and query parameter components encoded in application/x-www-form-urlencoded format; it MUST NOT contain a fragment component. Intermediate Entities and Trust Anchors MUST publish a federation_fetch_endpoint. Leaf Entities MUST NOT.
federation_list_endpoint
OPTIONAL. The list endpoint described in Section 8.2. This URL MUST use the https scheme and MAY contain port, path, and query parameter components encoded in application/x-www-form-urlencoded format; it MUST NOT contain a fragment component. Intermediate Entities and Trust Anchors MUST publish a federation_list_endpoint. Leaf Entities MUST NOT.
federation_resolve_endpoint
OPTIONAL. The resolve endpoint described in Section 8.3. This URL MUST use the https scheme and MAY contain port, path, and query parameter components encoded in application/x-www-form-urlencoded format; it MUST NOT contain a fragment component. Any federation Entity MAY publish a federation_resolve_endpoint.
federation_trust_mark_status_endpoint
OPTIONAL. The Trust Mark status endpoint described in Section 8.4. Trust Mark issuers SHOULD publish a federation_trust_mark_status_endpoint. This URL MUST use the https scheme and MAY contain port, path, and query parameter components encoded in application/x-www-form-urlencoded format; it MUST NOT contain a fragment component.
federation_trust_mark_list_endpoint
OPTIONAL. The endpoint described in Section 8.5. This URL MUST use the https scheme and MAY contain port, path, and query parameter components encoded in application/x-www-form-urlencoded format; it MUST NOT contain a fragment component. Trust Mark issuers MAY publish a federation_trust_mark_list_endpoint.
federation_trust_mark_endpoint
OPTIONAL. The endpoint described in Section 8.6. This URL MUST use the https scheme and MAY contain port, path, and query parameter components encoded in application/x-www-form-urlencoded format; it MUST NOT contain a fragment component. Trust Mark issuers MAY publish a federation_trust_mark_endpoint.
federation_historical_keys_endpoint
OPTIONAL. The endpoint described in Section 8.7. This URL MUST use the https scheme and MAY contain port, path, and query parameter components encoded in application/x-www-form-urlencoded format; it MUST NOT contain a fragment component. All Federation Entities MAY publish a federation_historical_keys_endpoint.

It is RECOMMENDED that each Federation Entity contain an organization_name claim, as defined in Section 5.2.2.

The following is a non-normative example of the federation_entity Entity Type:

"federation_entity": {
  "federation_fetch_endpoint":
    "https://amanita.caesarea.example.com/federation_fetch",
  "federation_list_endpoint":
    "https://amanita.caesarea.example.com/federation_list",
  "federation_trust_mark_status_endpoint": "https://amanita.caesarea.example.com/status",
  "federation_trust_mark_list_endpoint": "https://amanita.caesarea.example.com/trust_marked_list",
  "organization_name": "Ovulo Mushroom",
  "homepage_uri": "https://amanita.caesarea.example.com"
}
Figure 7: Example of federation_entity Entity Type

5.1.2. 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] and Section 5.2 are applicable, as well as additional parameters registered in the IANA "OAuth Dynamic Client Registration Metadata" registry [IANA.OAuth.Parameters].

In addition, the following RP metadata parameter is defined:

client_registration_types
REQUIRED. An array of strings specifying the client registration types the RP supports. Values defined by this specification are automatic and explicit.

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 8: Example Relying Party Entity Configuration JWT Claims Set

5.1.3. 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 are applicable, as well as additional parameters registered in the IANA "OAuth Authorization Server Metadata" registry [IANA.OAuth.Parameters].

In addition, the following OP metadata parameters are defined:

client_registration_types_supported
REQUIRED. Array specifying the federation types supported. Federation-type values defined by this specification are automatic and explicit.
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 encoded in application/x-www-form-urlencoded format; 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.
request_authentication_methods_supported

OPTIONAL. An OP MUST be able to verify that a request comes from an RP that is a member of a federation that the OP is a member of. This is done via request authentication methods. These methods achieve this by proving that the RP is in possession of a key that appears in its metadata. This parameter declares the request authentication methods that the OP supports.

The request_authentication_methods_supported value is a JSON object where the member names are names of endpoints where the request authentication occurs. This MAY be either at the OP's Authorization Endpoint or the OP's Pushed Authorization Request (PAR) endpoint. Supported endpoint identifiers are authorization_endpoint and pushed_authorization_request_endpoint. The values of the JSON object members for the endpoint names are JSON arrays containing the names of the request authentication methods used at those endpoints.

Some OAuth 2.0 client authentication methods can be used at the pushed_authorization_request_endpoint to achieve request authentication. They are the subset of those listed in the IANA "OAuth Token Endpoint Authentication Methods" registry [IANA.OAuth.Parameters] that perform client authentication by proving possession of a private key. These client authentication methods are:

private_key_jwt
This client authentication method is described in Section 9 of OpenID Connect Core 1.0 [OpenID.Core]. Note that if private_key_jwt is used, the audience of the signed JWT MUST be either the URL of the Authorization Server's Authorization Endpoint or the Authorization Server's Entity Identifier.
tls_client_auth
Section 2.1 of [RFC8705].
self_signed_tls_client_auth
Section 2.2 of [RFC8705].

A request authentication method that is not a client authentication method is:

request_object
Use of a Request Object, as described in OpenID Connect Core 1.0 [OpenID.Core]. The request authentication is performed by verifying that the request object is signed with a key that the RP controls. Use of Request Objects by Automatic Registration is described in Section 12.1.

The request_object method MAY be used at either endpoint.

Additional request authentication methods MAY be defined and used.

request_authentication_signing_alg_values_supported
OPTIONAL. JSON array containing a list of the supported JWS [RFC7515] algorithms (alg values) for signing the JWT [RFC7519] used in the Request Object contained in the request parameter of an authorization request or in the private_key_jwt of a pushed authorization request. This entry MUST be present if either of these authentication methods are specified in the request_authentication_methods_supported entry. No default algorithms are implied if this entry is omitted. Servers SHOULD support RS256. The value none MUST NOT be used.

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/openid",
         "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_authentication_methods_supported": {
            "authorization_endpoint": [
                "request_object"
            ],
            "pushed_authorization_request_endpoint": [
                "request_object",
                "private_key_jwt",
                "tls_client_auth",
                "self_signed_tls_client_auth"
            ]
        }
      }
   },
   "authority_hints":[
      "https://umu.se"
   ],
   "jwks":{
      "keys":[
         {
            "e":"AQAB",
            "kid":"dEEtRjlzY3djcENuT01wOGxrZlkxb3RIQVJlMTY0...",
            "kty":"RSA",
            "n":"x97YKqc9Cs-DNtFrQ7_vhXoH9bwkDWW6En2jJ044yH..."
         }
      ]
   }
}
Figure 9: Example OpenID Provider Entity Configuration JWT Claims Set

5.1.4. OAuth Authorization Server

The Entity Type Identifier is oauth_authorization_server.

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

5.1.5. 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 are applicable, as well as additional parameters registered in the IANA "OAuth Dynamic Client Registration Metadata" registry [IANA.OAuth.Parameters].

5.1.6. OAuth Protected Resource

The Entity Type Identifier is oauth_resource. The parameters defined in Section 5.2 are applicable. In addition, while it is not yet a standard, deployments MAY use the protected resource metadata parameters defined in [I-D.ietf-oauth-resource-metadata].

5.2. Common Metadata Parameters

This section defines additional metadata parameters that MAY be used with all the Entity Types above.

5.2.1. Extensions for JWK Sets in Entity Metadata

The following metadata parameters define ways of obtaining JWK Sets for an Entity Type of the Entity. Note that these keys are distinct from the Federation Entity Keys used to sign Entity Statements.

signed_jwks_uri
OPTIONAL. URL referencing a signed JWT having the Entity's JWK Set document for that Entity Type as its payload. The JWT MUST be signed using a Federation Entity Key. This URL MUST use the https scheme. When both signing and encryption keys are made available, a use (public key use) parameter value is REQUIRED for all keys in the referenced JWK Set to indicate each key's intended usage.

The following claims are specified for use in the payload, all of which except keys are defined in [RFC7519]:

keys
REQUIRED. Array of JWK values.
iss
REQUIRED. The "iss" (issuer) claim identifies the principal that issued the JWT.
sub
REQUIRED. This claim identifies the owner of the keys. It SHOULD be the same as the issuer.
iat
OPTIONAL. Number. Time when this signed JWK Set was issued. This is expressed as Seconds Since the Epoch, as defined in [RFC7519].
exp
OPTIONAL. Number. This claim identifies the time when the JWT is no longer valid. This is expressed as Seconds Since the Epoch, as defined in [RFC7519].

More claims are defined in [RFC7519]; of these, aud SHOULD NOT be used since the issuer cannot know who the audience is. nbf and jti are not particularly useful in this context and SHOULD be omitted.

Additional claims MAY be defined and used in conjunction with the claims above.

The following is a non-normative example of the JWT Claims Set for a signed JWK Set.

    {
      "keys": [
        {
          "kty": "RSA",
          "kid": "SUdtUndEWVY2cUFDeDV5NVlBWDhvOXJodVl2am1mNGNtR0pmd",
          "n": "y_Zc8rByfeRIC9fFZrDZ2MGH2ZnxLrc0ZNNwkNet5rwCPYeRF3Sv
                5nihZA9NHkDTEX97dN8hG6ACfeSo6JB2P7heJtmzM8oOBZbmQ90n
                EA_JCHszkejHaOtDDfxPH6bQLrMlItF4JSUKua301uLB7C8nzTxm
                tF3eAhGCKn8LotEseccxsmzApKRNWhfKDLpKPe9i9PZQhhJaurwD
                kMwbWTAeZbqCScU1o09piuK1JDf2PaDFevioHncZcQO74Obe4nN3
                oNPNAxrMClkZ9s9GMEd5vMqOD4huXlRpHwm9V3oJ3LRutOTxqQLV
                yPucu7eHA7her4FOFAiUk-5SieXL9Q",
          "e": "AQAB"
        },
        {
          "kty": "EC",
          "kid": "MFYycG1raTI4SkZvVDBIMF9CNGw3VEZYUmxQLVN2T21nSWlkd3",
          "crv": "P-256",
          "x": "qAOdPQROkHfZY1daGofOmSNQWpYK8c9G2m2Rbkpbd4c",
          "y": "G_7fF-T8n2vONKM15Mzj4KR_shvHBxKGjMosF6FdoPY"
        }
      ],
      "iss": "https://example.org/op",
      "sub": "https://example.org/op",
      "iat": 1618410883
    }

Figure 10: Example JWT Claims Set for a Signed JWK Set
jwks_uri
OPTIONAL. URL referencing a JWK Set document containing the Entity's keys for that Entity Type. This URL MUST use the https scheme. When both signing and encryption keys are made available, a use (public key use) parameter value is REQUIRED for all keys in the referenced JWK Set to indicate each key's intended usage.
jwks
OPTIONAL. JSON Web Key Set document, passed by value, containing the Entity's keys for that Entity Type. This parameter is intended to be used by participants that, for some reason, cannot use the signed_jwks_uri parameter. An upside of using jwks is that the Entity's keys for the Entity Type are recorded in Trust Chains.
5.2.1.1. Usage of jwks, jwks_uri, and signed_jwks_uri in Entity Metadata

It is RECOMMENDED that an Entity Configuration use only one of jwks, jwks_uri, and signed_jwks_uri in its OpenID Connect or OAuth 2.0 metadata. However, there may be circumstances in which is it desirable to use multiple JWK Set representations, such as when an Entity is in multiple federations and the federations have different policies about the JWK Set representation to be used. When multiple JWK Set representations are used, the keys present in each representation SHOULD be the same. Even if they are not completely the same at a given instant in time (which may be the case during key rollover operations), implementations MUST make them consistent in a timely manner.

5.2.2. Informational Metadata Extensions

The following metadata parameters define ways of obtaining information about the Entity for an Entity Type.

organization_name
OPTIONAL. A human-readable name representing the organization owning this Entity. If the owner is a physical person, this MAY be, for example, the person's name. Note that this information will be publicly available.
contacts
OPTIONAL. JSON array with one or more strings representing contact persons at the Entity. These MAY contain names, e-mail addresses, descriptions, phone numbers, etc.
logo_uri
OPTIONAL. String. A URL that points to the logo of this Entity. The file containing the logo SHOULD be published in a format that can be viewed via the web.
policy_uri
OPTIONAL. URL of the documentation of conditions and policies relevant to this Entity.
homepage_uri
OPTIONAL. URL of a Web page for the organization owning this Entity.

It is RECOMMENDED that, when present, these metadata parameters occur in an Entity's federation_entity metadata. They MAY also be present in the Entity's metadata for other Entity Types, particularly when the values for those Entity Types differ from those for the federation_entity metadata.

6. Federation Policy

6.1. Metadata Policy

Trust Anchors and Intermediate Entities MAY define policies that apply to the metadata of their Subordinates.

A federation may utilize metadata policies to achieve specific objectives. For example, in a federation of OpenID Connect [OpenID.Core] Entities, one objective may be to ensure the metadata published by OpenID Providers and Relying Parties are interoperable with one another. Another objective may be to ensure the Entity metadata complies with a security profile, for example, FAPI [FAPI].

Note that the metadata_policy is not intended to check and validate the JSON value types of metadata parameters. Such checks SHOULD be performed at the application layer, after obtaining the Entity metadata from a successfully resolved Trust Chain.

6.1.1. Principles

OpenID Federation enables the definition of metadata policies with the following properties:

Hierarchy

Once applied to a metadata parameter, a metadata policy cannot be repealed or made more permissive by Intermediate Entities that are subordinate in the Trust Chain.

The hierarchy of policies is preserved in nested federations where a Trust Anchor in one federation acts as an Intermediate Entity in another federation.

Equal Opportunity
All Superior Entities in a Trust Chain can contribute to metadata policies of the Trust Chain subject on an equal basis. For instance, any Intermediate can further restrict the metadata of its Subordinates relative to what its Superiors specified.
Specificity and Granularity

Just like metadata, a metadata policy is bound to a specific Entity Type. This ensures policies for different Entity Types are independent and isolated from one another.

Policies are expressed at the level of individual metadata parameters. The policies for a given Entity Type metadata parameter are thus independent and isolated from those for other parameters.

When a Trust Anchor or an Intermediate Entity defines a metadata policy for an Entity Type, it applies to the metadata of all Subordinate Entities of that type in the Trust Chain.

Because the place to define a policy is the Subordinate Statement and every Entity Statement is issued for a specific subject, a federation authority can choose to define a common Entity Type metadata policy for all its Subordinates, or specific Entity Type metadata policies for specific Subordinates.

Operation
A policy operates by performing a check, a modification, or both on a given metadata parameter. This specification defines a set of standard operators, described in Section 6.1.3.1. A federation MAY specify and use additional operators, provided they comply with the principles laid out in this section and with Section 6.1.3 and Section 6.1.3.2.
Integral Metadata Enforcement

The resolution and application of metadata policies is an integral part of the Trust Chain resolution process, as described in Section 10.

This means:

  • A Trust Chain for which the metadata policy resolution fails due to an error, for example, due to an Intermediate Entity’s policy conflicting with a Superior’s policy, is deemed invalid.

  • A Trust Chain with Entity metadata that does not comply with the resolved metadata policies is deemed invalid.

Determinism
The resolution and application of metadata policies in a Trust Chain is deterministic. Trust Anchors and Intermediate Entities are thus able to formulate policies that exhibit predictable and reproducible outcomes.

6.1.2. Structure

Metadata policies are expressed in the metadata_policy claim of a Subordinate Statement, as described in Section 3. The claim value is a JSON object that has a data structure consisting of three levels:

  1. Metadata policies for Entity Types.

    The top level contains one or more members, each representing the metadata policy for an Entity Type. Each member name is an Entity Type Identifier, as specified in Section 5.1, for example, openid_relying_party. The member value is a JSON object that contains metadata parameter policies.

  2. Metadata parameter policies for the Entity Type.

    The second level contains one or more members, each representing a policy for a metadata parameter for the Entity Type. Each member name is a metadata parameter name, for example id_token_signed_response_alg. The name MAY include a language tag, as described in Section 14, in which case the metadata parameter policy applies only to the metadata parameter with the specified language tag. The member value is a JSON object that contains policy operators.

  3. Operators for the metadata parameter policy for the Entity Type.

    The third level contains one or more members, each representing an operator that checks or modifies the metadata parameter, as described in Section 6.1.3. Only operators that are allowed to be combined with one another MUST be included, as described in the specification for each operator.

Duplicate JSON object member names MUST NOT be present at any of the three levels of the metadata_policy claim data structure.

The following is a non-normative example of a metadata policy for an OpenID Relying Party that consists of a single policy for the id_token_signed_response_alg metadata parameter and uses two operators, default and one_of:

"metadata_policy" : {
  "openid_relying_party": {
    "id_token_signed_response_alg": {
      "default": "ES256",
      "one_of": ["ES256", "ES384", "ES512"]
    }
  }
}
Figure 11: Example metadata_policy Claim

6.1.3. Operators

A metadata policy operator:

  • Is identified by a unique case-sensitive name.

  • Acts on a single metadata parameter. The operator definition MUST specify the metadata parameter JSON value types that are mandatory to support and MAY also specify JSON value types that are optional to support. When the metadata parameter has a JSON value type that is not supported, the operator MUST produce a policy error.

  • The action on the metadata parameter can be a value check, a value modification, or both. When the operator’s action is a value modification, it MAY remove the metadata parameter.

  • The action of the operator is configured by a JSON value. The operator definition MUST specify the JSON value types that are mandatory to support and MAY also specify JSON value types that are optional to support. When the operator is configured with a JSON value type that isn’t supported, the operator MUST produce a policy error.

  • MUST declare what other operators it may be combined within a metadata parameter policy. Combinations that are not allowed MUST result in a policy error.

  • MUST declare in what order it is to be applied to a metadata parameter, absolute or relative to other operators in the metadata parameter policy. Value check operators SHOULD generally be applied after operators that perform value modifications.

  • MUST specify, when more than one Subordinate Statement in a Trust Chain has a policy for an Entity Type metadata parameter that uses the same operator, whether the operator values are allowed to be merged to produce an identical or more restrictive policy, and if so, under what conditions. If the operator does not allow such a merge, it MUST produce a policy error.

  • An operator MUST NOT output a metadata parameter with the null value.

6.1.3.1. Standard Operators

This specification defines the following metadata policy operators:

6.1.3.1.1. value

Name: value

Action: The metadata parameter MUST be assigned the value of the operator. When the value of the operator is null, the metadata parameter MUST be removed.

Metadata parameter JSON values:

  • Mandatory to support: string, number, boolean, object, array

Operator JSON values:

  • Mandatory to support: string, number, boolean, object, array, null

Combination with other operators in a metadata parameter policy:

  • MAY be combined with essential.

Order of application: First

Operator value merge: Allowed only when the operator values are equal. If not, this MUST result in a policy error.

6.1.3.1.2. add

Name: add

Action: The value or values of this operator MUST be added to the metadata parameter. Values that are already present in the metadata parameter MUST NOT be added another time. If the metadata parameter is absent, it MUST be initialized with the value of this operator.

Metadata parameter JSON values:

  • Mandatory to support: array of strings

  • Optional to support: array of objects, array of numbers

Operator JSON values:

  • Mandatory to support: array of strings

  • Optional to support: array of objects, array of numbers

Combination with other operators in a metadata parameter policy:

  • MAY be combined with default.

  • MAY be combined with subset_of, in which case the values of add MUST be a subset of the values of subset_of.

  • MAY be combined with superset_of, in which case the values of add MUST be a superset of the values of superset_of.

  • MAY be combined with essential.

Order of application: After value.

Operator value merge: The result of merging the values of two add operators is the union of the values.

6.1.3.1.3. default

Name: default

Action: If the metadata parameter is absent, it MUST be set to the value of the operator. If the metadata parameter is present, this operator has no effect.

Metadata parameter JSON values:

  • Mandatory to support: string, number, boolean, object, array

Operator JSON values:

  • Mandatory to support: string, number, boolean, object, array

Combination with other operators in a metadata parameter policy:

  • MAY be combined with add.

  • MAY be combined with one_of, in which case the default value MUST be among the one_of values.

  • MAY be combined with subset_of, in which case the default values MUST be a subset of the subset_of values.

  • MAY be combined with superset_of, in which case the default values MUST be a superset of the superset_of values.

  • MAY be combined with essential.

Order of application: After add.

Operator value merge: The operator values MUST be equal. If the values are not equal this MUST result in a policy error.

6.1.3.1.4. one_of

Name: one_of

Action: If the metadata parameter is present, its value MUST be one of those listed in the operator value.

Metadata parameter JSON values:

  • Mandatory to support: string

  • Optional to support: object, number

Operator JSON values:

  • Mandatory to support: array of strings

  • Optional to support: array of objects, array of numbers

Combination with other operators in a metadata parameter policy:

  • MAY be combined with default, in which case the value of default MUST be among the one_of values.

  • MAY be combined with essential.

Order of application: After default.

Operator value merge: The result of merging the values of two one_of operators is the intersection of the operator values. If the intersection is empty, this MUST result in a policy error.

6.1.3.1.5. subset_of

Name: subset_of

Action: If the metadata parameter is present, this operator computes the intersection between the values of the operator and the metadata parameter. If the intersection is non-empty, the metadata parameter is set to the values in the intersection. If the intersection is empty, the metadata parameter MUST be removed. Note that this behavior makes subset_of a potential value modifier in addition to it being a value check.

Metadata parameter JSON values:

  • Mandatory to support: array of strings

  • Optional to support: array of objects, array of numbers

Operator JSON values:

  • Mandatory to support: array of strings

  • Optional to support: array of objects, array of numbers

Combination with other operators in a metadata parameter policy:

  • MAY be combined with add, in which case the values of add MUST be a subset of the values of subset_of.

  • MAY be combined with default, in which case the values of default MUST be a subset of the values of subset_of.

  • MAY be combined with superset_of, in which case the values of subset_of MUST be a superset of the values of superset_of.

  • MAY be combined with essential.

Order of application: After one_of.

Operator value merge: The result of merging the values of two subset_of operators is the intersection of the operator values. If the intersection is empty, this MUST result in a policy error.

6.1.3.1.6. superset_of

Name: superset_of

Action: If the metadata parameter is present, its values MUST contain those specified in the operator value. By mathematically defining supersets, equality is included.

Metadata parameter JSON values:

  • Mandatory to support: array of strings

  • Optional to support: array of objects, array of numbers

Operator JSON values:

  • Mandatory to support: array of strings

  • Optional to support: array of objects, array of numbers

Combination with other operators in a metadata parameter policy:

  • MAY be combined with add, in which case the values of add MUST be a superset of the values of superset_of.

  • MAY be combined with default, in which case the values of default MUST be a superset of the values of superset_of.

  • MAY be combined with subset_of, in which case the values of subset_of MUST be a superset of the values of superset_of.

  • MAY be combined with essential.

Order of application: After subset_of.

Operator value merge: The result of merging the values of two superset_of operators is the union of the operator values.

6.1.3.1.7. essential

Name: essential

Action: If the value of this operator is true, then the metadata parameter MUST be present. If false, the metadata parameter is voluntary and may be absent. If the essential operator is omitted, this is equivalent to including it with a value of false.

Metadata parameter JSON values:

  • Mandatory to support: string, number, boolean, object, array

Operator JSON values:

  • Mandatory to support: boolean

Combination with other operators in a metadata parameter policy:

  • MAY be combined with any other operator.

Order of application: Last

Operator value merge: If a Superior has specified essential=true, then a Subordinate MUST NOT change that. If a Superior has specified essential=false, then a Subordinate is allowed to change that to essential=true. If a Superior has not specified essential, then a Subordinate can set essential to true or false. If those conditions are not met, this MUST result in a policy error.

6.1.3.1.8. Notes on Operators

A "set equals" metadata parameter policy can be expressed by combining the operators subset_of and superset_of with identical array values.

The scope OAuth 2.0 client metadata parameter, defined in [RFC7591] and represented by a string of space-separated string values, is to be regarded and processed as a string array by policy operators, such as the operators default, subset_of and superset_of. The resulting scope metadata parameter is a space-separated string of individual scope values, where the scope values present are taken from the array of values produced by applying the metadata operators to the scope parameter.

The following table is a map of the outputs produced by combinations of the essential and subset_of policy operators with different input metadata parameter values. Note, the subset_of check is skipped when the metadata parameter is absent and designated as voluntary, as shown in the last row.

Table 1: Examples of Outputs with Combinations of essential and subset_of for Different Inputs
Policy Metadata Parameter
essential subset_of input output
true [a,b,c] [a,e] [a]
false [a,b,c] [a,e] [a]
true [a,b,c] [d,e] error
false [a,b,c] [d,e] no parameter
true [a,b,c] no parameter error
false [a,b,c] no parameter no parameter
6.1.3.2. Additional Operators

Federations MAY specify and use additional metadata policy operators that conform with the principles in Section 6.1.1 and in Section 6.1.3.

Additional operators MUST observe the following rules in regard to the order of their application relative to the standard operators defined in Section 6.1.3.1:

  • Additional operators that modify metadata parameters MUST be applied after the value operator that is specified in Section 6.1.3.1.1.

  • Additional operators that check metadata parameters MUST be applied before the essential operator that is specified in Section 6.1.3.1.7.

Implementations MUST ignore additional operators that are not understood, unless the operator name is included in the metadata_policy_crit Subordinate Statement claim, in which case the operator MUST be understood and processed. If an additional operator listed in metadata_policy_crit is not understood or cannot be processed, then this MUST result in a policy error and the Trust Chain MUST be considered invalid.

6.1.4. Enforcement

This section describes the resolution of the metadata policy for a Trust Chain and its application to the metadata of the Federation Entity that is the Trust Chain subject.

If a policy error or another error is encountered during the metadata policy resolution or its application, the Trust Chain MUST be considered invalid.

6.1.4.1. Resolution

The metadata policy for a Trust Chain is determined by the sequence of the present metadata_policy claims of the Subordinate Statements that make up the chain.

The resolution process MUST first gather the names of all policy operators other than the standard ones defined in Section 6.1.3.1 that are declared as critical. This is done by checking each Subordinate Statement in the Trust Chain for the optional metadata_policy_crit claim, described in Section 3, and collecting any operator names that are found in it.

The resolution process proceeds by iterating through the Subordinate Statements. The sequence of this iteration is crucial - it MUST begin with the Subordinate Statement issued by the most Superior Entity and end with the Subordinate Statement issued by the Immediate Superior of the Trust Chain subject.

An important procedure during the iteration is the metadata_policy validation. It MUST ensure the data structure is compliant and that every metadata parameter policy contains only allowed operator combinations, as described in Section 6.1.3, and in accordance with the specifications of the operators. It MUST be also ensured the metadata_policy contains no operators that cannot be understood and processed whose names are among the collected metadata_policy_crit values. An unsuccessful validation MUST result in a policy error.

At each iteration step, the Subordinate Statement MUST be checked for the presence of a metadata_policy claim. The first encountered metadata_policy MUST be validated as described above, after which it becomes the current metadata policy.

If the iteration yields a next subordinate metadata_policy claim, it MUST be validated as described above, then merged into the current metadata policy.

The merge is performed at all three levels of the metadata_policy data structure described in Section 6.1.2, by starting from the top level:

  1. The metadata policies for Entity Types.

  2. The metadata parameter policies for an Entity Type.

  3. The operators for a metadata parameter policy for an Entity Type.

At the level of metadata policies for Entity Types, the merge proceeds as follows:

  • If the next subordinate metadata_policy claim contains a metadata policy for an Entity Type that is already present in the current metadata policy, it MUST be merged according to the rules of the next lower level (the metadata parameter policies).

  • Entity Type metadata policies in the next subordinate metadata_policy claim that are not present in the current metadata policy MUST be copied to it.

At the level of metadata parameter policies, the merge proceeds as follows:

  • If a metadata parameter policy is already present in the current Entity Type metadata policy, it MUST be merged according to the rules of the next lower level (the operators for the metadata parameter policy). If the resulting metadata parameter policy contains combinations that are not allowed, as described in Section 6.1.3 and in accordance with the specifications of the operators, this MUST result in a policy error.

  • Subordinate metadata parameter policies that are not present in the current Entity Type metadata policy MUST be copied to it.

At the level of operators, the merge proceeds as follows:

  • If an operator is already present in the current metadata parameter policy, the values of the subordinate operator MUST be merged, as described in Section 6.1.3 and in accordance with the operator specification. If an operator value merge is not allowed or otherwise unsuccessful this MUST result in a policy error.

  • Subordinate operators that are not present in the current metadata parameter policy MUST be copied to it.

If no further Subordinate Statements with a metadata_policy claim are found, the current metadata policy becomes the resolved one for the Trust Chain.

6.1.4.2. Application

If the Subordinate Statement about the Trust Chain subject contains a metadata claim, this MUST first be applied, as described in the claim definition in Section 3, and only then it can be proceeded with applying the resolved metadata policy.

If the process described in Section 6.1.4.1 found no Subordinate Statements in the Trust Chain with a metadata_policy claim, the metadata of the Trust Chain subject resolves simply to the metadata found in its Entity Configuration, with any metadata parameters provided by the Immediate Superior applied to it.

If a metadata policy was resolved for the Trust Chain, for every Entity Type metadata and metadata parameter for which a corresponding metadata parameter policy is present, the included policy operators MUST be applied as described in Section 6.1.3 and in accordance with the specifications of the operators. The operators MUST be applied to the metadata parameter in a sequence that is determined by the absolute or relative order specified for each operator.

If the application of metadata policies results in illegal or otherwise incorrect metadata, then the metadata MUST be regarded as broken and MUST NOT be used.

The Trust Chain subject is responsible to verify that it is able to support and comply with the metadata that results from the application of federation metadata policies. For instance, this may involve a check that cryptographic algorithms required by the resulting metadata are supported. When metadata policies change, Trust Chain subjects may need to reevaluate their support and compliance.

6.1.5. Metadata Policy Example

The following is a non-normative example of resolving and applying Trust Chain metadata policies for an OpenID relying party.

We start with a federation Trust Anchor's metadata_policy for RPs:

"metadata_policy": {
  "openid_relying_party": {
    "grant_types": {
       "default": [
        "authorization_code"
      ],
      "subset_of": [
        "authorization_code",
        "refresh_token"
      ],
      "superset_of": [
        "authorization_code"
      ]
    },
    "token_endpoint_auth_method": {
      "one_of": [
        "private_key_jwt",
        "self_signed_tls_client_auth"
      ],
      "essential": true
    },
    "token_endpoint_auth_signing_alg" : {
      "one_of": [
        "PS256",
        "ES256"
      ]
    },
    "subject_type": {
      "value": "pairwise"
    },
    "contacts": {
      "add": [
        "helpdesk@federation.example.org"
      ]
    }
  }
}
Figure 12: Example Metadata Policy of a Trust Anchor for RPs

Next, we have an Intermediate organization's metadata_policy for Subordinate RPs together with metadata values for its Immediate Subordinate RPs:

{
  "metadata_policy": {
    "openid_relying_party": {
      "grant_types": {
        "subset_of": [
          "authorization_code"
        ]
      },
      "token_endpoint_auth_method": {
        "one_of": [
          "self_signed_tls_client_auth"
        ]
      },
      "contacts": {
        "add": [
          "helpdesk@org.example.org"
        ]
      }
    }
  },
  "metadata": {
    "openid_relying_party": {
      "sector_identifier_uri": "https://org.example.org/sector-ids.json",
      "policy_uri": "https://org.example.org/policy.html"
    }
  }
}
Figure 13: Example Metadata Policy and Metadata Values of an Intermediate Entity for RPs

Merging the example RP metadata policy of the Intermediate Entity into the RP metadata policy of the Trust Anchor produces the following policy for the Trust Chain:

{
  "grant_types": {
    "default": [
      "authorization_code"
    ],
    "superset_of": [
      "authorization_code"
    ],
    "subset_of": [
      "authorization_code"
    ]
  },
  "token_endpoint_auth_method": {
    "one_of": [
      "self_signed_tls_client_auth"
    ],
    "essential": true
  },
  "token_endpoint_auth_signing_alg": {
    "one_of": [
      "PS256",
      "ES256"
    ]
  },
  "subject_type": {
    "value": "pairwise"
  },
  "contacts": {
    "add": [
      "helpdesk@federation.example.org",
      "helpdesk@org.example.org"
    ]
  }
}
Figure 14: Example Merged Metadata Policy for RPs

The Trust Chain subject is a Leaf Entity, which publishes the following RP metadata in its Entity Configuration:

"metadata": {
  "openid_relying_party": {
    "redirect_uris": [
      "https://rp.example.org/callback"
    ],
    "response_types": [
      "code"
    ],
    "token_endpoint_auth_method": "self_signed_tls_client_auth",
    "contacts": [
      "rp_admins@rp.example.org"
    ]
  }
}
Figure 15: Example Entity Configuration RP Metadata

The metadata values specified by the Intermediate Entity for its Immediate Subordinates are applied to the Trust Chain subject metadata. After that, the merged metadata policy is applied, to produce the following resulting RP metadata:

{
  "redirect_uris": [
    "https://rp.example.org/callback"
  ],
  "grant_types": [
    "authorization_code"
  ],
  "response_types": [
    "code"
  ],
  "token_endpoint_auth_method": "self_signed_tls_client_auth",
  "subject_type": "pairwise",
  "sector_identifier_uri": "https://org.example.org/sector-ids.json",
  "policy_uri": "https://org.example.org/policy.html",
  "contacts": [
    "rp_admins@rp.example.org",
    "helpdesk@federation.example.org",
    "helpdesk@org.example.org"
  ]
}
Figure 16: The Resulting RP Metadata for the Trust Chain Subject

6.2. Constraints

Trust Anchors and Intermediate Entities MAY define constraining criteria that apply to their Subordinates. They are expressed in the constraints claim of a Subordinate Statement, as described in Section 3.

The following constraint parameters are defined:

max_path_length
OPTIONAL. Integer specifying the maximum number of Intermediate Entities between the Entity setting the constraint and the Trust Chain subject.
naming_constraints
OPTIONAL. JSON object specifying restrictions on the URIs of the Entity Identifiers of Subordinate Entities. Restrictions are defined in terms of permitted or excluded URI name subtrees.
allowed_entity_types
OPTIONAL. Array of string Entity Type Identifiers. Entity Type Identifiers are defined in Section 5.1. This constraint specifies the Entity Types and hence the metadata that Subordinate Entities are allowed to have.

Additional constraint parameters MAY be defined and used. If they are not understood, they MUST be ignored.

The following is a non-normative example of a set of constraints:

{
  "max_path_length": 2,
  "naming_constraints": {
    "permitted": [
      "https://.example.com"
    ],
    "excluded": [
      "https://east.example.com"
    ]
  },
  "allowed_entity_types": [
    "openid_provider",
    "openid_relying_party"
  ]
}
Figure 17: Example Set of Constraints

When resolving the Trust Chain for an Entity the constraints claim in each Subordinate Statement MUST be independently applied, if present. If any of the constraints checks fails, the Trust Chain MUST be considered invalid.

6.2.1. Max Path Length

The max_path_length constraint specifies the maximum allowed number of Intermediate Entities in a Trust Chain between a Trust Anchor or Intermediate that sets the constraint and the Trust Chain subject.

A max_path_length constraint of zero indicates that no Intermediates MAY appear between this Entity and the Trust Chain subject. The max_path_length constraint MUST have a value greater than or equal to zero.

Omitting the max_path_length constraint means that there are no additional constraints apart from those already in effect.

Assuming that we have a Trust Chain with four Entity Statements:

  1. Entity Configuration of a Leaf Entity (LE)

  2. Subordinate Statement by an Intermediate 1 (I1) about LE

  3. Subordinate Statement by an Intermediate 2 (I2) about I1

  4. Subordinate Statement by a Trust Anchor (TA) about I2

Then the Trust Chain fulfills the constraints if, for instance:

  • The TA specifies a max_path_length that is greater than or equal to 2.

  • TA specifies a max_path_length of 2, I2 specifies a max_path_length of 1, and I1 omits the max_path_length constraint.

  • Neither TA nor I2 specifies any max_path_length constraint while I1 sets max_path_length to 0.

The Trust Chain does not fulfill the constraints if, for instance, the:

  • The TA sets the max_path_length to 1.

6.2.2. Naming Constraints

The naming_constraints member specifies a URI namespace within which the Entity Identifiers of Subordinate Entities in a Trust Chain MUST be located.

Restrictions are defined in terms of URI name subtrees, using permitted and/or excluded members within the naming_constraints member, each of which contains an array of names to be permitted or excluded. Any name matching a restriction in the excluded list is invalid, regardless of the information appearing in the permitted list.

This specification uses the syntax of domain name constraints specified in Section 4.2.1.10 of [RFC5280]. As stated there, a domain name constraint MUST be specified as a fully qualified domain name and MAY specify a host or a domain. Examples are "host.example.com" and ".example.com". When the domain name constraint begins with a period, it MAY be expanded with one or more labels. That is, the domain name constraint ".example.com" is satisfied by both host.example.com and my.host.example.com. However, the domain name constraint ".example.com" is not satisfied by "example.com". When the domain name constraint does not begin with a period, it specifies a host. As in RFC 5280, domain name constraints apply to the host part of the URI.

6.2.3. Entity Type Constraints

The allowed_entity_types constraint specifies the acceptable Entity Types of Subordinate Entities in a Trust Chain. If there is no allowed_entity_types constraint, it means that any Entity Type is allowed. The federation_entity Entity Type Identifier, specified in Section 5.1.1, is always allowed and MUST NOT be included in the constraint. If the constraint is the empty array [], it means that only the federation_entity Entity Type is allowed.

7. Trust Marks

Per the definition in Section 1.2, Trust Marks are statements of conformance to sets of criteria determined by an accreditation authority. Trust Marks used by this specification are signed JWTs. Entity Statements MAY include Trust Marks, as described in the trust_marks claim definition in Section 3.

A Trust Mark issuer is a Federation Entity that issues Trust Marks. A Trust Mark owner is an Entity that owns the right to a Trust Mark identifier.

Trust Marks are signed by a federation-accredited authority called a Trust Mark issuer. All Trust Mark issuers MUST be represented in the federation by an Entity. The fact that a Trust Mark issuer is accepted by the federation is expressed in the trust_mark_issuers claim of the Trust Anchor's Entity Configuration.

The key used by the Trust Mark issuer to sign its Trust Marks MUST be one of the private keys in its set of Federation Entity Keys.

Trust Mark JWTs MUST include the kid (Key ID) header parameter with its value being the Key ID of the signing key used.

Note that a federation MAY allow an Entity to self-sign Trust Marks.

Trust Mark JWTs MUST be explicitly typed by setting the typ header parameter to trust-mark+jwt to prevent cross-JWT confusion, per Section 3.11 of [RFC8725].

7.1. Trust Mark Delegation

There will be cases where the owner of a Trust Mark for some reason may not match the Trust Mark issuer due to administrative or technical requirements. Take as an example vehicle inspection. Vehicle inspection is a procedure mandated by national or subnational governments in many countries, in which a vehicle is inspected to ensure that it conforms to regulations governing safety, emissions, or both. The body that mandates the inspections does not perform them; instead, there may be commercial companies performing the inspections, after which they issue the Trust Mark.

The fact that a Trust Mark is issued by a Trust Mark issuer that is not the owner of the Trust Mark is expressed by including a delegation claim in the Trust Mark, whose value is a signed JWT. The format of the delegation JWT is described below.

If the Federation Operator knows that Trust Marks with a certain Trust Mark identifier may legitimately be issued by Trust Mark issuers that are not the owner of the Trust Mark identifier, then information about the owner and the Trust Mark identifier MUST be included in the trust_mark_owners claim in the Trust Anchor's Entity Configuration.

7.2. Trust Mark Claims

The claims in a Trust Mark are:

iss
REQUIRED. String. Issuer of the Trust Mark.
sub
REQUIRED. String. Entity this Trust Mark applies to.
id
REQUIRED. The id (identifier) claim defined in Section 13.2 is used in Trust Marks to provide the identifier of the Trust Mark. The Trust Mark identifier MUST be collision-resistant across multiple federations. It is RECOMMENDED that the identifier value is built using a URL that uniquely identifies the federation or the trust framework within which it was issued. This is required to prevent Trust Marks issued in different federations from having colliding identifiers.
iat
REQUIRED. Number. Time when this Trust Mark was issued. This is expressed as Seconds Since the Epoch, as defined in [RFC7519].
logo_uri
OPTIONAL. String. URL that references a logo for the Entity. The value of this field MUST point to a valid image file.
exp
OPTIONAL. Number. Time when this Trust Mark is no longer valid. This is expressed as Seconds Since the Epoch, per [RFC7519]. If not present, it means that the Trust Mark does not expire.
ref
OPTIONAL. The ref (reference) claim defined in Section 13.3 is used in Trust Marks to provide a URL referring to human-readable information about the issuance of the Trust Mark.
delegation
OPTIONAL. The delegation claim defined in Section 13.4 is used in Trust Marks to provide a signed JWT containing information about a delegation of the right to issue Trust Marks with a particular identifier created by the owner of the Trust Mark that identifies the delegated issuer of the Trust Mark.

Additional claims MAY be defined and used in conjunction with the claims above.

7.3. Trust Mark Delegation JWT

A Trust Mark delegation JWT MUST be explicitly typed, by setting the typ header parameter to trust-mark-delegation+jwt to prevent cross-JWT confusion, per Section 3.11 of [RFC8725]. It is signed with a Federation Entity Key.

Trust Mark delegation JWTs MUST include the kid (Key ID) header parameter with its value being the Key ID of the signing key used.

The claims in a Trust Mark delegation JWT are:

iss
REQUIRED. String. The owner of the Trust Mark.
sub
REQUIRED. String. The Entity this delegation applies to.
id
REQUIRED. String. The identifier of the Trust Mark.
iat
REQUIRED. Number. Time when this delegation was issued. This is expressed as Seconds Since the Epoch, as defined in [RFC7519].
exp
OPTIONAL. Number. Time when this delegation stops being valid. This is expressed as Seconds Since the Epoch, per [RFC7519]. If not present, it means that the delegation does not expire and is valid until revoked.
ref
OPTIONAL. String. URL that points to human-readable information connected to the Trust Mark.

Additional claims MAY be defined and used in conjunction with the claims above.

7.4. Validating a Trust Mark

An Entity SHOULD NOT try to validate a Trust Mark until it knows which Trust Anchor it is using. To validate a Trust Mark issuer, follow the procedure defined in Section 10. To validate a Trust Mark:

  1. Check the signature of the signed JWT and verify that it has not expired.

  2. If the Trust Mark identifier appears in the trust_mark_owners claim, verify that the Trust Mark contains a delegation claim. The claims for the Trust Mark identifier in the trust_mark_owners value are used in the following way:

    • The signature of the delegation JWT MUST verify with a key from jwks claim.

    • The issuer of the delegation JWT MUST match the sub value in this set of claims.

  3. Using the Trust Mark issuer status endpoint to verify that the Trust Mark is still active is described in Section 8.4.

Note that the Entity representing the accreditation authority SHOULD be well known and trusted for a given Trust Mark identifier. A Trust Anchor MAY publish a list of accreditation authorities of Trust Marks that SHOULD be trusted by other Entities. A Trust Anchor uses the trust_mark_issuers claim in its Entity Configuration to publish this information.

If a Trust Mark issuer is issuing Trust Marks on behalf of a Trust Mark owner, then the Trust Anchor MUST publish the connection between the Trust Mark identifier and the corresponding Trust Mark issuer in the trust_mark_issuers claim. This signifies that the Trust Anchor has validated the Trust Mark owner and that the Trust Mark owner has delegated the right to issue Trust Marks with a designated Trust Mark identifier to a specified Trust Mark issuer.

Trust Marks that are not recognized within a federation SHOULD be ignored when evaluating trust in the Entity that presented them. Such Trust Marks can appear for various reasons, such as the Entity Configuration including Trust Marks associated with another federation, or Trust Marks intended for specific purposes or Entity audiences.

An Entity MAY choose, at its own discretion, to utilize Trust Marks presented to it that are not recognized within the federation, and where the accreditation authority is established by some out-of-band mechanism.

7.5. Trust Mark Examples

A non-normative example of a trust_marks claim in the JWT Claims Set for an Entity Configuration is:

{
  "iss": "https://rp.example.it/spid/",
  "sub": "https://rp.example.it/spid/",
  "iat": 1516239022,
  "exp": 1516298022,
  "trust_marks": [
    {
     "id": "https://www.spid.gov.it/certification/rp",
     "trust_mark":
       "eyJraWQiOiJmdWtDdUtTS3hwWWJjN09lZUk3Ynlya3N5a0E1bDhPb2RFSXVyOH
        JoNFlBIiwidHlwIjoidHJ1c3QtbWFyaytqd3QiLCJhbGciOiJSUzI1NiJ9.eyJ
        pc3MiOiJodHRwczovL3d3dy5hZ2lkLmdvdi5pdCIsInN1YiI6Imh0dHBzOi8vc
        nAuZXhhbXBsZS5pdC9zcGlkIiwiaWF0IjoxNTc5NjIxMTYwLCJpZCI6Imh0dHB
        zOi8vd3d3LnNwaWQuZ292Lml0L2NlcnRpZmljYXRpb24vcnAiLCJsb2dvX3Vya
        SI6Imh0dHBzOi8vd3d3LmFnaWQuZ292Lml0L3RoZW1lcy9jdXN0b20vYWdpZC9
        sb2dvLnN2ZyIsInJlZiI6Imh0dHBzOi8vZG9jcy5pdGFsaWEuaXQvZG9jcy9zc
        GlkLWNpZS1vaWRjLWRvY3MvaXQvdmVyc2lvbmUtY29ycmVudGUvIn0.AGf5Y4M
        oJt22rznH4i7Wqpb2EF2LzE6BFEkTzY1dCBMCK-8P_vj4Boz7335pUF45XXr2j
        x5_waDRgDoS5vOO-wfc0NWb4Zb_T1RCwcryrzV0z3jJICePMPM_1hZnBZjTNQd
        4EsFNvKmUo_teR2yzAZjguR2Rid30O5PO8kJtGaXDmz-rWaHbmfLhlNGJnqcp9
        Lo1bhkU_4Cjpn2bdX7RN0JyfHVY5IJXwdxUMENxZd-VtA5QYiw7kPExT53XcJO
        89ebe_ik4D0dl-vINwYhrIz2RPnqgA1OdbK7jg0vm8Tb3aemRLG7oLntHwqLO-
        gGYr6evM2_SgqwA0lQ9mB9yhw"
    }
  ],
  "metadata": {
    "openid_relying_party": {
      "application_type": "web",
      "client_registration_types": ["automatic"],
      "client_name": "https://rp.example.it/spid/",
      "contacts": [
        "ops@rp.example.it"
      ]
    }
  }
}
Figure 18: Trust Mark in an Entity Configuration JWT Claims Set

An example of a decoded Trust Mark payload issued to an RP, attesting to conformance to a national public service profile:

{
  "id":"https://mushrooms.federation.example.com/openid_relying_party/public/",
  "iss": "https://epigeo.tm-issuer.example.it",
  "sub": "https://porcino.example.com/rp",
  "iat": 1579621160,
  "organization_name": "Porcino Mushrooms & Co.",
  "policy_uri": "https://porcino.example.com/privacy_policy",
  "tos_uri": "https://porcino.example.com/info_policy",
  "service_documentation": "https://porcino.example.com/api/v1/get/services",
  "ref": "https://porcino.example.com/documentation/manuale_operativo.pdf"
}

Figure 19: Trust Mark for a National Profile

An example of a decoded Trust Mark payload issued to an RP, attesting to its conformance to the rules for data management of underage users:

{
  "id":"https://mushrooms.federation.example.com/openid_relying_party/private/under-age",
  "iss": "https://trustissuer.pinarolo.example.it",
  "sub": "https://vavuso.example.com/rp",
  "iat": 1579621160,
  "organization_name": "Pinarolo Suillus luteus",
  "policy_uri": "https://vavuso.example.com/policy",
  "tos_uri": "https://vavuso.example.com/tos"
}

Figure 20: Trust Mark Issued to an RP

An example of a decoded Trust Mark payload attesting a stipulation of an agreement between two organization's Entities:

{
  "id": "https://mushrooms.federation.example.com/arrosto/agreements",
  "iss": "https://agaricaceae.example.it",
  "sub": "https://coppolino.example.com",
  "iat": 1579621160,
  "logo_uri": "https://coppolino.example.com/sgd-cmyk-150dpi-90mm.svg",
  "organization_type": "public",
  "id_code": "123456",
  "email": "info@coppolino.example.com",
  "organization_name#it": "Mazza di Tamburo",
  "policy_uri#it": "https://coppolino.example.com/privacy_policy",
  "tos_uri#it": "https://coppolino.example.com/info_policy",
  "service_documentation": "https://coppolino.example.com/api/v1/get/services",
  "ref": "https://agaricaceae.example.it/documentation/agaricaceae.pdf"
}
Figure 21: Trust Mark Attesting to an Agreement Between Entities

An example of a decoded Trust Mark payload asserting conformance to a security profile:

{
  "id": "https://mushrooms.federation.example.com/ottimo/commestibile",
  "iss": "https://cantharellus.cibarius.example.org",
  "sub": "https://gallinaccio.example.com/op",
  "iat": 1579621160,
  "logo_uri": "https://cantharellus.cibarius/static/images/cantharellus-cibarius.svg",
  "ref": "https://cantharellus.cibarius/cantharellus/cibarius"
}
Figure 22: Trust Mark Asserting Conformance to a Security Profile

An example of a decoded self-signed Trust Mark:

{
  "id": "https://mushrooms.federation.example.com/trust-marks/self-signed",
  "iss": "https://amanita.muscaria.example.com",
  "sub": "https://amanita.muscaria.example.com",
  "iat": 1579621160,
  "logo_uri": "https://amanita.muscaria.example.com/img/amanita-mus.svg",
  "ref": "https://amanita.muscaria.example.com/uploads/cookbook.zip"
}
Figure 23: Self-Signed Trust Mark

An example of a third-party accreditation authority for Trust Marks:

{
  "iss": "https://swamid.se",
  "sub": "https://umu.se/op",
  "iat": 1577833200,
  "exp": 1609369200,
  "id": "https://refeds.org/wp-content/uploads/2016/01/Sirtfi-1.0.pdf"
}
Figure 24: Third-Party Accreditation Authority for Trust Marks

8. Federation Endpoints

The federation endpoints of an Entity can be found in the configuration response as described in Section 9 or by other means.

For all federation endpoints, additional request parameters beyond those initially specified MAY be defined and used. If they are not understood, they MUST be ignored.

8.1. Fetching an Entity Statement

Fetching Entity Statements is performed to collect Entity Statements one by one to assemble Trust Chains. An Entity with Subordinates MUST expose a fetch endpoint. An Entity MUST publish Subordinate Statements about its Immediate Subordinates via its fetch endpoint.

The fetch endpoint location is published in the Entity's federation_entity metadata in the federation_fetch_endpoint parameter defined in Section 5.1.1. Since this endpoint is used when building and validating Trust Chains, its location MUST be available before metadata and metadata policies from Superiors can be applied. Therefore, this endpoint MUST be published directly in Entity Configuration metadata and not in Subordinate Statements.

To fetch an Entity Statement, an Entity needs to know the identifier of the Entity to ask (the issuer), the fetch endpoint of that Entity, and the identifier of the Entity, that is, the subject of the Entity Statement.

8.1.1. Fetch Entity Statement Request

When client authentication is not used, the request MUST be an HTTP request using the GET method to a fetch endpoint with the following query parameters, encoded in application/x-www-form-urlencoded format. The request is made to the fetch endpoint of the specified issuer.

iss
REQUIRED. The Entity Identifier of the issuer from which the Entity Statement is issued. Because of the normalization of the URL, multiple issuers MAY resolve to a shared fetch endpoint. This parameter makes it explicit exactly which issuer the Entity Statement must come from.
sub
OPTIONAL. The Entity Identifier of the subject for which the Entity Statement is being requested. If this parameter is omitted, it is considered to be the same as the issuer and indicates a request for a self-signed Entity Configuration.

When client authentication is used, the request MUST be an HTTP request using the POST method, with the parameters passed in the POST body.

The following is a non-normative example of an HTTP GET request for a Subordinate Statement from edugain.org about https://openid.sunet.se:

GET /federation_fetch_endpoint?
iss=https%3A%2F%2Fedugain%2Eorg&
sub=https%3A%2F%2Fopenid%2Esunet%2Ese HTTP/1.1
Host: edugain.org
Figure 25: API Request for a Subordinate Statement

8.1.2. Fetch Entity Statement Response

A successful response MUST use the HTTP status code 200 with the content type application/entity-statement+jwt, to make it clear that the response contains an Entity Statement. If it is a negative response, it will be a JSON object and the content type MUST be application/json. If the fetch endpoint cannot provide data for the requested iss parameter, returning the invalid_issuer error code is RECOMMENDED. If the fetch endpoint cannot provide data for the requested sub parameter, returning the not_found error code is RECOMMENDED. See more about error responses in Section 8.9.

The following is a non-normative example of the JWT Claims Set for a fetch response:

{
  "iss": "https://edugain.org/federation",
  "sub": "https://openid.sunet.se",
  "exp": 1568397247,
  "iat": 1568310847,
  "source_endpoint": "https://edugain.org/federation/federation_fetch_endpoint",
  "jwks": {
    "keys": [
      {
        "e": "AQAB",
        "kid": "dEEtRjlzY3djcENuT01wOGxrZlkxb3RIQVJlMTY0...",
        "kty": "RSA",
        "n": "x97YKqc9Cs-DNtFrQ7_vhXoH9bwkDWW6En2jJ044yH..."
      }
    ]
  },
  "metadata":{
    "federation_entity": {
        "organization_name":"SUNET"
    }
  }
  "metadata_policy": {
    "openid_provider": {
      "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 26: Fetch Response JWT Claims Set

8.2. Subordinate Listings

The listing endpoint is exposed by Federation Entities acting as a Trust Anchor, Intermediate, or Trust Mark issuer. The endpoint lists the Immediate Subordinates about which the Trust Anchor, Intermediate, or Trust Mark Issuer issues Entity Statements.

As a Trust Mark issuer, the endpoint MAY list the Immediate Subordinates for which Trust Marks have been issued and are still valid, if the issuer exposing this endpoint supports Trust Mark filtering, as defined below.

In both cases, the list contained in the result MAY be a very large list.

The list endpoint location is published in the Entity's federation_entity metadata in the federation_list_endpoint parameter defined in Section 5.1.1. This endpoint MUST be published directly in Entity Configuration metadata and not in Subordinate Statements.

The following example shows a tree of Entities belonging to the same federation including the Trust Anchor, Intermediate Entities, and Leaf Entities, discovered and collected through the Subordinate listing endpoints:

                       +----------------------+
                       |    Trust Anchor      |
                       +----------------------+
       +---------------+ Subordinate Listing  +--------------+
       |               +----------+-----------+              |
       |                          |                          |
       |                          |                          |
       |                          |                          |
       |                          |                          |
       |                          |                          |
+------v-------+       +----------v-----------+       +------v-------+
|     Leaf     |       |     Intermediate     |       |     Leaf     |
+--------------+       +----------------------+       +--------------+
                  +----+ Subordinate Listing  |
                  |    +------------+---------+
                  |                 |
                  |                 |
                  |                 |
       +----------v-----------+     |
       |     Intermediate     |     |
       +----------------------+     |
       | Subordinate Listing  |     |
       +-+---------+----------+     |
         |         |                |
         |         |                |
 +-------v--+     +v--------+    +--v------+
 |  Leaf    |     |  Leaf   |    |  Leaf   |
 +----------+     +---------+    +---------+
Figure 27: Tree of Entities in a Federation Collected through Subordinate Listing Endpoints

8.2.1. Subordinate Listing Request

When client authentication is not used, the request MUST be an HTTP request using the GET method to a list endpoint with the following query parameters, encoded in application/x-www-form-urlencoded format.

entity_type
OPTIONAL. The value of this parameter is an Entity Type Identifier. If the responder knows the Entity Types of its Immediate Subordinates, the result MUST be filtered to include only those that include the specified Entity Type. When multiple entity_type parameters are present, for example entity_type=openid_provider&entity_type=openid_relying_party , the result MUST be filtered to include all specified Entity Types. If the responder does not support this feature, it MUST use the HTTP status code 400 and the content type application/json, with the error code unsupported_parameter.
trust_marked
OPTIONAL. Boolean. If the parameter trust_marked is present and set to true, the result contains only the Immediate Subordinates for which at least one Trust Mark have been issued and is still valid. If the responder does not support this feature, it MUST use the HTTP status code 400 and set the content type to application/json, with the error code unsupported_parameter.
trust_mark_id
OPTIONAL. The value of this parameter is a Trust Mark identifier. If the responder has issued Trust Marks with the specified Trust Mark identifier, the list in the response is filtered to include only the Immediate Subordinates for which that Trust Mark identifier has been issued and is still valid. If the responder does not support this feature, it MUST use the HTTP status code 400 and set the content type to application/json, with the error code unsupported_parameter.
intermediate
OPTIONAL. Boolean. If the parameter intermediate is present and set to true, then if the responder knows whether its Immediate Subordinates are Intermediates or not, the result MUST be filtered accordingly. If the responder does not support this feature, it MUST use the HTTP status code 400 and the content type application/json, with the error code unsupported_parameter.

When client authentication is used, the request MUST be an HTTP request using the POST method, with the parameters passed in the POST body.

The following is a non-normative example of an HTTP GET request for a list of Immediate Subordinates:

GET /list HTTP/1.1
Host: openid.sunet.se
Figure 28: Subordinate Listing Request

8.2.2. Subordinate Listing Response

A successful response MUST use the HTTP status code 200 with the content type application/json, containing a JSON array with the known Entity Identifiers.

If the response is negative, the response is as defined in Section 8.9.

The following is a non-normative example of a response containing the Immediate Subordinate Entities:

200 OK
Content-Type: application/json

[
  "https://ntnu.andreas.labs.uninett.no/",
  "https://blackboard.ntnu.no/openid/callback",
  "https://serviceprovider.andreas.labs.uninett.no/application17"
]
Figure 29: Subordinate Listing Response

8.3. Resolve Entity Statement

An Entity MAY use a resolve endpoint to fetch resolved metadata and Trust Marks for an Entity. The resolver fetches the subject's Entity Configuration, assembles a Trust Chain that starts with the subject's Entity Configuration and ends with the specified Trust Anchor's Entity Configuration, verifies the Trust Chain, and then applies all the policies present in the Trust Chain to the subject's metadata.

The resolver MUST verify that all present Trust Marks with identifiers recognized within the Federation are active. The response set MUST include only verified Trust Marks.

The resolve endpoint location is published in the Entity's federation_entity metadata in the federation_resolve_endpoint parameter defined in Section 5.1.1.

8.3.1. Resolve Request

When client authentication is not used, the request MUST be an HTTP request using the GET method to a resolve endpoint with the following query parameters, encoded in application/x-www-form-urlencoded format.

sub
REQUIRED. The Entity Identifier of the Entity whose resolved data is requested.
anchor
REQUIRED. The Trust Anchor that the resolve endpoint MUST use when resolving the metadata. The value is an Entity identifier.
type
OPTIONAL. A specific Entity Type to resolve. Its value is an Entity Type Identifier, as specified in Section 5.1. If this parameter is not present, then all Entity Types are returned.

When client authentication is used, the request MUST be an HTTP request using the POST method, with the parameters passed in the POST body.

The following is a non-normative example of a resolve request:

GET /resolve?
sub=https%3A%2F%2Fop.example.it%2Fspid&
type=openid_provider&
anchor=https%3A%2F%2Fswamid.se HTTP/1.1
Host: openid.sunet.se
Figure 30: Example Resolve Request

8.3.2. Resolve Response

A successful response MUST use the HTTP status code 200 with the content type application/resolve-response+jwt, containing resolved metadata and verified Trust Marks.

The response is a signed JWT that is explicitly typed by setting the typ header parameter to resolve-response+jwt to prevent cross-JWT confusion, per Section 3.11 of [RFC8725]. It is signed with a Federation Entity Key.

The resolve response JWT MUST include the kid (Key ID) header parameter with its value being the Key ID of the signing key used.

The resolve response JWT MAY return the Trust Chain from the subject to the Trust Anchor in its trust_chain parameter, sorted as shown in Section 4.

The resolve response MAY also return the Trust Chain from its issuer to the Trust Anchor in the trust_chain JWS header parameter, as specified in Section 4.3. When this is present, the Trust Anchor in the Trust Chain MUST match the Trust Anchor requested in the related request in the anchor parameter.

An issuer that provides its Trust Chain within the resolve response makes it evident that it is part of the same federation as the subject of the response. Thus, when the Trust Chains of both the issuer and the subject are available and the Federation Historical Keys endpoint is provided by the Trust Anchor, the resolve response becomes a long-lived attestation; it can be always verified, even when the Federation Keys change in the future.

The response SHOULD contain the aud claim only if the requesting client is authenticated.

The claims in a resolve response are:

iss
REQUIRED. String. Entity Identifier of the issuer of the resolve response.
sub
REQUIRED. String. Entity Identifier of the subject of the resolve response.
iat
REQUIRED. Number. Time when this resolution was issued. This is expressed as Seconds Since the Epoch, as defined in [RFC7519].
exp
REQUIRED. Number. Time when this resolution is no longer valid. This is expressed as Seconds Since the Epoch, as defined in [RFC7519]. It MUST correspond to the exp value of the Trust Chain from which the resolve response was derived.
metadata
REQUIRED. JSON object containing the resolved subject metadata, according to the requested type and expressed in the metadata format defined in Section 3.
trust_marks
OPTIONAL. Array of objects, each representing a Trust Mark, as defined in Section 3.
trust_chain
OPTIONAL. Array containing the sequence of Entity Statements that compose the Trust Chain, starting with the subject and ending with the selected Trust Anchor, sorted as shown in Section 4.

Additional claims MAY be defined and used in conjunction with the claims above.

If the response is negative, the response is as defined in Section 8.9.

The following is a non-normative example of the JWT Claims Set for a resolve response:

{
  "iss": "https://resolver.spid.gov.it/",
  "sub": "https://op.example.it/spid/",
  "iat": 1516239022,
  "exp": 1516298022,
  "metadata": {
    "openid_provider": {
      "contacts": ["legal@example.it", "technical@example.it"],
      "logo_uri":
        "https://op.example.it/static/img/op-logo.svg",
      "op_policy_uri":
        "https://op.example.it/en/about-the-website/legal-information",
      "federation_registration_endpoint":"https://op.example.it/spid/fedreg",
      "authorization_endpoint":
        "https://op.example.it/spid/authorization",
      "token_endpoint": "https://op.example.it/spid/token",
      "response_types_supported": [
        "code",
        "code id_token",
        "token"
      ],
      "grant_types_supported": [
        "authorization_code",
        "urn:ietf:params:oauth:grant-type:jwt-bearer"
      ],
      "subject_types_supported": ["pairwise"],
      "id_token_signing_alg_values_supported": ["RS256"],
      "issuer": "https://op.example.it/spid",
      "jwks": {
        "keys": [
          {
            "kty": "RSA",
            "use": "sig",
            "n": "1Ta-sE ...",
            "e": "AQAB",
            "kid": "FANFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs"
          }
        ]
      }
    }
  },
  "trust_marks": [
    {"id": "https://www.spid.gov.it/certification/op/",
     "trust_mark":
       "eyJhbGciOiJSUzI1NiIsImtpZCI6ImRGRTFjMFF4UzBFdFFrWmxNRXR3ZWxOQl"
       "eyJhbGciOiJSUzI1NiIsImtpZCI6Ijh4c3VLV2lWZndTZ0hvZjFUZTRPVWRjeT"
       "RxN2RKcktmRlJsTzV4aEhJYTAifQ.eyJpc3MiOiJodHRwczovL3d3dy5hZ2lkL"
       "mdvdi5pdCIsInN1YiI6Imh0dHBzOi8vb3AuZXhhbXBsZS5pdC9zcGlkLyIsIml"
       "hdCI6MTU3OTYyMTE2MCwiaWQiOiJodHRwczovL3d3dy5zcGlkLmdvdi5pdC9jZ"
       "XJ0aWZpY2F0aW9uL29wLyIsImxvZ29fdXJpIjoiaHR0cHM6Ly93d3cuYWdpZC5"
       "nb3YuaXQvdGhlbWVzL2N1c3RvbS9hZ2lkL2xvZ28uc3ZnIiwicmVmIjoiaHR0c"
       "HM6Ly9kb2NzLml0YWxpYS5pdC9pdGFsaWEvc3BpZC9zcGlkLXJlZ29sZS10ZWN"
       "uaWNoZS1vaWRjL2l0L3N0YWJpbGUvaW5kZXguaHRtbCJ9"
    }
  ],
  "trust_chain" : [
    "eyJhbGciOiJSUzI1NiIsImtpZCI6Ims1NEhRdERpYnlHY3M5WldWTWZ2aUhm ...",
    "eyJhbGciOiJSUzI1NiIsImtpZCI6IkJYdmZybG5oQU11SFIwN2FqVW1BY0JS ...",
    "eyJhbGciOiJSUzI1NiIsImtpZCI6IkJYdmZybG5oQU11SFIwN2FqVW1BY0JS ..."
  ]
}
Figure 31: Resolve Response JWT Claims Set

8.3.3. Trust Considerations

The basic assumption of this specification is that an Entity should have direct trust in no one except the Trust Anchor and its own capabilities. However, Entities may establish a kind of transitive trust in other Entities. For example, the Trust Anchor states who its Immediate Subordinates are and Entities may choose to trust them. If a party uses the resolve service of another Entity to obtain federation data, it is trusting the resolver to perform validation of the cryptographically protected metadata correctly and to provide it with authentic results.

8.4. Trust Mark Status

This enables an Entity to check whether a Trust Mark is still active or not. The query MUST be sent to the Trust Mark issuer.

The Trust Mark status endpoint location is published in the Entity's federation_entity metadata in the federation_trust_mark_status_endpoint parameter defined in Section 5.1.1. This endpoint MUST be published directly in Entity Configuration metadata and not in Subordinate Statements.

8.4.1. Trust Mark Status Request

The request MUST be an HTTP request using the POST method to a Trust Mark status endpoint with the following parameters, encoded in application/x-www-form-urlencoded format.

sub
OPTIONAL. The Entity Identifier of the Entity to which the Trust Mark was issued.
trust_mark_id
OPTIONAL. Identifier of the Trust Mark.
iat
OPTIONAL. Number. Time when this Trust Mark was issued. This is expressed as Seconds Since the Epoch, as defined in [RFC7519]. If iat is not specified and the Trust Mark issuer has issued several Trust Marks with the identifier specified in the request to the Entity identified by sub, the most recent one is assumed.
trust_mark
OPTIONAL. The whole Trust Mark.

If trust_mark is used, then sub and trust_mark_id are not needed. If trust_mark is not used, then sub and trust_mark_id are REQUIRED.

When client authentication is used, the request MUST be an HTTP request using the POST method, with the parameters passed in the POST body.

The following is a non-normative example of a Trust Mark status request using sub and trust_mark_id:

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

sub=https%3A%2F%2Fopenid.sunet.se%2FRP
&trust_mark_id=https%3A%2F%2Frefeds.org%2Fsirtfi
Figure 32: Trust Mark Status Request

8.4.2. Trust Mark Status Response

A successful response MUST use the HTTP status code 200 with the content type application/json. The response body is a JSON object containing the data below:

active
REQUIRED. Boolean. Whether the Trust Mark is active or not.

If the response is negative, the response is as defined in Section 8.9.

The following is a non-normative example of a Trust Mark status response:

200 OK
Content-Type: application/json

{
  "active": true
}
Figure 33: Trust Mark Status Response

8.5. Trust Marked Entities Listing

The Trust Marked Entities listing endpoint is exposed by Trust Mark issuers and lists all the Entities for which Trust Marks have been issued and are still valid.

The Trust Marked Entities listing endpoint location is published in the Entity's federation_entity metadata in the federation_trust_mark_list_endpoint parameter defined in Section 5.1.1.

8.5.1. Trust Marked Entities Listing Request

When client authentication is not used, the request MUST be an HTTP request using the GET method to a list endpoint with the following query parameters, encoded in application/x-www-form-urlencoded format.

trust_mark_id
REQUIRED. The value of this parameter is a Trust Mark identifier. If the responder has issued Trust Marks with the specified Trust Mark identifier, the list in the response is filtered to include only the Entities for which that Trust Mark identifier has been issued and is still valid.
sub
OPTIONAL. The Entity Identifier of the Entity to which the Trust Mark was issued. The list obtained in the response MUST be filtered to only the Entity matching this value.

When client authentication is used, the request MUST be an HTTP request using the POST method, with the parameters passed in the POST body.

The following is a non-normative example of an HTTP GET request for a list of Trust Marked Entities:

GET /trust_marked_list?trust_mark_id=https%3A%2F%2Ffederation.example.org%2Fopenid_relying_party%2Fprivate%2Funder-age HTTP/1.1
Host: trust-mark-issuer.example.org
Figure 34: Trust Marked Entities Listing Request

8.5.2. Trust Marked Entities Listing Response

A successful response MUST use the HTTP status code 200 with the content type application/json, containing a JSON array with Entity Identifiers.

If the response is negative, the response is as defined in Section 8.9.

The following is a non-normative example of a response, containing the Trust Marked Entities:

200 OK
Content-Type: application/json

[
  "https://blackboard.ntnu.no/openid/rp",
  "https://that-rp.example.org"
]
Figure 35: Trust Marked Entities Listing Response

8.6. Trust Mark Endpoint

The Trust Mark endpoint is exposed by a Trust Mark issuer to provide Trust Marks to subjects.

The Trust Mark endpoint location is published in the Entity's federation_entity metadata in the federation_trust_mark_endpoint parameter defined in Section 5.1.1.

8.6.1. Trust Mark Request

When client authentication is not used, the request MUST be an HTTP request using the GET method with the following query parameter, encoded in application/x-www-form-urlencoded format.

trust_mark_id
REQUIRED. Trust Mark identifier.
sub
REQUIRED. The Entity Identifier of the Entity to which the Trust Mark is issued.

When client authentication is used, the request MUST be an HTTP request using the POST method, with the parameters passed in the POST body. The Trust Mark endpoint MAY choose to allow authenticated requests from clients that are not the Trust Mark subject, as indicated by the sub parameter. An example use case is to let a Federation Entity retrieve the Trust Mark for another Entity.

The following is a non-normative example of an HTTP request for a Trust Mark with a specific Trust Mark ID and subject:

GET /trust_mark?trust_mark_id=https%3A%2F%2Ftuber.cert.example.org%2Fnero%2Fpregiato%2Fnorcia&sub=https%3A%2F%2Ftartufo.example.it HTTP/1.1
Host: tuber.cert.example.org
Figure 36: Trust Mark Request

8.6.2. Trust Mark Response

A successful response MUST use the HTTP status code 200 with the content type application/trust-mark+jwt, containing the Trust Mark.

If the specified Entity doesn't have the specified Trust Mark, the response is negative and MUST use the HTTP status code 404.

The following is a non-normative example of a response, containing the Trust Mark for the specified Entity (with line wraps within values for display purposes only):

200 OK

eyJhbGciOiJSUzI1NiIsImtpZCI6Im1VRXR0aW5SNTNpLW9Bc1JoN2l6blY1R1hlaFh3QzZ1
aTRScG1QeUt5ZDgifQ.eyJpc3MiOiJodHRwczovL3R1YmVyLmNlcnQuZXhhbXBsZS5vcmciL
CJzdWIiOiJodHRwczovL3RhcnR1Zm8uZXhhbXBsZS5pdCIsImlhdCI6MTU3OTYyMTE2MCwiZ
XhwIjoxNTc5NzIxMTYwLCJpZCI6Imh0dHBzOi8vdHViZXIuY2VydC5leGFtcGxlLm9yZy9uZ
XJvL3ByZWdpYXRvL25vcmNpYSJ9.HwzNAJVPDYC9AM-ILWfgmT5YDz-pjtklQhtEQbqhC7P0
nv88W8Wx74oE5IR5WgJP9Q3xPD-UO7o6O_Z0PMR186TzcBnaXtogn6-QxHRomCPwytviVGyk
XE1MkOnf9wTYWb5q13A53w8y0vUTlwZhBHt9qYNp3t4XwjR8eEZTptHeI_NHkaOsknT3cI16
FbxqXVdTudQCfPJEYKGGL1QDg2EdVGFgjq4V-2UTKlBQvnorNUmfNOxgRT0DR37ZezluvGJ5
NjK15h2rrJRN4e_8favIJNTNO8fhK7bjyUFJlVGYmLUpfCuJmxBv-EMhiAkeoDtk71Tc6ou6
2rxqFCU3LQ
Figure 37: Trust Mark Response

8.7. Federation Historical Keys Endpoint

Each Federation Entity MAY publish its previously used Federation Entity Keys at the historical keys endpoint defined in Section 5.1.1. The purpose of this endpoint is to provide the list of keys previously used by the Federation Entity to provide non-repudiation of statements signed by it after key rotation. This endpoint also discloses the reason for the retraction of the keys and whether they were expired or revoked, including the reason for the revocation.

Note that an expired key can be later additionally marked as revoked, to indicate a key compromise event discovered after the expiration of the key.

The publishing of the historical keys guarantees that Trust Chains will remain verifiable and usable as inputs to trust decisions after the key expiration, unless the key becomes revoked for a security reason.

8.7.1. Federation Historical Keys Request

When client authentication is not used, the request MUST be an HTTP request using the GET method to the federation historical keys endpoint.

When client authentication is used, the request MUST be an HTTP request using the POST method, with the client authentication parameters passed in the POST body.

The following is a non-normative example of a historical keys request:

GET /federation_historical_keys HTTP/1.1
Host: trust-anchor.example.com
Figure 38: Federation Historical Keys Request

8.7.2. Federation Historical Keys Response

A successful response MUST use the HTTP status code 200 with the content type application/jwk-set+jwt. The response is a signed JWT with the JWK Set [RFC7517] as its payload. It is signed with a Federation Entity Key.

Historical keys JWTs are explicitly typed by setting the typ header parameter to jwk-set+jwt to prevent cross-JWT confusion, per Section 3.11 of [RFC8725].

Historical keys JWTs MUST include the kid (Key ID) header parameter with its value being the Key ID of the signing key used.

The claims in a historical keys JWT are:

iss
REQUIRED. String. The Entity's Entity Identifier.
iat
REQUIRED. Number. Time when this historical keys JWT was issued. This is expressed as Seconds Since the Epoch, as defined in [RFC7519].
keys

REQUIRED. Array of JSON objects containing the signing keys for the Entity in JWK format.

JWKs in the keys claim use the following parameters:

kid
REQUIRED. Parameter used to match a specific key. It is RECOMMENDED that the Key ID be the JWK Thumbprint [RFC7638] of the key using the SHA-256 hash function.
iat
OPTIONAL. Number. Time when this key was issued. This is expressed as Seconds Since the Epoch, as defined in [RFC7519].
exp
REQUIRED. Number. Expiration time for the key. This is expressed as Seconds Since the Epoch, as defined in [RFC7519], After this time the key MUST NOT be considered valid.
revoked

OPTIONAL. JSON object that contains the properties of the revocation, as defined below:

revoked_at
REQUIRED. Time when the key was revoked or must be considered revoked, using the time format defined for the iat claim in [RFC7519].
reason
OPTIONAL. String that identifies the reason for the key revocation, as defined in Section 8.7.3.

Additional members of the revoked object MAY be defined and used.

Additional claims MAY be defined and used in conjunction with the claims above.

JWKs in the keys claim MAY also contain the nbf parameter. For use in Historical Keys, iat and exp are sufficient to establish the key lifetime, making nbf typically superfluous; however, it is registered for use by profiles that may choose to issue keys that do not immediately become valid at the time of issuance. Its definition is:

nbf
OPTIONAL. Time before which the key is not valid, using the time format defined for the nbf claim in [RFC7519].

The following is a non-normative example of the JWT Claims Set for a historical keys response:

{
    "iss": "https://trust-anchor.federation.example.com",
    "iat": 123972394272,
    "keys":
        [
            {
                "kty":"RSA",
                "n":"5s4qi …",
                "e":"AQAB",
                "kid":"2HnoFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs",
                "iat": 123972394872,
                "exp": 123974395972
            },
            {
                "kty":"RSA",
                "n":"ng5jr …",
                "e":"AQAB",
                "kid":"8KnoFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMJJr",
                "iat": 123972394872,
                "exp": 123974394972,
                "revoked": {
                  "revoked_at": 123972495172,
                  "reason": "compromised",
                }
            }
        ]
}
Figure 39: Federation Historical Keys Response JWT Claims Set

8.7.3. Federation Historical Keys Revocation Reasons

Federation Entities are strongly encouraged to use a meaningful reason value when indicating the revocation reason for a Federation Entity Key. The reason MAY be omitted instead of using the unspecified value.

Below is the definition of the reason values.

The following table defines Federation Entity Keys revocation reasons. These reasons are inspired by Section 5.3.1 of [RFC5280].

Table 2: Federation Entity Keys Revocation Reasons.
Reason Description
unspecified General or unspecified reason for the JWK status change.
compromised The private key is believed to have been compromised.
superseded The JWK is no longer active.

A federation MAY specify and utilize additional reasons depending on the trust or security framework in use.

8.7.4. Rationale for the Federation Historical Keys Endpoint

The Federation Historical Keys endpoint solves the problem of verifying historical Trust Chains when the Federation Entity Keys have changed, either due to expiration or revocation.

The Federation Historical Keys endpoint publishes the list of public keys used in the past by the Entity. These keys are needed to verify Trust Chains created in the past with Entity keys no longer published in the Entity's Entity Configuration.

The Federation Historical Keys endpoint response contains a signed JWT that attests to all the expired and revoked Entity keys.

Based on the attributes contained in the Entity Statements that form a Trust Chain, it MAY be also possible to verify the non-federation public keys used in the past by Leaf Entities for signature operations for OpenID Connect requests and responses. For example, an Entity Statement issued for a Leaf MAY also include the jwks claim for the Leaf's Entity Types, in its metadata or metadata_policy claims.

A simple example: In the following Trust Chain, the Federation Intermediate attests to the Leaf's OpenID Connect RP jwks in the Subordinate Statement issued about the Leaf. The result is a Trust Chain that contains the Leaf's OpenID Connect RP JWK Set, needed to verify historical signature on Request Objects and any other signed JWT issued by the Leaf as an RP. This example Trust Chain contains:

  1. an Entity Configuration about the RP published by the RP,

  2. a Subordinate Statement about the RP published by Organization A, with the claim jwks contained in metadata or metadata_policy attesting the Leaf's OpenID Connect RP jwks, and

  3. a Subordinate Statement about Organization A published by Federation F.

8.8. Client Authentication at Federation Endpoints

Client authentication is not used at any of the federation endpoints, by default. Federations can choose to make client authentication OPTIONAL, REQUIRED, and/or not allowed at particular federation endpoints.

Client authentication with private_key_jwt is the default client authentication method to federation endpoints when client authentication is supported. This client authentication method is described in Section 9 of OpenID Connect Core 1.0 [OpenID.Core]. The client authentication JWT MUST be signed with a Federation Entity Key. The audience of the JWT MUST be the URL of the federation endpoint. When client authentication is used, the request MUST be an HTTP request using the POST method, with the client authentication and endpoint request parameters passed in the POST body. Federations can choose to also use other client authentication methods.

8.8.1. Client Authentication Metadata for Federation Endpoints

Like other OAuth and OpenID endpoints supporting client authentication, this specification defines metadata parameters saying which client authentication methods are supported. These largely parallel the token_endpoint_auth_methods_supported and token_endpoint_auth_signing_alg_values_supported metadata values defined in Section 3 of OpenID Connect Discovery 1.0 [OpenID.Discovery].

Specifically, for each of the federation endpoints defined in Section 5.1.1, parameters named *_auth_methods and *_auth_signing_algs are defined, where the * represents the federation endpoint names federation_fetch_endpoint, federation_list_endpoint, ..., federation_historical_keys_endpoint.

The *_auth_methods metadata parameters list supported client authentication methods, just as token_endpoint_auth_methods_supported does. In addition, the value none MAY be used to indicate that client authentication is not required at the endpoint.

So, for instance, this metadata declaration states that requests authenticated with private_key_jwt are REQUIRED at the federation_trust_mark_endpoint:

"federation_trust_mark_endpoint_auth_methods": ["private_key_jwt"]
Figure 40: Declaring that client authentication is REQUIRED at an endpoint

If omitted, the default value for these methods is ["none"], indicating that only unauthenticated requests are accepted.

The *_auth_signing_algs metadata parameters list supported client authentication signing algorithms supported, just as token_endpoint_auth_signing_alg_values_supported does. If omitted and private_key_jwt is supported, the default value is ["RS256"]. The value none MUST NOT be used.

8.9. Error Responses from Federation Endpoints

If the request was malformed or an error occurred during the processing of the request, the response body SHOULD be a JSON object with the content type application/json. In compliance with [RFC6749], the following standardized error format SHOULD be used:

error

REQUIRED. One of the following error codes SHOULD be used.

invalid_request
The request is incomplete or does not comply with current specifications. The HTTP response status code SHOULD be 400 (Bad Request).
invalid_client
The Client cannot be authorized or is not a valid participant of the federation. The HTTP response status code SHOULD be 401 (Unauthorized).
invalid_issuer
The endpoint cannot service the requested issuer. The HTTP response status code SHOULD be 404 (Not Found).
not_found
The requested Entity Identifier is "not found". The HTTP response status code SHOULD be 404 (Not Found).
server_error
The server encountered an unexpected condition that prevented it from fulfilling the request. The HTTP response status code SHOULD be one in the 5xx range, like 500 (Internal Server Error).
temporarily_unavailable
The server hosting the federation endpoint is currently unable to handle the request due to a temporary overloading or maintenance. The HTTP response status code SHOULD be 503 (Service Unavailable).
unsupported_parameter
The server does not support the requested parameter.

Other error codes in the IANA "OAuth Extensions Error Registry" [IANA.OAuth.Parameters] MAY also be used.

error_description
REQUIRED. A human-readable short text describing the error.

The following is a non-normative example of an error response:

400 Bad request
Content-Type: application/json

{
  "error": "invalid_request",
  "error_description":
    "Required request parameter [sub] was missing."
}
Figure 41: Example Error Response

9. Obtaining Federation Entity Configuration Information

The Entity Configuration of every participant SHOULD be exposed at a well-known endpoint. The configuration endpoint is found using the Well-Known URIs [RFC8615] specification, with the suffix openid-federation. The scheme, host, and port are taken directly from the Entity Identifier combined with the following path: /.well-known/openid-federation.

If the Entity Identifier contains a path, it is concatenated after /.well-known/openid-federation in the same manner that path components are concatenated to the well-known identifier in the OAuth 2.0 Authorization Server Metadata [RFC8414] specification. Of course, in real multi-tenant deployments, in which the Entity Identifier might be of the form https://multi-tenant-service.example.com/my-tenant-identifier the tenant is very likely to not have control over the path https://multi-tenant-service.example.com/.well-known/openid-federation/my-tenant-identifier whereas it is very likely to have control over the path https://multi-tenant-service.example.com/my-tenant-identifier/.well-known/openid-federation. Therefore, if using the configuration endpoint at the URL with the tenant path after the well-known part fails, it is RECOMMENDED that callers retry at the URL with the tenant path before the well-known part (even though this violates [RFC8615]).

Entities SHOULD make an Entity Configuration document available at the configuration endpoint. There is only one exception to this rule and that is for an RP that only does Explicit Registration. Since it posts the Entity Configuration to the OP during client registration, the OP has everything it needs from the RP.

9.1. Federation Entity Configuration Request

An Entity Configuration document MUST be queried using an HTTP GET request at the previously specified path.

In this example, the requesting party would make the following request to the Entity https://openid.sunet.se to obtain its Entity Configuration:

  GET /.well-known/openid-federation HTTP/1.1
  Host: openid.sunet.se
Figure 42: Request for Entity Configuration

9.2. Federation Entity Configuration Response

The response is an Entity Configuration, as described in Section 3. If the Entity is an Intermediate Entity or a Trust Anchor, the response MUST contain metadata for a federation Entity (federation_entity).

A successful response MUST use the HTTP status code 200 with the content type application/entity-statement+jwt, to make it clear that the response contains an Entity Statement. In case of an error, the response is as defined in Section 8.9.

The following is a non-normative example JWT Claims Set for a response from an Intermediate Entity:

{
  "iss": "https://openid.sunet.se",
  "sub": "https://openid.sunet.se",
  "iat": 1516239022,
  "exp": 1516298022,
  "metadata": {
    "federation_entity": {
      "contacts": ["ops@sunet.se"],
      "federation_fetch_endpoint": "https://sunet.se/openid/fedapi",
      "homepage_uri": "https://www.sunet.se",
      "organization_name": "SUNET"
    },
    "openid_provider": {
      "issuer": "https://openid.sunet.se",
      "signed_jwks_uri": "https://openid.sunet.se/jwks.jose",
      "authorization_endpoint":
        "https://openid.sunet.se/authorization",
      "client_registration_types_supported": [
        "automatic",
        "explicit"
      ],
      "grant_types_supported": [
        "authorization_code"
      ],
      "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"
      ],
      "subject_types_supported": [
        "pairwise",
        "public"
      ],
      "token_endpoint": "https://openid.sunet.se/token",
      "federation_registration_endpoint":
        "https://op.umu.se/openid/fedreg",
      "token_endpoint_auth_methods_supported": [
        "private_key_jwt"
      ]

    }
  },
  "jwks": {
    "keys": [
      {
        "alg": "RS256",
        "e": "AQAB",
        "kid": "key1",
        "kty": "RSA",
        "n": "pnXBOusEANuug6ewezb9J_...",
        "use": "sig"
      }
    ]
  },
  "authority_hints": [
    "https://edugain.org/federation"
  ]
}
Figure 43: Entity Configuration Response JWT Claims Set

10. Resolving the Trust Chain and Metadata

An Entity (Party A) that wants to establish trust with another Entity (Party B) MUST have Party B's Entity Identifier and a list of Entity Identifiers of Trust Anchors and their public signing keys. Party A will first have to fetch sufficient Entity Statements to establish at least one chain of trust from Party B to one or more of the Trust Anchors. After that, Party A MUST validate the Trust Chains independently, and if there are multiple valid Trust Chains and if the application demands it, choose one to use.

10.1. Fetching Entity Statements to Establish a Trust Chain

Depending on the circumstances, Party A MAY be handed Party B's Entity Configuration, or it may have to fetch it by itself. If it needs to fetch it, it will use the process described in Section 9 based on the Entity Identifier of Party B.

The next step is to iterate through the list of Intermediates listed in authority_hints, ignoring the authority hints that end in an unknown Trust Anchor, requesting an Entity Configuration from each of the Intermediates. If the received Entity Configuration contains an authority hint, this process is repeated.

With the list of all Intermediates and the Trust Anchor, the respective fetch endpoints, as defined in Section 8.1, are used to fetch Entity Statements about the Intermediates and Party B.

Note: Federation participants SHOULD NOT attempt to fetch Entity Statements they already have obtained during this process to prevent loops.

A successful operation will return one or more lists of Entity Statements. Each of the lists terminating in a self-signed Entity Statement is issued by a Trust Anchor.

If there is no path from Party B to at least one of the trusted Trust Anchors, then the list will be empty and there is no way of establishing trust in Party B's information. How Party A deals with this is out of scope for this specification.

The following sequence diagram represents the interactions between the RP, the OP, and the Trust Anchor during a trust evaluation made by the OP about the RP. Relating this to the preceding description, in this diagram, Party A is the OP and Party B is the RP.

+-----+                         +-----+                             +--------------+
| RP  |                         | OP  |                             | Trust Anchor |
+-----+                         +-----+                             +--------------+
   |                               |                                        |
   | Entity Configuration Request  |                                        |
   |<------------------------------|                                        |
   |                               |                                        |
   | Entity Configuration Response |                                        |
   |------------------------------>|                                        |
   |                               |                                        |
   |                               | Evaluates authority_hints              |
   |                               |--------------------------              |
   |                               |                         |              |
   |                               |<-------------------------              |
   |                               |                                        |
   |                               | Entity Configuration Request           |
   |                               |--------------------------------------->|
   |                               |                                        |
   |                               |        Entity Configuration Response   |
   |                               |<---------------------------------------|
   |                               |                                        |
   |                               | Obtains Fetch endpoint                 |
   |                               |-----------------------                 |
   |                               |                      |                 |
   |                               |<----------------------                 |
   |                               |                                        |
   |                               | Request Subordinate Statement about RP |
   |                               |--------------------------------------->|
   |                               |                                        |
   |                               |        Subordinate Statement about RP  |
   |                               |<---------------------------------------|
   |                               |                                        |
   |                               | Evaluates the Trust Chain              |
   |                               |--------------------------              |
   |                               |                         |              |
   |                               |<-------------------------              |
   |                               |                                        |
   |                               | Applies Metadata Policies              |
   |                               |--------------------------              |
   |                               |                         |              |
   |                               |<-------------------------              |
   |                               |                                        |
   |                               | Derives the RP's final Metadata        |
   |                               |----------------------------------      |
   |                               |                                 |      |
   |                               |<---------------------------------      |
Figure 44: Resolving Trust Chain and Metadata from the Perspective of an OP

10.2. Validating a Trust Chain

As described in Section 4, a Trust Chain consists of an ordered list of Entity Statements. So however Party A has acquired the set of Entity Statements, it MUST now verify that it is a proper Trust Chain using the rules laid out in that section.

Let us refer to the Entity Statements in the Trust Chain as ES[j], where j = 0,...,i, with 0 being the index of the first Entity Statement and i being the zero-based index of the last. To validate the Trust Chain, the following MUST be done:

  • For each Entity Statement ES[j], where j = 0,..,i:

    • Verify that the statement contains all the required claims.

    • Verify that iat has a value in the past.

    • Verify that exp has a value that is in the future.

  • For ES[0] (the Entity Configuration of the Trust Chain subject), verify that iss == sub.

  • For ES[0], verify that its signature validates with a public key in ES[0]["jwks"].

  • For each j = 0,...,i-1, verify that ES[j]["iss"] == ES[j+1]["sub"].

  • For each j = 0,...,i-1, verify the signature of ES[j] with a public key in ES[j+1]["jwks"].

  • For ES[i] (the Trust Anchor's Entity Configuration), verify that the issuer matches the Entity Identifier of the Trust Anchor.

  • For ES[i], verify that its signature validates with a public key of the Trust Anchor.

Verifying the signature is a much more expensive operation than verifying the correctness of the statement and the timestamps. An implementer MAY therefore choose not to verify the signatures until all the other checks have been done.

Federation participants MAY cache Entity Statements and signature verification results until they expire, per Section 10.4.

10.3. Choosing One of the Valid Trust Chains

If multiple valid Trust Chains are found, Party A will need to decide on which one to use. One simple rule would be to prefer a shorter chain over a longer one. Federation participants MAY follow other rules according to local policy.

10.4. Calculating the Expiration Time of a Trust Chain

Each Entity Statement in a Trust Chain is signed and MUST have an expiration time (exp). The expiration time of the whole Trust Chain is the minimum (exp) value within the Trust Chain.

10.5. Transient Trust Chain Validation Errors

If the federation topology is being updated, for example when a set of Leaf Entities is moved to a new Intermediate Entity, the Trust Chain validation may fail in a transient manner. Retrying after a period of time may resolve the situation.

10.6. Resolving the Trust Chain and Metadata with a Resolver

Note that an alternative method for resolving a Trust Chain for an Entity (Party B) using the methods described above is to use a resolve endpoint, as described in Section 8.3. This lets the resolver do the work that otherwise the Entity (Party A) wanting to establish trust would have to do for itself.

11. Updating Metadata, Key Rollover, and Revocation

This specification facilitates smoothly updating metadata and public keys.

As described in Section 10.4, each Trust Chain has an expiration time. Federation participants MUST support refreshing a Trust Chain when it expires. How often a participant reevaluates the Trust Chain depends on how quickly it wants to find out that something has changed.

11.1. Protocol Key Rollover

If a Leaf Entity publishes its public keys in its metadata using jwks, the expiration time of its Entity Configuration can be used to control how often the receiving Entity needs to fetch an updated set of public keys.

11.2. Key Rollover for a Trust Anchor

A Trust Anchor MUST publish an Entity Configuration about itself. The Trust Anchor SHOULD set an expiration time on its Entity Configuration, such that federation participants will re-fetch it at reasonable intervals. When a Trust Anchor rolls over its signing keys, it needs to:

  1. Add the new keys to the jwks representing the Trust Anchor's signing keys in its Entity Configuration.

  2. Keep signing the Entity Configuration and the Entity Statements using the old keys for a long enough time period to allow all Subordinates to have obtained the new keys.

  3. Switch to signing with the new keys.

  4. After a reasonable time period, remove the old keys. What is regarded as a reasonable time is dependent on the security profile and risk assessment of the Trust Anchor.

11.3. Redundant Retrieval of Trust Anchor Keys

It is RECOMMENDED that Federation Operators provide a means of retrieving the public keys for the Trust Anchors it administers that is independent of those Trust Anchors' Entity Configurations. This is intended to provide redundancy in the eventuality of the compromise of the Web PKI infrastructure underlying retrieval of public keys from Entity Configurations.

The keys retrieved via the independent mechanism specified by the Federation Operator SHOULD be compared to those retrieved via the Trust Anchor's Entity Configuration. If they do not match, both SHOULD be retrieved again. If they still do not match, it is indicative of a security or configuration problem. The appropriate remediation steps in that eventuality SHOULD be specified by the Federation Operator.

11.4. Revocation

Since the participants in federations are expected to check the Trust Chain on a regular frequent basis, this specification does not define a revocation process. Specific federations MAY make a different choice and will then have to define their own revocation process.

12. OpenID Connect Client Registration

This section describes how the mechanisms defined in this specification are used to establish trust between an RP and an OP that have no explicit configuration or registration between them in advance.

There are two alternative approaches to establish trust between an RP and an OP, which we call Automatic Registration and Explicit Registration. Members of a federation or a community SHOULD agree upon which one to use. While implementations should support both methods, deployments MAY choose to use one or the other of them.

Independent of whether the RP uses Automatic or Explicit Registration, the way that the RP learns about the OP is the same: It uses the procedure described in Section 10.

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.

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.

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, the RP MUST NOT be supplied with a Client Secret. Instead, the Automatic Registration model requires the RP to use asymmetric cryptography to authenticate its requests.

  • The OP MUST publish that it supports one or more request authentication methods using the openid_provider metadata parameter request_authentication_methods_supported.

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 as described in Section 6.1 of OpenID Connect Core 1.0 [OpenID.Core] or using a pushed authorization request, as described in Pushed Authorization Requests [RFC9126].

12.1.1.1. Using a Request Object

When a Request Object is used, 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 Audience (aud) value MUST be or include the OP's Issuer Identifier URL.
iss
REQUIRED. The iss value MUST be the Client Identifier.
sub
MUST NOT be present. This, together with the value of aud, prevent 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, as defined in [RFC7519].
iat
OPTIONAL. Number. Time when this Request Object was issued. This is expressed as Seconds Since the Epoch, as defined in [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, sorted as in Section 4. 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.
12.1.1.1.1. Authorization Request with a Trust Chain

When the trust_chain request parameter is used in the Authorization Request Object, 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, request_uri, or a Pushed Authorization Request [RFC9126] for the request.

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

{
  "alg": "RS256",
  "kid": "that-kid-which-points-to-a-jwk-contained-in-the-trust-chain",
}
.
{
  "aud": "https://op.example.org/authorization-endpoint",
  "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",
  "trust_chain" : [
    "eyJhbGciOiJSUzI1NiIsImtpZCI6Ims1NEhRdERpYnlHY3M5WldWTWZ2aUhm ...",
    "eyJhbGciOiJSUzI1NiIsImtpZCI6IkJYdmZybG5oQU11SFIwN2FqVW1BY0JS ...",
    "eyJhbGciOiJSUzI1NiIsImtpZCI6IkJYdmZybG5oQU11SFIwN2FqVW1BY0JS ..."
  ]
}
Figure 45: 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=eyJhbGciOiJSUzI1NiIsImtpZCI6Ik5fX0Q5OEl2QjhOYWUta3dBNm5yT3QtaXBU
        aGpIa0R4MzduaWNETUgzTjQifQ.eyJhdWQiOiJodHRwczovL29wLmV4YW1wbGUub
        3JnL2F1dGhvcml6YXRpb24tZW5kcG9pbnQiLCJjbGllbnRfaWQiOiJodHRwczovL
        3JwLmV4YW1wbGUuY29tIiwiZXhwIjoxNTg5Njk5MTYyLCJpYXQiOjE1ODk2OTkxM
        DIsImlzcyI6Imh0dHBzOi8vcnAuZXhhbXBsZS5jb20iLCJqdGkiOiI0ZDNlYzBmO
        DFmMTM0ZWU5YTk3ZTA0NDliZTZkMzJiZSIsIm5vbmNlIjoiNExYMG1GTXhkQmprR
        210eDdhOFdJT25CIiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly9ycC5leGFtcGxlL
        mNvbS9hdXRoel9jYiIsInJlc3BvbnNlX3R5cGUiOiJjb2RlIiwic2NvcGUiOiJvc
        GVuaWQgcHJvZmlsZSBlbWFpbCBhZGRyZXNzIHBob25lIiwic3RhdGUiOiJZbVg4U
        E05STdXYk5vTW5uaWVLS0JpcHRWVzBzUDJPWiIsInRydXN0X2NoYWluIjpbImV5S
        mhiR2NpT2lKU1V6STFOaUlzSW10cFpDSTZJbXMxTkVoUmRFUnBZbmxIWTNNNVdsZ
        FdUV1oyYVVobSAuLi4iLCJleUpoYkdjaU9pSlNVekkxTmlJc0ltdHBaQ0k2SWtKW
        WRtWnliRzVvUVUxMVNGSXdOMkZxVlcxQlkwSlMgLi4uIiwiZXlKaGJHY2lPaUpTV
        XpJMU5pSXNJbXRwWkNJNklrSllkbVp5Ykc1b1FVMTFTRkl3TjJGcVZXMUJZMEpTI
        C4uLiJdfQ.Rv0isfuku0FcRFintgxgKDk7EnhFkpQRg3Tm6N6fCHAHEKFxVVdjy4
        9JboJtxKcQVZKN9TKn3lEYM1wtF1e9PQrNt4HZ21ICfnzxXuNx1F5SY1GXCU2n2y
        FVKtz3N0YkAFbTStzy-sPRTXB0stLBJH74RoPiLs2c6dDvrwEv__GA7oGkg2gWt6
        VDvnfDpnvFi3ZEUR1J8MOeW_VFsayrT9sNjyjsz62Po4LzvQKQMKxq0dNwPNYuuS
        fUmb-YvmFguxDb3weYl8WS-
        48EIkP1h4b_KGU9x9n7a1fUOHrS02ATQZmaL8jUil7yLJqx5MiCsPr4pCAXV0doA
        4pwhs_FIw HTTP/1.1

Figure 46: Authentication Request Using Request Object
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 present a Trust Chain related to itself to the OP in the Request Object using the trust_chain request parameter defined in Section 12.1.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 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. Whenever the OP uses a Trust Chain submitted by an RP, the OP MUST fully verify it, including every Entity Statement contained in it. 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.

If the RP does not include the trust_chain request parameter in the Request Object, 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, 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 a Request Object directly to the AS in exchange for a request_uri.

There are four applicable authentication methods:

  • JWT Client authentication, as described for private_key_jwt in Section 9 of OpenID Connect Core 1.0 [OpenID.Core].

  • 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 one key in the JWK Set describing the RP's keys.

  • mTLS using public key infrastructure (PKI), as described in Section 2.1 of [RFC8705].

  • A Request Object, as described in Section 12.1.1.1 and Section 12.1.1.1.1.

Note that if mTLS is used, TLS client authentication MUST be configured and, in the case of self-signed certificates, the server must omit the certificate chain validation.

Using the example above, a Pushed Authorization Request 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.eyJzdWIiOiAiaHR0cHM6Ly9ycC
  5leGFtcGxlLmNvbSIsICJpc3MiOiAiaHR0cHM6Ly9ycC5leGFtc
  GxlLmNvbSIsICJpYXQiOiAxNTg5NzA0NzAxLCAiZXhwIjogMTU4
  OTcwNDc2MSwgImF1ZCI6ICJodHRwczovL29wLmV4YW1wbGUub3J
  nL2F1dGhvcml6YXRpb24iLCAianRpIjogIjM5ZDVhZTU1MmQ5Yz
  Q4ZjBiOTEyZGM1NTY4ZWQ1MGQ2In0.oUt9Knx_lxb4V2S0tyNFH
  CNZeP7sImBy5XDsFxv1cUpGkAojNXSy2dnU5HEzscMgNW4wguz6
  KDkC01aq5OfN04SuVItS66bsx0h4Gs7grKAp_51bClzreBVzU4g
  _-dFTgF15T9VLIgM_juFNPA_g4Lx7Eb5r37rWTUrzXdmfxeou0X
  FC2p9BIqItU3m9gmH0ojdBCUX5Up0iDsys6_npYomqitAcvaBRD
  PiuUBa5Iar9HVR-H7FMAr7aq7s-dH5gx2CHIfM3-qlc2-_Apsy0
  BrQl6VePR6j-3q6JCWvNw7l4_F2UpHeanHb31fLKQbK-1yoXDNz
  DwA7B0ZqmuSmMFQ
Figure 47: Pushed Authorization Request
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 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.
tls_client_auth

If the certificate used is not self-signed, it MUST first be validated as chaining to a trusted root. (The selection of trusted roots is outside of this trust model.)

The RP metadata MUST contain exactly one of the five members listed in Section 2.1.2 of [RFC8705]. For example, if the tls_client_auth_san_dns member is specified with a value of host.example.com, the certificate would only match for authentication if that DNS name is present in the Subject Alternative Name (SAN) of the certificate.

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. Authentication Error Response

If the OP fails to establish trust with the RP, it SHOULD use an appropriate error code and an error_description that aids the RP in understanding what is wrong.

In addition to the error codes contained in the IANA "OAuth Extensions Error Registry" registry [IANA.OAuth.Parameters], this specification also defines the following error codes:

missing_trust_anchor
No trusted Trust Anchor could be found.
validation_failed
Trust chain validation failed.

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

HTTP/1.1 302 Found
  Location: https://client.example.org/cb?
    error=missing_trust_anchor
    &error_description=
      Could%20not%20find%20a%20trusted%20anchor
    &state=af0ifjsldkj
Figure 48: Authentication Error Response

12.1.3. Possible Other Uses of Automatic Registration

Automatic Registration is designed to be able to be employed for use cases beyond OpenID Federation. For instance, ecosystems using OpenID Connect [OpenID.Core], OAuth 2.0 [RFC6749], and FAPI [FAPI] can utilize Automatic Registration.

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, a Client Secret, and 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. In that case, the Registration Request will 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 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 resolved OP 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.

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

  6. The content type of the Registration Request MUST be application/entity-statement+jwt when it contains only the Entity Configuration of the requestor. Otherwise, when it contains the 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.

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. Its value MUST be the Entity Identifier of the OP.
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. Explicit Client Registration Response

12.2.2.1. Processing of the Request by the 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. If the request contains an Entity Configuration the OP MUST use it 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 Anchor from those chains as the one to proceed with.

  3. If the request contains 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 Entity Configuration from the Trust Chain and proceed according to Step 2, as if only an Entity Configuration was received.

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

  5. The OP will now use the RP metadata 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].

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

  7. 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_id claim of the Entity Statement to the Trust Anchor it selected to process the request. The authority_hints claim MUST be set to the OP'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.3.

    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.

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

The following Entity Statement claims are specified for use in Explicit Registration responses.

iss
REQUIRED. Its value MUST be the Entity Identifier of the OP. See Section 3 for the full specification.
sub
REQUIRED. Its value MUST be the Entity Identifier of the RP. See Section 3 for the full specification.
iat
REQUIRED. See Section 3 for the full specification.
exp
REQUIRED. See Section 3 for the full specification.
jwks
OPTIONAL. If present, it MUST be a verbatim copy of the jwks Entity Statement claim from the received Entity Configuration of the RP. This claim is defined at Section 3. Note that this is distinct from the identically named RP metadata parameter.
aud
REQUIRED. Its value MUST be the Entity Identifier of the RP. See [RFC7519] for the full specification. This claim is specific to Explicit Registration responses and is not a general Entity Statement claim.
trust_anchor_id
REQUIRED. Its value MUST be the Entity Identifier of the Trust Anchor that the OP selected to process the Explicit Registration request. This claim is specific to Explicit Registration responses and 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 OP in the Trust Chain that the OP selected to process the request. See Section 3 for the full specification.
metadata
REQUIRED. It MUST contain the registered RP metadata under the openid_relying_party Entity Type Identifier. See Section 3 for the full specification.
crit
OPTIONAL. See Section 3 for the full specification.

A successful response MUST have an HTTP status code 200 and the content type application/entity-statement+jwt.

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

12.2.2.2. Processing of the Response by the 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 trust_anchor_id represents one of its own Trust Anchors.

  3. 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_id claim.

  4. The RP MUST ensure that the metadata it was registered with at the OP complies with the Trust Chain openid_relying_party policies, which Trust Chain is resolved using the trust_anchor_id and authority_hints claims of the received registration Entity Statement. The RP SHOULD perform this check by applying the resolved policies to the metadata as specified in Section 6.1.4.1, or utilize another equivalent method.

  5. 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.3. After an Explicit Client Registration

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 OP expiration of the client_id coincides with an OAuth 2.0 flow that was just initiated by the RP, this may cause OpenID Connect authentication requests, token requests, or UserInfo requests to suddenly fail. Renewing the RP 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.

  • Instead of using a Client Secret to authenticate the client, 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.

12.5. Rationale for the Trust Chain 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.

13. General-Purpose JWT Claims

This section defines general-purpose JWT claims designed to be used by many different JWT profiles. They are also used in specific kinds of JWTs defined by this specification.

13.1. "crit" (Critical) Claim

The crit (critical) claim indicates that extensions to the set of claims specified for use in this type of JWT are being used that MUST be understood and processed. It is used in the same way that the crit header parameter is used for extension JOSE header parameters that MUST be understood and processed. Its value is an array listing the claim names present in the JWT that use those extensions. If any of the listed claims are not understood and supported by the recipient, then the JWT is invalid. Producers MUST NOT include claim names already specified for use in this type of JWT, duplicate names, or names that do not occur as claim names in the JWT in the crit list. Producers MUST NOT use the empty array [] as the crit value. Use of this claim is OPTIONAL.

13.2. "id" (Identifier) Claim

The id (identifier) claim provides an identifier for a property of the JWT. Like the sub (subject) claim, the processing of this claim is generally application specific. The id value is a case-sensitive string containing a StringOrURI value. Use of this claim is OPTIONAL.

13.3. "ref" (Reference) Claim

The ref (reference) claim provides a URI for information pertaining to the JWT. Like the sub (subject) claim, the processing of this claim is generally application specific. The ref value is a case-sensitive string containing a URI value. Use of this claim is OPTIONAL.

13.4. "delegation" (Delegation) Claim

The delegation claim expresses a delegation relationship. Like the sub (subject) claim, the processing of this claim is generally application specific. The delegation value is a case-sensitive string containing a StringOrURI value. Use of this claim is OPTIONAL.

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. Security Considerations

15.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, the resolve endpoint (Section 8.2), 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].

Implementations should set a limit on the number of authority_hints they are willing to inspect. This is to protect against attacks where an adversary might define a large count of false authority_hints in their Entity Configuration.

Entities may be required to include a Trust Chain (Section 4.3) 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.

A Trust Mark can be statically validated using the public key of its issuer. The static validation of the Trust Marks represents a filter against propagation attacks. If the OpenID Provider (OP) discovers at least one valid Trust Mark within an Entity Configuration, this may serve as evidence of the reliability of the Relying Party that initiated the request. Given that the Trust Mark is optional, the decision to require one is at the discretion of the federation implementation, where a federation may define and require Trust Marks according to specific needs.

If Client authentication is not required at the resolve endpoint, then incoming requests should not automatically trigger the collection (Federation Entity Discovery process) and assessment of Trust Chains. Instead, the resolve endpoint should only respond to unauthenticated Client requests with cached information about Entities that have already been evaluated and deemed trustworthy. The initiation of the Federation Entity Discovery process should not be the default action for the resolve endpoint in this case.

15.2. Unsigned Error Messages

One of the fundamental design goals of this protocol is to protect messages end-to-end. This cannot be accomplished by demanding TLS since TLS, in lots of cases, is not end-to-end but ends in a HTTPS to HTTP Reverse Proxy. Allowing unsigned error messages therefore opens an attack vector for someone who wants to run a Denial-of-Service attack. This is not specific to OpenID Federation but equally valid for other protocols when HTTPS to HTTP reverse proxies are used.

16. IANA Considerations

16.1. OAuth Authorization Server Metadata Registration

This specification registers the following metadata entries in the IANA "OAuth Authorization Server Metadata" registry [IANA.OAuth.Parameters] established by [RFC8414].

16.1.1. Registry Contents

  • Metadata Name: client_registration_types_supported

  • Metadata Description: Client Registration Types Supported

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 5.1.3 of this specification

  • Metadata Name: federation_registration_endpoint

  • Metadata Description: Federation Registration Endpoint

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 5.1.3 of this specification

  • Metadata Name: request_authentication_methods_supported

  • Metadata Description: Authentication request authentication methods supported

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 5.1.3 of this specification

  • Metadata Name: request_authentication_signing_alg_values_supported

  • Metadata Description: JSON array containing the JWS signing algorithms supported for the signature on the JWT used to authenticate the request

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 5.1.3 of this specification

  • Metadata Name: signed_jwks_uri

  • Metadata Description: URL referencing a signed JWT having this authorization server's JWK Set document as its payload

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 5.2.1 of this specification

  • Metadata Name: jwks

  • Metadata Description: JSON Web Key Set document, passed by value

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 5.2.1 of this specification

  • Metadata Name: organization_name

  • Metadata Description: Human-readable name representing the organization owning this authorization server

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 5.2.2 of this specification

  • Metadata Name: contacts

  • Metadata Description: Array of strings representing ways to contact people responsible for this authorization server, typically email addresses

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 5.2.2 of this specification

  • Metadata Name: logo_uri

  • Metadata Description: URL that references a logo for the organization owning this authorization server

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 5.2.2 of this specification

  • Metadata Name: homepage_uri

  • Metadata Description: URL of a Web page for the organization owning this authorization server

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 5.2.2 of this specification

16.2. OAuth Dynamic Client Registration Metadata Registration

This specification registers the following client metadata entries in the IANA "OAuth Dynamic Client Registration Metadata" registry [IANA.OAuth.Parameters] established by [RFC7591].

16.2.1. Registry Contents

  • Client Metadata Name: client_registration_types

  • Client Metadata Description: An array of strings specifying the client registration types the RP wants to use

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 5.1.2 of this specification

  • Client Metadata Name: signed_jwks_uri

  • Client Metadata Description: URL referencing a signed JWT having the client's JWK Set document as its payload

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 5.2.1 of this specification

  • Client Metadata Name: organization_name

  • Client Metadata Description: Human-readable name representing the organization owning this client

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 5.2.2 of this specification

  • Metadata Name: homepage_uri

  • Metadata Description: URL of a Web page for the organization owning this client

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 5.2.2 of this specification

16.3. OAuth Extensions Error Registration

This section registers the following values in the IANA "OAuth Extensions Error Registry" registry [IANA.OAuth.Parameters] established by [RFC6749].

16.3.1. Registry Contents

  • Name: missing_trust_anchor

  • Usage Location: Authorization Request

  • Protocol Extension: OpenID Federation

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Reference: Section 12.1.2 of this specification

  • Name: validation_failed

  • Usage Location: Authorization Request

  • Protocol Extension: OpenID Federation

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Reference: Section 12.1.2 of this specification

16.4. Media Type Registration

This section registers the following media types [RFC2046] in the "Media Types" registry [IANA.MediaTypes] in the manner described in [RFC6838].

16.4.1. Registry Contents

  • Type name: application

  • Subtype name: entity-statement+jwt

  • Required parameters: n/a

  • Optional parameters: n/a

  • Encoding considerations: binary; An Entity Statement is a JWT; JWT values are encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') characters.

  • Security considerations: See Section 15 of this specification

  • Interoperability considerations: n/a

  • Published specification: Section 3 of this specification

  • Applications that use this media type: Applications that use this specification

  • Fragment identifier considerations: n/a

  • Additional information:

    • Magic number(s): n/a

    • File extension(s): n/a

    • Macintosh file type code(s): n/a

  • Person & email address to contact for further information:

    Michael B. Jones, michael_b_jones@hotmail.com

  • Intended usage: COMMON

  • Restrictions on usage: none

  • Author: Michael B. Jones, michael_b_jones@hotmail.com

  • Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Provisional registration? No

  • Type name: application

  • Subtype name: trust-mark+jwt

  • Required parameters: n/a

  • Optional parameters: n/a

  • Encoding considerations: binary; A Trust Mark is a JWT; JWT values are encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') characters.

  • Security considerations: See Section 15 of this specification

  • Interoperability considerations: n/a

  • Published specification: Section 7 of this specification

  • Applications that use this media type: Applications that use this specification

  • Fragment identifier considerations: n/a

  • Additional information:

    • Magic number(s): n/a

    • File extension(s): n/a

    • Macintosh file type code(s): n/a

  • Person & email address to contact for further information:

    Michael B. Jones, michael_b_jones@hotmail.com

  • Intended usage: COMMON

  • Restrictions on usage: none

  • Author: Michael B. Jones, michael_b_jones@hotmail.com

  • Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Provisional registration? No

  • Type name: application

  • Subtype name: resolve-response+jwt

  • Required parameters: n/a

  • Optional parameters: n/a

  • Encoding considerations: binary; An Entity Resolve Response is a signed JWT; JWT values are encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') characters.

  • Security considerations: See Section 15 of this specification

  • Interoperability considerations: n/a

  • Published specification: Section 8.3.2 of this specification

  • Applications that use this media type: Applications that use this specification

  • Fragment identifier considerations: n/a

  • Additional information:

    • Magic number(s): n/a

    • File extension(s): n/a

    • Macintosh file type code(s): n/a

  • Person & email address to contact for further information:

    Michael B. Jones, michael_b_jones@hotmail.com

  • Intended usage: COMMON

  • Restrictions on usage: none

  • Author: Michael B. Jones, michael_b_jones@hotmail.com

  • Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Provisional registration? No

  • Type name: application

  • Subtype name: trust-chain+json

  • Required parameters: n/a

  • Optional parameters: n/a

  • Encoding considerations: binary; A Trust Chain is a JSON array of JWTs; JWT values are encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') characters.

  • Security considerations: See Section 15 of this specification

  • Interoperability considerations: n/a

  • Published specification: Section 12.2.1 of this specification

  • Applications that use this media type: Applications that use this specification

  • Fragment identifier considerations: n/a

  • Additional information:

    • Magic number(s): n/a

    • File extension(s): n/a

    • Macintosh file type code(s): n/a

  • Person & email address to contact for further information:

    Michael B. Jones, michael_b_jones@hotmail.com

  • Intended usage: COMMON

  • Restrictions on usage: none

  • Author: Michael B. Jones, michael_b_jones@hotmail.com

  • Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Provisional registration? No

  • Type name: application

  • Subtype name: trust-mark-delegation+jwt

  • Required parameters: n/a

  • Optional parameters: n/a

  • Encoding considerations: binary; A Trust Mark delegation is a signed JWT; JWT values are encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') characters.

  • Security considerations: See Section 15 of this specification

  • Interoperability considerations: n/a

  • Published specification: Section 7.3 of this specification

  • Applications that use this media type: Applications that use this specification

  • Fragment identifier considerations: n/a

  • Additional information:

    • Magic number(s): n/a

    • File extension(s): n/a

    • Macintosh file type code(s): n/a

  • Person & email address to contact for further information:

    Roland Hedberg, roland@catalogix.se

  • Intended usage: COMMON

  • Restrictions on usage: none

  • Author: Roland Hedberg, roland@catalogix.se

  • Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Provisional registration? No

  • Type name: application

  • Subtype name: jwk-set+jwt

  • Required parameters: n/a

  • Optional parameters: n/a

  • Encoding considerations: binary; A signed JWK Set is a signed JWT; JWT values are encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') characters.

  • Security considerations: See Section 15 of this specification

  • Interoperability considerations: n/a

  • Published specification: Section 8.7.2 of this specification

  • Applications that use this media type: Applications that use this specification

  • Fragment identifier considerations: n/a

  • Additional information:

    • Magic number(s): n/a

    • File extension(s): n/a

    • Macintosh file type code(s): n/a

  • Person & email address to contact for further information:

    Michael B. Jones, michael_b_jones@hotmail.com

  • Intended usage: COMMON

  • Restrictions on usage: none

  • Author: Michael B. Jones, michael_b_jones@hotmail.com

  • Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Provisional registration? No

16.5. OAuth Parameters Registration

This specification registers the following parameter name in the IANA "OAuth Parameters" registry [IANA.OAuth.Parameters] established by [RFC6749].

16.5.1. Registry Contents

  • Parameter Name: trust_chain

  • Parameter Usage Location: authorization request

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 12.1.1.1.2 of this specification

16.6. JSON Web Signature and Encryption Header Parameters Registration

This specification registers the following JWS header parameter in the IANA "JSON Web Signature and Encryption Header Parameters" registry [IANA.JOSE] established by [RFC7515].

16.6.1. Registry Contents

  • Header Parameter Name: trust_chain

  • Header Parameter Description: OpenID Federation Trust Chain

  • Header Parameter Usage Location: JWS

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 4 of this specification

16.7. JSON Web Token Claims Registration

This specification registers the following claim in the IANA "JSON Web Token Claims" registry [IANA.JWT.Claims] established by [RFC7519].

16.7.1. Registry Contents

  • Claim Name: keys

  • Claim Description: Array of JWK values, as defined in RFC 7517

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 5.2 of this specification

  • Claim Name: trust_anchor_id

  • Claim Description: Trust Anchor ID

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 12.2.2.1 of this specification

  • Claim Name: crit

  • Claim Description: Critical Claim

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 13.1 of this specification

  • Claim Name: id

  • Claim Description: Identifier

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 13.2 of this specification

  • Claim Name: ref

  • Claim Description: Reference

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 13.3 of this specification

  • Claim Name: delegation

  • Claim Description: Delegation

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 13.4 of this specification

16.8. JSON Web Key Parameters Registration

This specification registers the following parameters in the IANA "JSON Web Key Parameters" registry [IANA.JOSE] established by [RFC7517].

16.8.1. Registry Contents

  • Parameter Name: iat

  • Parameter Description: Issued At, as defined in RFC 7519

  • Used with "kty" Value(s): *

  • Parameter Information Class: Public

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 8.7.2 of this specification

  • Parameter Name: nbf

  • Parameter Description: Not Before, as defined in RFC 7519

  • Used with "kty" Value(s): *

  • Parameter Information Class: Public

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 8.7.2 of this specification

  • Parameter Name: exp

  • Parameter Description: Expiration Time, as defined in RFC 7519

  • Used with "kty" Value(s): *

  • Parameter Information Class: Public

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 8.7.2 of this specification

  • Parameter Name: revoked

  • Parameter Description: Revoked Key Properties

  • Used with "kty" Value(s): *

  • Parameter Information Class: Public

  • Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification Document(s): Section 8.7.2 of this specification

16.9. Well-Known URI Registry

This specification registers the following well-known URI in the IANA "Well-Known URIs" registry [IANA.well-known] established by [RFC5785].

16.9.1. Registry Contents

  • URI suffix: openid-federation

  • Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net

  • Specification document: Section 9 of this specification

  • Related information: (none)

17. References

17.1. Normative References

[I-D.ietf-oauth-resource-metadata]
Jones, M. B., Hunt, P., and A. Parecki, "OAuth 2.0 Protected Resource Metadata", Work in Progress, Internet-Draft, draft-ietf-oauth-resource-metadata-05, , <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-05>.
[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.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>.
[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>.
[RFC3339]
Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, , <https://www.rfc-editor.org/info/rfc3339>.
[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>.
[RFC5280]
Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, , <https://www.rfc-editor.org/info/rfc5280>.
[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>.
[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>.
[RFC7638]
Jones, M. and N. Sakimura, "JSON Web Key (JWK) Thumbprint", RFC 7638, DOI 10.17487/RFC7638, , <https://www.rfc-editor.org/info/rfc7638>.
[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>.
[RFC8615]
Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, , <https://www.rfc-editor.org/info/rfc8615>.
[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>.
[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>.

17.2. Informative References

[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.JOSE]
IANA, "JSON Object Signing and Encryption (JOSE)", <https://www.iana.org/assignments/jose/>.
[IANA.JWT.Claims]
IANA, "JSON Web Token Claims", <https://www.iana.org/assignments/jwt>.
[IANA.MediaTypes]
IANA, "Media Types", <https://www.iana.org/assignments/media-types>.
[IANA.OAuth.Parameters]
IANA, "OAuth Parameters", <https://www.iana.org/assignments/oauth-parameters>.
[IANA.well-known]
IANA, "Well-Known URIs", <https://www.iana.org/assignments/well-known-uris>.
[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>.
[RFC5785]
Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known Uniform Resource Identifiers (URIs)", RFC 5785, DOI 10.17487/RFC5785, , <https://www.rfc-editor.org/info/rfc5785>.
[RFC6838]
Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, , <https://www.rfc-editor.org/info/rfc6838>.
[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>.

Appendix A. Example OpenID Provider Information Discovery and Client Registration

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 49: Participants Within 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.

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

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 50: 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 51: 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",
      "homepage_uri": "https://www.umu.se",
      "organization_name": "UmU"
    }
  }
}
Figure 52: 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, as defined in Section 8.1.1, 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 53: 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 54: 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 55: 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",
      "homepage_uri": "https://www.sunet.se/swamid/",
      "organization_name": "SWAMID"
    }
  }
}
Figure 56: 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 as defined in Section 8.1.1 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 57: 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 58: 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 59: 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 60: 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 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 as defined in Section 8.1.1 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 61: 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 62: 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 the fifth and final link.

We now have 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.

A.2.8. Verified 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:

{
  "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 63: Final Metadata Derived from Trust Chain by Applying Metadata Policies

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

A.3. Examples of the Two Ways of Doing Client Registration

As described in Section 12, there are two ways that can be used to do client registration:

Automatic
No negotiation between the RP and the OP is made regarding what features the client SHOULD use in future communication are done. 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=eyJhbGciOiJSUzI1NiIsImtpZCI6ImRVTjJhMDF3Umtoa1NXc
    GxRVGh2Y1ZCSU5VSXdUVWRPVUZVMlRtVnJTbWhFUVhnelpYbHBUemRR
    TkEifQ.eyJyZXNwb25zZV90eXBlIjogImNvZGUiLCAic2NvcGUiOiAi
    b3BlbmlkIHByb2ZpbGUgZW1haWwiLCAiY2xpZW50X2lkIjogImh0dHB
    zOi8vd2lraS5saWdvLm9yZyIsICJzdGF0ZSI6ICIyZmY3ZTU4OS0zOD
    Q4LTQ2ZGEtYTNkMi05NDllMTIzNWU2NzEiLCAibm9uY2UiOiAiZjU4M
    WExODYtYWNhNC00NmIzLTk0ZmMtODA0ODQwODNlYjJjIiwgInJlZGly
    ZWN0X3VyaSI6ICJodHRwczovL3dpa2kubGlnby5vcmcvb3BlbmlkL2N
    hbGxiYWNrIiwgImlzcyI6ICIiLCAiaWF0IjogMTU5MzU4ODA4NSwgIm
    F1ZCI6ICJodHRwczovL29wLnVtdS5zZSJ9.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 64: 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.

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 65: 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 66: 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_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"
  }
}
Figure 67: 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_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"
  }
}
Figure 68: Final 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 69: 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_id": "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 70: JWT Claims Set of Registration Entity Statement Returned by OP to RP after Explicit Client Registration

Appendix B. Notices

Copyright (c) 2024 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 or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications 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 requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation 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. Acknowledgements

The authors wish to acknowledge the contributions of the following individuals and organizations to this specification: Pasquale Barbaro, Brian Campbell, David Chadwick, Michele D'Amico, Andrii Deinega, Erick Domingues, Heather Flanagan, Joseph Heenan, Samuel Gulliksson, Takahiko Kawasaki, Torsten Lodderstedt, Francesco Marino, Roberto Polli, Jouke Roorda, Nat Sakimura, Mischa Sallé, Stefan Santesson, Marcos Sanz, Peter Brand, Michael Schwartz, Giada Sciarretta, Amir Sharif, Kristina Yasuda, and the JRA3T3 task force of GEANT4-2.

Appendix D. Document History

[[ To be removed from the final specification ]]

-36

-35

-34

-33

-32

-31

-30

-29

-28

-27

-26

-25

-24

-23

-22

-21

-20

-19

-18

-17

-16

-15

-14

-13

-12

-11

-10

-09

-08

-07

-06

-05

-04

Authors' Addresses

Roland Hedberg (editor)
independent
Michael B. Jones
Self-Issued Consulting
Andreas Åkre Solberg
Sikt
John Bradley
Yubico
Giuseppe De Marco
independent
Vladimir Dzhuvinov
Connect2id