OpenID Federation 1.1 - draft 00

3.1.1. Claims that MUST or MAY Appear in both Entity Configurations and Subordinate Statements

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, per [RFC7519].¶

exp

REQUIRED. Number. Expiration time after which the statement MUST NOT be accepted for processing. This is expressed as Seconds Since the Epoch, per [RFC7519].¶

jwks

REQUIRED for all Subordinate Statements, REQUIRED for all Entity Configurations of Trust Anchors and Intermediate Entities, and also REQUIRED for all Entity Configurations of Leaf Entities not using a profile permitting it to be absent. Its value is 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, by Trust Anchors and Intermediate Entities to sign Subordinate Statements about their Immediate Subordinates, and for other signatures made by Federation Entities, such as Trust Mark signatures. 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.¶

These Federation Entity Keys SHOULD NOT be used in other protocols. (Keys to be used in other protocols, such as OpenID Connect, are conveyed in the metadata elements for the protocol's Entity Type Identifiers, such as the metadata under the openid_provider and openid_relying_party Entity Type Identifiers, which are defined in [OpenID.Connect.Federation-1.1].)¶

metadata

OPTIONAL. JSON object that declares roles that the Entity plays - its Entity Types - and that contains 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.¶

crit

OPTIONAL. Entity Statements require that the crit (critical) Claim defined in Section 13.4 be understood and processed. Claims in the Entity Statement whose Claim Names are in the array that is the value of this Claim MUST be understood and processed. Claims specified for use in Entity Statements by this specification MUST NOT be included in the list.¶

3.1.2. Claims that MUST or MAY Appear in Entity Configurations but Not in Subordinate Statements

authority_hints

OPTIONAL. An array of strings representing the Entity Identifiers of Intermediate Entities or Trust Anchors that are Immediate Superiors of 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 contain the Entity Identifiers of its Immediate Superiors and MUST NOT be the empty array []. This Claim MUST NOT be present in Entity Configurations of Trust Anchors with no Superiors.¶

trust_anchor_hints

OPTIONAL. An array of strings representing the Entity Identifiers of Trust Anchors trusted by the Entity. Its value MUST NOT be the empty array []. This Claim MUST NOT be present in Entity Configurations of Trust Anchors with no Superiors.¶

trust_marks

OPTIONAL. An array of JSON objects, each representing a Trust Mark.¶

trust_mark_type

REQUIRED. Identifier for the type of the Trust Mark. The value of this Claim MUST be the same as the value of the trust_mark_type Claim contained in the Trust Mark JWT that is the value of the trust_mark Claim in this object.¶

trust_mark

REQUIRED. A signed JSON Web Token that represents a Trust Mark.¶

Trust Marks are described in Section 7.¶

trust_mark_issuers

OPTIONAL. A Trust Anchor MAY use this Claim to tell which combination of Trust Mark type 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 type 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 type identifier is empty, anyone MAY issue Trust Marks with that identifier. Trust Marks are described in Section 7.¶

trust_mark_owners

OPTIONAL. If a Federation Operator knows that a Trust Mark type 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 type 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.¶

3.1.3. Claims that MUST or MAY Appear in Subordinate Statements but Not in Entity Configurations

constraints

OPTIONAL. JSON object that defines Trust Chain constraints, as described in Section 6.2. 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.¶

metadata_policy

OPTIONAL. JSON object that defines a metadata policy, as described in Section 6.1. 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.¶

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

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

5.1.1. Federation Entity

The Entity Type Identifier is federation_entity.¶

The Entities that contain any of Federation Entity properties defined below 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; 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; 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; 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; 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; 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; 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; it MUST NOT contain a fragment component. All Federation Entities MAY publish a federation_historical_keys_endpoint.¶

endpoint_auth_signing_alg_values_supported

OPTIONAL. JSON array containing a list of the supported JWS [RFC7515] algorithms (alg values) for signing the JWT [RFC7519] used for private_key_jwt when authenticating to federation endpoints, as described in Section 8.8. No default algorithms are implied if this entry is omitted. Servers SHOULD support RS256. The value none MUST NOT be used.¶

Additional Federation Entity properties MAY be defined and used.¶

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 metadata for 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",
  "organization_uri": "https://amanita.caesarea.example.com"
}

5.2.1. Parameters 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, which are in the jwks Claim of the Entity Statement, and not within the metadata Claim. These parameters for JWK Sets MUST NOT be used in federation_entity Entity Type metadata.¶

signed_jwks_uri

OPTIONAL. URL referencing a signed JWT having the Entity's JWK Set document for that Entity Type as its payload. This URL MUST use the https scheme. The JWT MUST be signed using a Federation Entity Key. A successful response from the URL MUST use the HTTP status code 200 with the content type application/jwk-set+jwt. When both signing and encryption keys are present, a use (public key use) parameter value is REQUIRED for all keys in the referenced JWK Set to indicate each key's intended usage.¶

Signed JWK Set 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]. Signed JWK Set JWTs without a typ header parameter or with a different typ value MUST be rejected.¶

Signed JWK Set JWTs MUST include the kid (Key ID) header parameter with its value being the Key ID of the signing key used.¶

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 in the JWK Set, as specified in Section 5.1 of [RFC7517].¶

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, per [RFC7519].¶

exp

OPTIONAL. Number. This Claim identifies the time when the JWT is no longer valid. This is expressed as Seconds Since the Epoch, per [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
    }

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 present, 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. When both signing and encryption keys are present, a use (public key use) parameter value is REQUIRED for all keys in the JWK Set to indicate each key's intended usage. 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.2. Informational Metadata Parameters

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

display_name

OPTIONAL. A human-readable name of the Entity to be presented to the End-User.¶

description

OPTIONAL. A human-readable brief description of this Entity presentable to the End-User.¶

keywords

OPTIONAL. JSON array with one or more strings representing search keywords, tags, categories, or labels that apply to this Entity.¶

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

information_uri

OPTIONAL. URL for documentation of additional information about this Entity viewable by the End-User.¶

organization_uri

OPTIONAL. URL of a Web page for the organization owning this Entity.¶

These metadata parameters MAY be present in the Entity's metadata for any Entity Types that it uses.¶

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 metadata policies on an equal basis, provided their contributions result in a combined metadata policy that is logically sound. For instance, any Intermediate can further restrict the metadata of its Subordinates relative to what its Superiors specified. An Intermediate that introduces a conflict among the metadata policies causes the Trust Chain to be deemed invalid.¶

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.1.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, as defined in the specifications for each operator, can be included together here.¶

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"]
    }
  }
}

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 is not supported, the operator MUST produce a policy error.¶

• MUST declare what other operators it may be combined with, which applies to both individual as well as merged metadata parameter policies, as described in Section 6.1.2 and Section 6.1.4. A combination may be unconditional, or conditional, requiring the configured values of the two operators to meet certain criteria. Combinations that are not allowed MUST produce 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. The order of the result of such an operator value merge is not defined. 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.¶

Note that metadata parameters and policies that conform to the JSON grammar but do not represent interoperable uses of JSON, as per Sections 4 and 8 of [RFC8259], can cause unpredictable behaviors.¶

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

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"
    }
  }
}

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"
    ]
  }
}

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"
    ]
  }
}

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's Resolved 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"
  ]
}

6.2.1. Max Path Length Constraint

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 metadata 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.¶

To apply the allowed_entity_types constraint during Trust Chain Resolution all Entity Types that are not listed in the allowed_entity_types constraint MUST be removed from the metadata Claim in the subject's Entity Configuration. The federation_entity Entity Type MUST NOT be removed. This MUST be done before applying Metadata Policies but after applying Metadata from a direct superior's Subordinate Statement.¶

7.2.1. Trust Mark Delegation JWT

A Trust Mark Delegation JWT is a signed JWT issued by a Trust Mark Owner that identifies a legitimate delegated issuer of Trust Marks with a particular identifier.¶

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]. Trust Mark delegation JWTs without a typ header parameter or with a different typ value MUST be rejected. 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.¶

trust_mark_type

REQUIRED. String. The identifier for the type of the Trust Mark.¶

iat

REQUIRED. Number. Time when this delegation was issued. This is expressed as Seconds Since the Epoch, per [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.¶

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.2.2. Validating a Trust Mark Delegation

Validating a Trust Mark Delegation means validating a Trust Mark Delegation instance represented by a specific signed JWT.¶

Henceforth, "delegation" is used as a shorthand for a Trust Mark Delegation JWT. The Trust Anchor referenced below is a Trust Anchor that has been successfully used when establishing trust in the Trust Mark Issuer.¶

To validate a delegation, the following validation steps MUST be performed. Please note that if any of these validation checks fail, the entire validation process fails and the delegation is considered invalid.¶

1. The delegation MUST be a signed JWT¶

2. The delegation MUST have a typ header with the value trust-mark-delegation+jwt¶

3. The delegation MUST have an alg (algorithm) header parameter with a value that is an acceptable JWS signing algorithm; it MUST NOT be none¶

4. The Entity Identifier of the Trust Mark Issuer MUST match the value of sub in the delegation¶

5. The Entity Identifier of the Trust Mark Owner MUST match the value of iss in the delegation.¶

6. The current time MUST be after the time represented by the iat (issued at) Claim in the delegation (possibly allowing for some small leeway to account for clock skew).¶

7. The current time MUST be before the time represented by the exp (expiration) Claim in the delegation (possibly allowing for some small leeway to account for clock skew).¶

8. The value of the Claim trust_mark_type in the delegation MUST be the same as the value of the Claim trust_mark_type in the Trust Mark.¶

9. The delegation's signature MUST validate using one of the Trust Mark Owner's keys identified by the value of the header parameter kid. The Trust Mark Owner's keys can be found in the trust_mark_owners Claim in the Trust Anchor's Entity Configuration.¶

8.1.1. Fetch Subordinate 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 parameter, encoded in application/x-www-form-urlencoded format. The request is made to the fetch endpoint of the specified issuer.¶

sub

REQUIRED. The Entity Identifier of the subject for which the Subordinate Statement is being requested.¶

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?
sub=https%3A%2F%2Fopenid%2Esunet%2Ese HTTP/1.1
Host: edugain.org

8.1.2. Fetch Subordinate 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 an error 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 sub parameter, returning the not_found error code is RECOMMENDED. If the sub parameter references the Entity Identifier of the Issuing Entity, returning the invalid_request 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",
  "sub": "https://openid.sunet.se",
  "exp": 1568397247,
  "iat": 1568310847,
  "source_endpoint": "https://edugain.org/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"
        ]
      }
    }
  }
}

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

trust_mark_type

OPTIONAL. The value of this parameter is the identifier for the type of the Trust Mark. If the responder has issued Trust Marks with the specified Trust Mark type identifier, the list in the response is filtered to include only the Immediate Subordinates for which that Trust Mark type 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

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

An error 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"
]

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

trust_anchor

REQUIRED. The Trust Anchor that the resolve endpoint MUST use when resolving the metadata. The value is an Entity identifier.¶

The trust_anchor request parameter MAY occur multiple times, in which case, the resolver MAY return a successful resolve response using any of the Trust Anchor values provided.¶

entity_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.¶

The entity_type request parameter MAY occur multiple times, in which case, data for each Entity Type whose Entity Type Identifier is in an entity_type parameter value is 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&
entity_type=openid_provider&
trust_anchor=https%3A%2F%2Fswamid.se HTTP/1.1
Host: openid.sunet.se

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]. Resolve responses without a typ header parameter or with a different typ value MUST be rejected. 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 MUST return the Trust Chain from the subject to the Trust Anchor in its trust_chain parameter.¶

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 trust_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 party is authenticated as described in Section 8.8, in which case, the value MUST be the Entity Identifier of the requesting party and MUST NOT include any other values.¶

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, per [RFC7519].¶

exp

REQUIRED. Number. Time when this resolution is no longer valid. This is expressed as Seconds Since the Epoch, per [RFC7519]. It MUST be the minimum of the exp value of the Trust Chain from which the resolve response was derived, as well as any Trust Mark included in the response.¶

metadata

REQUIRED. JSON object containing the subject's Resolved Metadata, according to the requested type and expressed in the metadata format defined in Section 3.1.1.¶

trust_chain

REQUIRED. Array containing the sequence of Entity Statements that compose the Trust Chain, starting with the subject and ending with the selected Trust Anchor.¶

trust_marks

OPTIONAL. Array of objects, each representing a Trust Mark, as defined in Section 3.1.2. Only valid Trust Marks that have been issued by Trust Mark issuers trusted by the Trust Anchor to issue such Trust Marks MAY appear in the resolver response.¶

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

An error 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": [
    {"trust_mark_type": "https://www.spid.gov.it/certification/op/",
     "trust_mark":
       "eyJ0eXAiOiJ0cnVzdC1tYXJrK2p3dCIsImFsZyI6IlJTMjU2Iiwia2lkIjoiOH
        hzdUtXaVZmd1NnSG9mMVRlNE9VZGN5NHE3ZEpyS2ZGUmxPNXhoSElhMCJ9.
        eyJpc3MiOiJodHRwczovL3d3dy5hZ2lkLmdvdi5pdCIsInN1YiI6Imh0dHBzOi
        8vb3AuZXhhbXBsZS5pdC9zcGlkLyIsImlhdCI6MTU3OTYyMTE2MCwidHJ1c3Rf
        bWFya190eXBlIjoiaHR0cHM6Ly93d3cuc3BpZC5nb3YuaXQvY2VydGlmaWNhdG
        lvbi9vcC8iLCJsb2dvX3VyaSI6Imh0dHBzOi8vd3d3LmFnaWQuZ292Lml0L3Ro
        ZW1lcy9jdXN0b20vYWdpZC9sb2dvLnN2ZyIsInJlZiI6Imh0dHBzOi8vZG9jcy
        5pdGFsaWEuaXQvaXRhbGlhL3NwaWQvc3BpZC1yZWdvbGUtdGVjbmljaGUtb2lk
        Yy9pdC9zdGFiaWxlL2luZGV4Lmh0bWwifQ.
        xyz-PDQ_..."
    }
  ],
  "trust_chain" : [
    "eyJhbGciOiJSUzI1NiIsImtpZCI6Ims1NEhRdERpYnlHY3M5WldWTWZ2aUhm ...",
    "eyJhbGciOiJSUzI1NiIsImtpZCI6IkJYdmZybG5oQU11SFIwN2FqVW1BY0JS ...",
    "eyJhbGciOiJSUzI1NiIsImtpZCI6IkJYdmZybG5oQU11SFIwN2FqVW1BY0JS ..."
  ]
}

8.3.3. Trust Considerations

The basic assumption of this specification is that an Entity should have direct trust in no party 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.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 parameter, encoded in application/x-www-form-urlencoded format.¶

trust_mark

REQUIRED. The Trust Mark to be validated.¶

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:¶

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

trust_mark=eyJ0eXAiOiJ0cnVzdC1tYXJrK2p3dCIsImFsZyI6 ...

8.4.2. Trust Mark Status Response

A successful response MUST use the HTTP status code 200 with the content type application/trust-mark-status-response+jwt, containing a signed JWT that is a Trust Mark Status Response.¶

The Trust Mark Status Response is a signed JWT that is explicitly typed by setting the typ header parameter to trust-mark-status-response+jwt to prevent cross-JWT confusion, per Section 3.11 of [RFC8725]. Trust Mark Status Responses without a typ header parameter or with a different typ value MUST be rejected. It is signed with a Federation Entity Key.¶

The Trust Mark Status Response JWT MUST include the kid (Key ID) header parameter with its value being the Key ID of the signing key used.¶

The JWT Claims Set of the Trust Mark Status JWT is a JSON object containing the following Claims:¶

iss

REQUIRED. String. Entity Identifier of the issuer of the Trust Mark Status JWT.¶

iat

REQUIRED. Number. Time when this Trust Mark Status JWT was issued. This is expressed as Seconds Since the Epoch, per [RFC7519].¶

trust_mark

REQUIRED. String. The Trust Mark JWT that this status response is about.¶

status

REQUIRED. Case-sensitive string value indicating the status of the Trust Mark. Values defined by this specification are:¶

active

The Trust Mark is active¶

expired

The Trust Mark has expired¶

revoked

The Trust Mark was revoked¶

invalid

Signature validation failed or another error was detected¶

Additional status values MAY be defined and used in addition to those above.¶

Additional Trust Mark Status JWT Claims MAY be defined and used in addition to those listed above.¶

The following is a non-normative example of the JWT Claims Set for a response with the status active:¶

{
  "iss": "https://www.agid.gov.it",
  "trust_mark": "eyJ0eXAiOiJ0cnVzdC1tYXJrK2p3dCIsImFsZyI6IlJTMjU2Iiwia2
    lkIjoia29zR20yd3VaaDlER21OeEF0a3VPNDBwUGpwTDMtakNmMU4tcVBPLVllVSJ9.
    eyJpc3MiOiJodHRwczovL3d3dy5hZ2lkLmdvdi5pdCIsInN1YiI6Imh0dHBzOi8
    vcnAuZXhhbXBsZS5pdC9zcGlkIiwiaWF0IjoxNTc5NjIxMTYwLCJ0cnVzdF9tYX
    JrX3R5cGUiOiJodHRwczovL3d3dy5zcGlkLmdvdi5pdC9jZXJ0aWZpY2F0aW9uL
    3JwIiwibG9nb191cmkiOiJodHRwczovL3d3dy5hZ2lkLmdvdi5pdC90aGVtZXMv
    Y3VzdG9tL2FnaWQvbG9nby5zdmciLCJyZWYiOiJodHRwczovL2RvY3MuaXRhbGl
    hLml0L2RvY3Mvc3BpZC1jaWUtb2lkYy1kb2NzL2l0L3ZlcnNpb25lLWNvcnJlbn
    RlLyJ9.
    L_pSh1InEiFAcs3E-1HBM7fNZYwF5ru3UGA_8yc80dGS3sszfA_sbj4AoW_zAJW
    QBdZpjxnHBBmybYXFrfZBcqxcedsrvUYrmbt1nPYxbUE54fRRoZK-sJmVqh1GzS
    an5nOmkxuAtMinU8k_-aWnPWj83sYe2AzT2mMgkXiz8zhda3jZm8hoxZ4jR6B0Y
    AvbMlq2pPWO5OWKdZhiFRMSprwh0GYluQkK0j1aLNMGXD3keMJd2zEoWX9D7w2f
    XShAA48W3cNhuXyBVnCoum1K4IWK3s_fx4nIkp6W-V4jCBOpxp7Yo8LZ30o_xpE
    OzGTIECGWVR86azOAlwVC8XSiAA",
  "iat": 1759897995,
  "status": "active"
}

The following is a non-normative example of the JWT Claims Set for a response with the status revoked:¶

{
  "iss": "https://www.agid.gov.it",
  "trust_mark": "eyJ0eXAiOiJ0cnVzdC1tYXJrK2p3dCIsImFsZyI6IlJTMjU2Iiwia2
    lkIjoia29zR20yd3VaaDlER21OeEF0a3VPNDBwUGpwTDMtakNmMU4tcVBPLVllVSJ9.
    eyJpc3MiOiJodHRwczovL3d3dy5hZ2lkLmdvdi5pdCIsInN1YiI6Imh0dHBzOi8
    vcnAuZXhhbXBsZS5pdC9zcGlkIiwiaWF0IjoxNTc5NjIxMTYwLCJ0cnVzdF9tYX
    JrX3R5cGUiOiJodHRwczovL3d3dy5zcGlkLmdvdi5pdC9jZXJ0aWZpY2F0aW9uL
    3JwIiwibG9nb191cmkiOiJodHRwczovL3d3dy5hZ2lkLmdvdi5pdC90aGVtZXMv
    Y3VzdG9tL2FnaWQvbG9nby5zdmciLCJyZWYiOiJodHRwczovL2RvY3MuaXRhbGl
    hLml0L2RvY3Mvc3BpZC1jaWUtb2lkYy1kb2NzL2l0L3ZlcnNpb25lLWNvcnJlbn
    RlLyJ9.
    L_pSh1InEiFAcs3E-1HBM7fNZYwF5ru3UGA_8yc80dGS3sszfA_sbj4AoW_zAJW
    QBdZpjxnHBBmybYXFrfZBcqxcedsrvUYrmbt1nPYxbUE54fRRoZK-sJmVqh1GzS
    an5nOmkxuAtMinU8k_-aWnPWj83sYe2AzT2mMgkXiz8zhda3jZm8hoxZ4jR6B0Y
    AvbMlq2pPWO5OWKdZhiFRMSprwh0GYluQkK0j1aLNMGXD3keMJd2zEoWX9D7w2f
    XShAA48W3cNhuXyBVnCoum1K4IWK3s_fx4nIkp6W-V4jCBOpxp7Yo8LZ30o_xpE
    OzGTIECGWVR86azOAlwVC8XSiAA",
  "iat": 1759898057,
  "status": "revoked"
}

An error response to a Trust Mark Status request is as defined in Section 8.9.¶

If the Trust Mark Issuer receives a request about the status of an unknown Trust Mark, something it did not issue or is not aware of, it MUST respond with an HTTP status code 404 (Not found).¶

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_type

REQUIRED. Identifier for the type of the Trust Mark. If the responder has issued Trust Marks with the specified Trust Mark type identifier, the list in the response is filtered to include only the Entities for which that Trust Mark type 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_type=https%3A%2F%2Ffederation.example.org%2Fopenid_relying_party%2Fprivate%2Funder-age HTTP/1.1
Host: trust-mark-issuer.example.org

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

An error 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"
]

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 parameters, encoded in application/x-www-form-urlencoded format.¶

trust_mark_type

REQUIRED. Identifier for the type of the Trust Mark.¶

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 type identifier and subject:¶

GET /trust_mark?trust_mark_type=https%3A%2F%2Fwww.spid.gov.it%2Fcertification%2Frp&sub=https%3A%2F%2Frp.example.it%2Fspid HTTP/1.1
Host: tuber.cert.example.org

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 does not have the specified Trust Mark, the response is an error response 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
Content-Type: application/trust-mark+jwt

eyJ0eXAiOiJ0cnVzdC1tYXJrK2p3dCIsImFsZyI6IlJTMjU2Iiwia2lkIjoia29zR20yd3Va
aDlER21OeEF0a3VPNDBwUGpwTDMtakNmMU4tcVBPLVllVSJ9.
eyJpc3MiOiJodHRwczovL3d3dy5hZ2lkLmdvdi5pdCIsInN1YiI6Imh0dHBzOi8vcnAuZXhh
bXBsZS5pdC9zcGlkIiwiaWF0IjoxNTc5NjIxMTYwLCJ0cnVzdF9tYXJrX3R5cGUiOiJodHRw
czovL3d3dy5zcGlkLmdvdi5pdC9jZXJ0aWZpY2F0aW9uL3JwIiwibG9nb191cmkiOiJodHRw
czovL3d3dy5hZ2lkLmdvdi5pdC90aGVtZXMvY3VzdG9tL2FnaWQvbG9nby5zdmciLCJyZWYi
OiJodHRwczovL2RvY3MuaXRhbGlhLml0L2RvY3Mvc3BpZC1jaWUtb2lkYy1kb2NzL2l0L3Zl
cnNpb25lLWNvcnJlbnRlLyJ9.
L_pSh1InEiFAcs3E-1HBM7fNZYwF5ru3UGA_8yc80dGS3sszfA_sbj4AoW_zAJWQBdZpjxnH
BBmybYXFrfZBcqxcedsrvUYrmbt1nPYxbUE54fRRoZK-sJmVqh1GzSan5nOmkxuAtMinU8k_
-aWnPWj83sYe2AzT2mMgkXiz8zhda3jZm8hoxZ4jR6B0YAvbMlq2pPWO5OWKdZhiFRMSprwh
0GYluQkK0j1aLNMGXD3keMJd2zEoWX9D7w2fXShAA48W3cNhuXyBVnCoum1K4IWK3s_fx4nI
kp6W-V4jCBOpxp7Yo8LZ30o_xpEOzGTIECGWVR86azOAlwVC8XSiAA

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

8.7.2. Federation Historical Keys Response

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

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 without a typ header parameter or with a different typ value MUST be rejected.¶

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, per [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, per [RFC7519].¶

exp

REQUIRED. Number. Expiration time for the key. This is expressed as Seconds Since the Epoch, per [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",
                }
            }
        ]
}

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

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 also be 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.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 for each endpoint. These largely parallel the token_endpoint_auth_methods_supported metadata value 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 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 for these endpoints, just as token_endpoint_auth_methods_supported does for the Token Endpoint. 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"]

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

The endpoint_auth_signing_alg_values_supported metadata parameter lists supported client authentication signing algorithms supported for these endpoints, just as token_endpoint_auth_signing_alg_values_supported does for the Token Endpoint.¶

17.2.1. Bottom-Up Trust Chain Resolution

Bottom-up Trust Chain resolution is the process described in Section 10, also known as Federation Entity Discovery (see the definition in the Terminology section). This process starts with a known Entity Identifier and builds a Trust Chain by traversing up the federation hierarchy until reaching a Trust Anchor. This pattern is not discovery in the sense of finding unknown entities, but rather trust resolution for a known entity.¶

This pattern is used when an entity needs to verify the trustworthiness of another entity whose Entity Identifier is already known. This is typically used for:¶

• OpenID Providers verifying Relying Parties during authentication requests,¶

• Resource servers verifying Client trustworthiness,¶

• Any Entity validating incoming requests from known parties, and¶

• Dynamic trust establishment in federated environments.¶

The bottom-up Trust Chain resolution process follows these steps, as described in Section 10:¶

1. Start with the subject entity's Entity Configuration (provided or fetched using the process defined in Section 9).¶

2. Use authority_hints to identify immediate superior entities.¶

3. Fetch Entity Configuration for each Superior Entity.¶

4. Use Fetch Endpoints (as defined in Section 8.1.1) to obtain Subordinate Statements about the subject entity.¶

5. Recursively traverse up the hierarchy until reaching a Trust Anchor.¶

6. Build and validate the complete Trust Chain.¶

7. Apply federation policies to derive Resolved Metadata.¶

17.2.2. Top-Down Discovery

Top-down discovery is the process of finding entities that are part of a federation by starting from a known Trust Anchor and traversing down the federation hierarchy. This pattern is used when the goal is to discover available entities, particularly entities of specific Entity Types, without necessarily knowing their Entity Identifiers in advance.¶

This pattern is particularly useful for:¶

• Service discovery by Relying Parties looking for OpenID Providers,¶

• Resource discovery by Clients looking for specific service types,¶

• Federation browsing and exploration, and¶

• Building provider directories and catalogs (e.g., WAYF services, Seamless Access).¶

The top-down discovery process follows these steps:¶

1. Start with a known Trust Anchor that the discovering entity trusts.¶

2. Use the list endpoint (as defined in Section 8.2) to discover Immediate Subordinate entities.¶

3. Filter by entity_type parameter to find protocol-specific providers (e.g., openid_provider).¶

4. For Intermediate entities, recursively traverse their Subordinates.¶

5. Collect Entity Identifiers and optionally Entity Configurations for discovered entities.¶

Note that top-down discovery may or may not include Trust Chain resolution, depending on the use case. For example, when building a directory of OpenID Providers for user selection at login time, the discovery service may collect entity identifiers and basic metadata without resolving Trust Chains for all discovered entities. However, if the discovery service needs to verify that entities are properly registered in the federation before including them in the directory, it may choose to perform Trust Chain resolution as part of the discovery process.¶

17.2.3. Single Point of Trust Resolution

Single point of trust resolution delegates the entire Trust Chain resolution process to a trusted resolver implementing the Resolve Endpoint defined in Section 8.3. This pattern allows entities to offload the complexity of Trust Chain resolution to a specialized service.¶

This pattern is useful for:¶

• Entities that want to offload Trust Chain resolution complexity,¶

• Centralized trust evaluation services,¶

• Performance optimization by caching Resolved Metadata, and¶

• Simplified integration for lightweight clients.¶

Note that this pattern requires the Entity Identifier of the subject entity to be known in advance. It does not provide discovery functionality in the sense of finding unknown entities within a federation.¶

The single point of trust resolution process follows these steps:¶

1. Identify a trusted resolver with a Resolve Endpoint.¶

2. Submit the subject Entity Identifier and Trust Anchor to the resolver.¶

3. The resolver performs complete Trust Chain resolution internally (following the bottom-up pattern).¶

4. The resolver returns Resolved Metadata and Trust Marks.¶

5. Optionally verify the resolver's own Trust Chain.¶

6. Use Resolved Metadata for protocol operations.¶