OpenID Federation 1.0 - draft 40

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

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

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. Additional values MAY be defined and used, without restriction by this specification.¶

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

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

5.1.3. OpenID Connect OpenID Provider

The Entity Type Identifier is openid_provider.¶

All parameters defined in Section 3 of OpenID Connect Discovery 1.0 [OpenID.Discovery] and Section 5.2 are applicable, as well as additional parameters registered in the IANA "OAuth Authorization Server Metadata" registry [IANA.OAuth.Parameters].¶

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

In addition, the following OP metadata parameters are defined:¶

client_registration_types_supported

REQUIRED. Array specifying the federation types supported. Federation-type values defined by this specification are automatic and explicit. Additional values MAY be defined and used, without restriction by this specification.¶

federation_registration_endpoint

OPTIONAL. URL of the OP's federation-specific Dynamic Client Registration Endpoint. If the OP supports Explicit Client Registration Endpoint this URL MUST use the https scheme and MAY contain port, path, and query parameter components; it MUST NOT contain a fragment component. If the OP supports Explicit Client Registration as described in Section 12.2, then this claim is REQUIRED.¶

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

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

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

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

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

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

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

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

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

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

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

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

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

The type request parameter MAY occur multiple times, in which case, data for each Entity Type whose Entity Type Identifier is a 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&
type=openid_provider&
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 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. 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.¶

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

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.1. Trust Mark Status Request

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

sub

REQUIRED. The Entity Identifier of the Entity to which the Trust Mark was issued.¶

trust_mark_id

REQUIRED. Identifier of the Trust Mark.¶

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

GET /federation_trust_mark_status_endpoint?
sub=https%3A%2F%2Fopenid.sunet.se%2FRP&
trust_mark_id=https%3A%2F%2Frefeds.org%2Fsirtfi HTTP/1.1
Host: op.example.org

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
}

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

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

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_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

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

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

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

12.1.1. Authentication Request

The Authentication Request is performed by passing a signed 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].¶

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

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

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=eyJhbGciOiJSUzI1NiIsImtpZCI6Ik5fX0Q5OEl2QjhOYWUta3dBNm5yT3Q
        taXBUaGpIa0R4MzduaWNETUgzTjQifQ.
        eyJhdWQiOiJodHRwczovL29wLmV4YW1wbGUub3JnIiwiY2xpZW50X2lkIjoiaHR0
        cHM6Ly9ycC5leGFtcGxlLmNvbSIsImV4cCI6MTU4OTY5OTE2MiwiaWF0IjoxNTg5
        Njk5MTAyLCJpc3MiOiJodHRwczovL3JwLmV4YW1wbGUuY29tIiwianRpIjoiNGQz
        ZWMwZjgxZjEzNGVlOWE5N2UwNDQ5YmU2ZDMyYmUiLCJub25jZSI6IjRMWDBtRk14
        ZEJqa0dtdHg3YThXSU9uQiIsInJlZGlyZWN0X3VyaSI6Imh0dHBzOi8vcnAuZXhh
        bXBsZS5jb20vYXV0aHpfY2IiLCJyZXNwb25zZV90eXBlIjoiY29kZSIsInNjb3Bl
        Ijoib3BlbmlkIHByb2ZpbGUgZW1haWwgYWRkcmVzcyBwaG9uZSIsInN0YXRlIjoi
        WW1YOFBNOUk3V2JOb01ubmllS0tCaXB0Vlcwc1AyT1oiLCJ0cnVzdF9jaGFpbiI6
        WyJleUpoYkdjaU9pSlNVekkxTmlJc0ltdHBaQ0k2SW1zMU5FaFJkRVJwWW5sSFkz
        TTVXbGRXVFdaMmFVaG0gLi4uIiwiZXlKaGJHY2lPaUpTVXpJMU5pSXNJbXRwWkNJ
        NklrSllkbVp5Ykc1b1FVMTFTRkl3TjJGcVZXMUJZMEpTIC4uLiIsImV5SmhiR2Np
        T2lKU1V6STFOaUlzSW10cFpDSTZJa0pZZG1aeWJHNW9RVTExU0ZJd04yRnFWVzFC
        WTBKUyAuLi4iXX0.
        Rv0isfuku0FcRFintgxgKDk7EnhFkpQRg3Tm6N6fCHAHEKFxVVdjy4
        9JboJtxKcQVZKN9TKn3lEYM1wtF1e9PQrNt4HZ21ICfnzxXuNx1F5SY1GXCU2n2y
        FVKtz3N0YkAFbTStzy-sPRTXB0stLBJH74RoPiLs2c6dDvrwEv__GA7oGkg2gWt6
        VDvnfDpnvFi3ZEUR1J8MOeW_VFsayrT9sNjyjsz62Po4LzvQKQMKxq0dNwPNYuuS
        fUmb-YvmFguxDb3weYl8WS-
        48EIkP1h4b_KGU9x9n7a1fUOHrS02ATQZmaL8jUil7yLJqx5MiCsPr4pCAXV0doA
        4pwhs_FIw HTTP/1.1

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

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

12.1.2. Successful Authentication Response

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

12.1.3. Authentication Error Response

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

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

If the OP fails to establish trust with the RP, it MUST treat the redirection URI as invalid and not perform redirection. This means that the two error codes defined below, both of which are about reasons trust failed to be established, SHOULD only be returned in Pushed Authorization Request [RFC9126] error responses, and not to the Client's redirection URI.¶

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

missing_trust_anchor

No trusted Trust Anchor could be found.¶

trust_chain_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=consent_required
    &error_description=
      Consent%20by%20the%20End-User%20required
    &state=af0ifjsldkj

12.1.4. Possible Other Uses of Automatic Registration

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

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. This claim is only used in Explicit Registration requests, since it is not a general Entity Statement claim.¶

authority_hints

REQUIRED.¶

metadata

REQUIRED. It MUST contain the RP metadata under the openid_relying_party Entity Type Identifier.¶

crit

OPTIONAL.¶

trust_marks

OPTIONAL.¶

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

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

12.2.2. Processing Explicit Client Registration Request by OP

The OP processes the request as follows:¶

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

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

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

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

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

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

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

12.2.3. Explicit Client Registration Response

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

The OP MUST set the trust_anchor_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.5.¶

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

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

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

The following Entity Statement claims are used in Explicit Registration responses:¶

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 used in Explicit Registration responses but 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.4. Processing Explicit Client Registration Response by RP

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

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

2. The RP MUST verify that the aud (audience) claim value is its Entity Identifier.¶

3. The RP MUST verify that the trust_anchor_id represents one of its own Trust Anchors.¶

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

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

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

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

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

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

17.3.1. Registry Contents

• Name: missing_trust_anchor¶

• Usage Location: authorization endpoint¶

• Protocol Extension: OpenID Federation¶

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

• Reference: Section 12.1.3 of this specification¶

• Name: trust_chain_validation_failed¶

• Usage Location: authorization endpoint¶

• Protocol Extension: OpenID Federation¶

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

• Reference: Section 12.1.3 of this specification¶

17.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 16 of this specification¶

• Interoperability considerations: n/a¶

• Published specification: Section 15.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+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 16 of this specification¶

• Interoperability considerations: n/a¶

• Published specification: Section 15.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: 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 16 of this specification¶

• Interoperability considerations: n/a¶

• Published specification: Section 15.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-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 16 of this specification¶

• Interoperability considerations: n/a¶

• Published specification: Section 15.4 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 16 of this specification¶

• Interoperability considerations: n/a¶

• Published specification: Section 15.5 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 16 of this specification¶

• Interoperability considerations: n/a¶

• Published specification: Section 15.6 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¶

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

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

17.7.1. Registry Contents

• Claim Name: jwks¶

• Claim Description: JSON Web Key Set¶

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

• Claim Description: Metadata object¶

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

• Claim Description: Constraints object¶

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

• Claim Description: Critical Claim¶

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

• Specification Document(s): Section 13.4 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.5 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.6 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.7 of this specification¶

• Claim Name: logo_uri¶

• Claim Description: URI referencing a logo¶

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

• Specification Document(s): Section 13.8 of this specification¶

• Claim Name: authority_hints¶

• Claim Description: Authority Hints¶

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

• Specification Document(s): Section 3 of this specification¶

• Claim Name: metadata_policy¶

• Claim Description: Metadata Policy object¶

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

• Specification Document(s): Section 3 of this specification¶

• Claim Name: metadata_policy_crit¶

• Claim Description: Critical Metadata Policy Operators¶

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

• Specification Document(s): Section 3 of this specification¶

• Claim Name: trust_marks¶

• Claim Description: Trust Marks¶

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

• Specification Document(s): Section 3 of this specification¶

• Claim Name: trust_mark_issuers¶

• Claim Description: Trust Mark Issuers¶

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

• Specification Document(s): Section 3 of this specification¶

• Claim Name: trust_mark_owners¶

• Claim Description: Trust Mark Owners¶

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

• Specification Document(s): Section 3 of this specification¶

• Claim Name: source_endpoint¶

• Claim Description: Source Endpoint URL¶

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

• Specification Document(s): Section 3 of this specification¶

• Claim Name: trust_chain¶

• Claim Description: Trust Chain¶

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

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

• Claim Name: keys¶

• Claim Description: Array of JWK values in a JWK Set¶

• 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 of this specification¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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