R. Hedberg, Ed.
independent
M. Jones
Microsoft
A. Solberg
Uninett
S. Gulliksson
Schibsted
J. Bradley
Yubico
November 7, 2019

OpenID Connect Federation 1.0 - draft 10
openid-connect-federation-1_0

Abstract

The OpenID Connect standard specifies how a Relying Party (RP) can discover metadata about an OpenID Provider (OP), and then register to obtain RP credentials. The discovery and registration process does not involve any mechanisms of dynamically establishing trust in the exchanged information, but instead rely on out-of-band trust establishment.

In an identity federation context, this is not sufficient. The participants of the federation must be able to trust information provided about other participants in the federation. OpenID Connect Federations specifies how trust can be dynamically obtained by resolving trust from a common trusted third party.

While this specification is primarily targeting OpenID Connect, it is designed to allow for re-use by other protocols and in other use cases.


Table of Contents

1. Introduction

This specification describes how two entities that would like to interact can dynamically fetch and resolve trust and metadata for a given protocol through the use of third-party trust anchor. A trust anchor is an entity whose main purpose is to issue statements about entities, such as OpenID Connect Relying Parties, OpenID Providers, and participating organizations. An identity federation can be realized using this specification using one or more levels of trust issuers. This specification does not mandate a specific way or restrict how a federation may be built. Instead, the specification provides the basic technical trust infrastructure building blocks needed to build a dynamic and distributed trust network such as a federation.

Note that a company, as with any real-world organization, may be represented by more than one entity in a federation.

OpenID Connect Federation trust chains rely on cryptographically signed JSON Web Token (JWT) documents, and the trust chain does not at all rely on TLS [RFC8446] in order to establish trust.

1.1. Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

1.2. Terminology

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

This specification also defines the following terms:

Entity

Something that has a separate and distinct existence and that can be identified in a context. All entities in an OpenID Connect federation MUST have a globally unique identifier.
Entity statement

An entity statement is issued by an entity, which pertains to a subject entity and leaf entities. An entity statement is always a signed JWT.
Intermediate entity

An entity that issues an entity statement that appears somewhere in between those issued by the trust anchor and the leaf entity in a trust chain.
Leaf Entity

An entity defined by a certain protocol, e.g., OpenID Connect Relying Party or Provider.
Trust Anchor

An entity that represents a trusted third party.
Trust Chain

A sequence of entity statements that represents a chain starting at a leaf entity and ending in a trust anchor.

2. Components

2.1. Entity Statement

An entity statement is issued by an entity and concerns a subject entity and leaf entities in a federation. An entity statement is always a signed JWT. All entities in a federation SHOULD be prepared to publish an entity statement about themselves. If they are not able to do so themselves someone else MUST do it for them.

An entity statement is composed of the following claims:

iss

REQUIRED. The entity identifier of the issuer of the statement. If the iss and the sub are identical, the issuer is making a statement about itself.
sub

REQUIRED. The entity identifier of the subject
iat

REQUIRED. The time the statement was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See RFC 3339 for details regarding date/times in general and UTC in particular.
exp

REQUIRED. Expiration time on or after which the statement MUST NOT be accepted for processing. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
jwks

REQUIRED. A JSON Web Key Set (JWKS) representing the public part of the subject entity's signing keys. The corresponding private key is used by leaf entities to sign entity statements about themselves, and intermediate entities to sign statements about other entities. The keys that can be found here are primarily intended to sign entity statements and should not be used in other protocols.
aud

OPTIONAL. The entity statement may be specifically created for an entity. The entity identifier for that entity MUST appear in this claim.
authority_hints

OPTIONAL. Array of strings representing the entity identifiers of intermediate entities or trust anchors that may issue an entity statement about the issuer entity. For all entities except for trust anchors that do not have any superiors this is REQUIRED and MUST NOT be the empty list []. This claim MUST be absent in an entity statement issued by a trust anchor with no superiors.
metadata

OPTIONAL. JSON object including protocol specific metadata claims that represent the entity's metadata. Each key of the JSON object represents a metadata type identifier, and each value MUST be a JSON object representing the metadata according to the metadata schema of that metadata type. An entity statement may contain multiple metadata statements, but only one for each metadata type. If the iss of an entity statement points to the same entity as the sub then the entity statement MUST contain a metadata claim.
metadata_policy

OPTIONAL. JSON object that describes a metadata policy. Each key of the JSON object represents a metadata type identifier, and each value MUST be a JSON object representing the metadata policy according to the metadata schema of that metadata type. An entity statement may contain multiple metadata policy statements, but only one for each metadata type. Only non-leaf entities MAY contain a metadata_policy claim. Leaf entities MUST NOT contain a metadata_policy claim.
constraints

OPTIONAL. JSON object that describes a set of trust chain constraints. More about this in Section 7.3
crit

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

OPTIONAL. The policy_language_crit (critical) entity statement claim indicates that extensions to the policy language defined by this specification are being used that MUST be understood and processed. It is used in the same way that crit is used for extension JSON Web Signature (JWS) header parameters that MUST be understood and processed. Its value is an array listing the policy language extensions present in the policy language statements that use those extensions. If any of the listed extension policy language extensions are not understood and supported by the recipient, then the entity statement is invalid. Producers MUST NOT include policy language names defined by this specification or names that do not occur in policy language statements in the entity statement in the policy_language_crit list. Producers MUST NOT use the empty list [] as the policy_language_crit value.

The entity statement is signed using the private key of the issuer entity, in the form of a JSON Web Signature (JWS).

The following is a non-normative example of an entity statement before serialization and adding a signature. The example contains a critical extension jti (JWT ID) to the entity statement and one critical extension to the policy language regexp (Regular expression).

{
  "iss": "https://feide.no",
  "sub": "https://ntnu.no",
  "iat": 1516239022,
  "exp": 1516298022,
  "crit": ["jti"],
  "jti": "7l2lncFdY6SlhNia",
  "policy_language_crit": ["regexp"],
  "metadata_policy": {
    "openid_provider": {
      "issuer": {"value": "https://ntnu.no"},
      "organization_name": {"value": "NTNU"},
      "id_token_signing_alg_values_supported":
        {"subset_of": ["RS256", "RS384", "RS512"]},
      "op_policy_uri": {
        "regexp": "^https:\/\/[\w-]+\.example\.com\/[\w-]+\.html"}
    },
    "openid_relying_party": {
      "organization_name": {"value": "NTNU"},
      "grant_types_supported": {
        "subset_of": ["authorization_code", "implicit"]},
      "scopes": {
        "subset_of": ["openid", "profile", "email", "phone"]}
    }
  },
  "constraints": {
    "max_path_length": 2
  }
  "jwks": {
    "keys": [
      {
        "alg": "RS256",
        "e": "AQAB",
        "ext": true,
        "key_ops": ["verify"],
        "kid": "key1",
        "kty": "RSA",
        "n": "pnXBOusEANuug6ewezb9J_...",
        "use": "sig"
      }
    ]
  },
  "authority_hints": [
    "https://edugain.org/federation"
  ]
}

2.2. Trust Chain

In an OpenID Connect Identity Federation, entities that together build a trust chain can be categorized as:

Trust anchor

An entity that represents a trusted third party
Leaf

In an OpenID Connect Identity Federation, an RP or an OP
Intermediate

Neither a leaf nor a trust anchor

A trust chain begins with a leaf entity's self-signed entity statement, has zero or more entity statements issued by intermediates about subordinates, and ends with an entity statement issued by the trust anchor about the top-most intermediate (if there are intermediates) or the leaf entity (if there are no intermediates).

A simple example: If we have an RP that belongs to organization A that is a member of federation F, the trust chain for such a setup will contain the following entity statements:

  1. A self-signed entity statement about the RP published by the RP
  2. An entity statement about the RP published by Organization A
  3. An entity statement about Organization A published by Federation F

A trust chain MUST always be possible to order such that: If we name the entity statements ES[0] (the leaf entity's self-signed entity statement) to ES[i] (an entity statement issued by the trust anchor), i>0 then:

The signing key that MUST be used to verify ES[i] is distributed from the trust anchors to the any entity that needs to verify a trust chain in some secure out-of-band way not described in this document.

3. Metadata

This specification does allow new metadata types to be defined, to support use cases outside OpenID Connect federations. The metadata type identifier will uniquely identify which metadata specification to utilize.

The metadata document MUST be a JSON document. Beyond that there is no restriction.

Metadata used in federations typically re-uses existing metadata standards. If needed, the metadata schema is extended with additional properties relevant in a federated context. For instance, for OpenID Connect Federations, this specification uses metadata values from OpenID Connect Discovery 1.0 and OpenID Connect Dynamic Client Registration 1.0 and adds additional values used for federations.

3.1. RP Metadata

The metadata type identifier is openid_relying_party.

All parameters defined in Section 2 of OpenID Connect Dynamic Client Registration 1.0 are allowed in a metadata statement.

To that list is added:

federation_type

REQUIRED. Array of strings specifying the federation types supported. Values defined by this specification are automatic and explicit.
organization_name

OPTIONAL. A human readable name representing the organization owning the RP.

3.2. OP Metadata

The metadata type identifier is openid_provider.

All parameters defined in Section 3 of OpenID Connect Discovery 1.0 are applicable.

In addition, the following parameters are defined by this specification:

federation_types_supported

REQUIRED. Array specifying the federation types supported. Federation type values defined by this specification are automatic and explicit.
organization_name

OPTIONAL. A human readable name representing the organization owning the OP. It is intended to be used in the user interface, being recognized by the end users that would be using the OP to authenticate.
federation_registration_endpoint

OPTIONAL. URL of the OP's Federation specific Dynamic Client Registration Endpoint. If the OP supports explicit client registration as described in Section 9.2, then this claim is REQUIRED.

3.3. OAuth Authorization Server

The metadata type identifier is oauth_authorization_server.

All parameters defined in Section 2 of RFC 8414 are applicable.

3.4. OAuth Client

The metadata type identifier is oauth_client.

All parameters defined in Section 2 of RFC 7591 are applicable.

3.5. OAuth Protected Resource

The metadata type identifier is oauth_resource. There is no standard that specifies what parameters that can occur in the metadata for this kind of entity. So for the time being, this can be regarded as a place holder.

3.6. Federation Entity

The metadata type identifier is federation_entity.

All entities participating in a federation are of this type.

The following properties are allowed:

federation_api_endpoint

OPTIONAL. The endpoint used for the Federation API described in Section 6. Intermediate entities and trust anchors MUST publish a federation_api_endpoint. Leaf entities MUST NOT.
trust_anchor_id

OPTIONAL. An OP MUST use this claim to tell the RP which trust anchor it chose to use when responding to an explicit client registration. The value of trust_anchor_id is the entity identifier of a trust anchor.
name

OPTIONAL. String. The human readable name describing the subject entity. This may be, for example, the name of an organization.
contacts

OPTIONAL. JSON array with one or more strings. Contact persons at the entity. These may contain names, e-mail addresses, descriptions, phone numbers, etc.
policy_uri

OPTIONAL. URL to documentation of conditions and policies relevant to this entity.
homepage_uri

OPTIONAL. URL to a generic home page representing this entity.

Example

"federation_entity": {
    "federation_api_endpoint":
        "https://example.com/federation_api_endpoint",
    "name": "The example cooperation",
    "homepage_uri": "https://www.example.com"
}

4. Applying Policy to Metadata

The metadata for a specific entity can be constructed by combining the metadata polices defined by the trust anchor and possible intermediates starting with the trust anchor and the applying this combined policy to the metadata information in a leaf entity's entity statement.

4.1. Policy Language

Policies are expressed using a JSON object.

The following keywords represent different actions/checks that MUST be applied to the metadata.

4.1.1. subset_of

The resulting value of the claim will be the intersection of the values specified here and the values of the claim. For instance, the claim policy:

  "response_types": {
    "subset_of": ["code", "code token", "code id_token"]}

if applied to a metadata statement with:

  "response_types": ["code", "code id_token token", "code id_token"]

will update the claim in the metadata statement to be:

  "response_types": ["code", "code id_token"]

4.1.2. one_of

The value of the claim MUST be one of the ones listed here. As an example, if the claim policy:

  "request_object_signing_alg": {
    "one_of": ["ES256", "ES384", "ES512"]}

is applied to the metadata statement

  "request_object_signing_alg": "ES384"

the resulting claim statement will be:

  "request_object_signing_alg": "ES384"

If an entity tries to register a value that is not in the one_of set of values, applying the policy MUST lead to a failure.

4.1.3. superset_of

The values of the claim MUST contain the ones listed here. We define superset the mathematical way, that is equality is included. As an example, if the claim policy:

 "request_object_signing_alg_values_supported": {
    "superset": ["ES256", "RS256"]}
                

is applied to the metadata statement

"request_object_signing_alg_values_supported": [
  "ES256", "ES384", "RS256", "RS512"]

the resulting claim statement will be:

"request_object_signing_alg_values_supported": [
  "ES256", "ES384", "RS256", "RS512"]
 

If an entity tries to register a set of values that are not a superset of the ones specified by superset_of, applying the policy MUST lead to a failure.

4.1.4. add

Adds the value or values specified to the list of values for the metadata statement claim. If the specified value is already present in the list, this operation has no effect. If the claim has no value then the claim is initialized with the specified value. As an example, if the claim policy:

  "contacts": {
    "add": "support@federation.example.com"}

is applied to the following claim in the metadata statement:

  "contacts": "support@org.example.com"

the end result will be the claim:

  "contacts": ["support@org.example.com",
               "support@federation.example.com"]

4.1.5. value

Disregarding what value the claim had, if any, the claims value will be set to what is specified here. As an example, if the claim policy:

  "require_auth_time": {
    "value": true}

is applied to a metadata statement with the claim

  "require_auth_time": false

then the metadata statement will afterwards contain:

  "require_auth_time": true

4.1.6. default

If no value is assigned to this claim, then the claim's value will be set to what is specified here. As an example, if the claim policy:

  "require_auth_time": {
    "default": true }

is applied to a metadata statement with the claim

  "require_auth_time": false

then the metadata statement will afterwards contain:

  "require_auth_time": false

If on the other hand, the metadata statement did not contain a require_auth_time claim then the following claim statement would be added to the metadata statement:

  "require_auth_time": true

4.1.7. essential

If 'true' then claim MUST have a value. essential can be combined with all the other types.

  "tos_uri": {
    "essential": true}

The upshot of applying this policy to a metadata statement is that the metadata statement MUST contain such a claim otherwise the metadata statement is incorrect.

4.2. Policy Type Combinations

An entity may use more then one policy type when expressing a policy for a claim. These are the policy types that can be combined in a metadata_policy statement:

essential

Can be combined with all the others. If essential is not present that is the same as stating essential=true.
default

Can be combined with one_of, subset_of and superset_of. If a default policy is combined with one_of, subset_of or superset_of and it is not a subset of the subset_of policy or the one_of policy or a superset of the superset_of policy then an error MUST be raised.
superset_of

Can be combined with subset_of. If subset_of and superset_of both appears in a metadata_policy statement subset_of MUST be a superset of superset_of.
subset_of

Can be combined with superset_of. If superset_of and subset_of both appears in a metadata_policy statement for a claim subset_of MUST be a superset of superset_of.
value

Can be combined with one_of, subset_of and superset_of. Here the order matters. If value appear in a superiors policy statement then the others MUST be ignored. If value are defined by the subordinate then it MUST be a subset of subset_of, superset of superset_of and one of one_of.

4.3. Combining Policies

If there is more than one metadata policy in a trust chain, then the policies MUST be combined before they are applied to the metadata statement.

Using the notation we have defined in Section 2.2 policies are combined starting with ES[i] and then adding the policies from ES[j] j=i-1,..,1 before applying the combined policy to the entity's metadata.

After having combined the policies, the policy for each claim MUST adhere to the rules defined in Section 4.2.

These are the policy types that can be combined when combining two policies:

subset_of

The result of combining two subset_of policies is the intersection of the values.
one_of

The result of combining two one_of policies is the intersection of the values.
superset_of

The result of combining two superset_of policies is the intersection of the values.
add

The result of combining two add policies is the union of the values.
value

The result of combining two value policies is NOT allowed unless the two values are equal.
default

The result of combining two default policies is NOT allowed unless the two values are equal.
essential

The result of combining two essential policies is True if any of the values are True otherwise it is False. Note that a missing essential specification is to be treated as an essential=true statement.

It should be noted that applying subset_of, superset_of or one_of to an empty value will result in an empty value.

4.3.1. Policy Combination Example

A federations policy for RPs:

{
    "scopes": {
        "subset_of": ["openid", "eduperson", "phone"],
        "superset_of": ["openid"],
        "default": ["openid", "eduperson"]},
    "id_token_signed_response_alg": {
        "one_of": ["ES256", "ES384", "ES512"]},
    "contacts": {
        "add": "helpdesk@federation.example.org"},
    "application_type": {"value": "web"}
}

An organization's policy for RPs:

{
    "scopes": {
        "subset_of": ["openid", "eduperson", "address"],
        "default": ["openid", "eduperson"]},
    "id_token_signed_response_alg": {
        "one_of": ["ES256", "ES384"],
        "default": "ES256"},
    "contacts": {
        "add": "helpdesk@org.example.org"}
}

The combined metadata policy then becomes:

{
    "scopes": {
        "subset_of": ["openid", "eduperson"],
        "superset_of": ["openid"],
        "default": ["openid", "eduperson"]},
    "id_token_signed_response_alg": {
        "one_of": ["ES256", "ES384"],
        "default": "ES256"},
    "contacts": {
        "add": ["helpdesk@federation.example.org",
                "helpdesk@org.example.org"]},
    "application_type": {
        "value": "web"}
}

4.4. Enforcing Policy

If applying policies to a metadata statement results in incorrect metadata, then such a metadata statement MUST be regarded as broken and MUST NOT be used.

4.5. Extending the Policy Language

There might be parties that want to extend the policy language defined here. If that happens then the rule is that if software compliant with this specification encounters a keyword it doesn't understand it MUST ignore it unless it is listed in a policy_language_crit list, as is done for JWS header parameters with the crit parameter. If the policy language extension keyword is listed in the policy_language_crit list and not understood, then the metadata MUST be rejected.

4.6. Policy Example

The following is a non-normative example of a set of policies being applied to an RP's metadata.

The RP's metadata:

{
  "contacts": ["rp_admins@cs.example.com"],
  "redirect_uris": ["https://cs.example.com/rp1"],
  "response_types": ["code"]
}

The federation's policy for RPs:

{
    "scopes": {
        "superset_of": ["openid", "eduperson"],
        "default": ["openid", "eduperson"]
    },
    "response_types": {
        "subset_of": ["code", "code id_token"]}
}

The organization's policy for RPs:

{
  "contacts": {
    "add": "helpdesk@example.com"},
  "logo_uri": {
    "one_of": ["https://example.com/logo_small.jpg",
               "https://example.com/logo_big.jpg"],
    "default": "https://example.com/logo_small.jpg"
  },
  "policy_uri": {
    "value": "https://example.com/policy.html"},
  "tos_uri": {
    "value": "https://example.com/tos.html"}
}

The metadata for the entity in question after applying the policies above, would then become:

{
  "contacts": ["rp_admins@cs.example.com", "helpdesk@example.com"],
  "logo_uri": "https://example.com/logo_small.jpg",
  "policy_uri": "https://example.com/policy.html",
  "tos_uri": "https://example.com/tos.html",
  "scopes": ["openid", "eduperson"],
  "response_types": ["code"],
  "redirect_uris": ["https://cs.example.com/rp1"]
}

5. Obtaining Federation Entity Configuration Information

The configuration endpoint is found using the Well-Known URIs specification, with the suffix openid-federation. The scheme, host and port is taken directly from the entity identifier combined with the following path: /.well-known/openid-federation.

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

Federation Entities MUST make an Entity Configuration Document available at the configuration endpoint.

5.1. Federation Entity Configuration Request

A federation Entity Configuration Document MUST be queried using an HTTP GET request at the previously specified path. The requesting party would make the following request to the Entity https://example.com to obtain its Configuration information:


  GET /.well-known/openid-federation HTTP/1.1
  Host: example.com

5.2. Federation Entity Configuration Response

The response is a self-signed Entity Statement, as described in entity statement. If the entity is an intermediate entity or a trust anchor the response MUST contain metadata for a federation entity.

A positive response is a signed entity statement, where the content type MUST be set to application/jose. In case of an error, the response will be a JSON object, the content type MUST be set to application/json and the error response uses the applicable HTTP status code value.

The following is a non-normative example response from an intermediate entity, before serialization and adding a signature:

200 OK
Last-Modified: Thu, 29 Aug 2019 08:54:26 GMT
Content-Type: application/jose

{
  "iss": "https://example.com",
  "sub": "https://example.com",
  "iat": 1516239022,
  "exp": 1516298022,
  "metadata": {
    "federation_entity": {
      "federation_api_endpoint":
        "https://example.com/federation_api_endpoint",
      "name": "The example cooperation",
      "homepage_uri": "https://www.example.com",
    }
  },
  "jwks": {
    "keys": [
      {
        "alg": "RS256",
        "e": "AQAB",
        "ext": true,
        "key_ops": ["verify"],
        "kid": "key1",
        "kty": "RSA",
        "n": "pnXBOusEANuug6ewezb9J_...",
        "use": "sig"
      }
    ]
  }
}

6. The Federation API

All entities that are expected to publish entity statements about other entities MUST expose a Federation API endpoint.

The federation API endpoint of an entity can be found the in the configuration response as described in Section 5 or by other means.

The Federation API is an HTTPS API that may support multiple operations. Fetching entity statements is one of the operations, and the only one that all Federation API endpoints are REQUIRED to support. All the other operations are OPTIONAL. The list of defined operations may be extended in a future.

While all operations on the federation API endpoint make use of a GET request, other operations may choose to use other HTTP methods. If the operation parameter is left out, it is treated as a fetch entity statements request. Unless otherwise mentioned or agreed upon, requests to the federation API do not need to be authenticated.

6.1. Fetching Entity Statement (REQUIRED)

Fetching entity statement is used to collect entity statements one by one in order to gather trust chains.

In order to fetch an entity statement, an entity needs to know the identifier of the entity to ask (the issuer), the federation API endpoint of that entity and the identifier of the entity that you want the statement to be about (the subject).

6.1.1. Fetch Entity Statements Request

The request MUST be an HTTP request using the GET method and the https scheme to a resolved federation API endpoint with the following query string parameters:

operation

OPTIONAL. If not present, MUST be treated as fetch.
iss

REQUIRED. The entity identifier of the issuer from which you want an entity statement issued. Because of the normalization of the URL, multiple issuers may resolve to a shared federation API. This parameter makes it explicit exactly which issuer we want entity statements from.
sub

OPTIONAL. The entity identifier of the subject for which you would like an entity statement issued. If this parameter is left out, it is considered to be the same as the issuer and would indicate a request for a self-issued statement.
aud

OPTIONAL. The entity identifier of the requester. If the aud parameter is present in the request, the aud claim SHOULD be present in the entity statement response and take exactly that value.

The following is a non-normative example of an API request for an entity statement:

GET /federation_api_endpoint?
iss=https%3A%2F%2Fopenid.sunet.se%2Ffederation HTTP/1.1
Host: openid.sunet.se

6.1.2. Fetch Entity Statements Response

A positive response is a signed entity statement where the content type MUST be set to application/jose. If it is negative response it will be a JSON object and the content type MUST be set to application/json. See more about error responses in Section 6.4.

The following is a non-normative example of a response, before serialization and adding a signature:

200 OK
Last-Modified: Mon, 17 Dec 2018 11:15:56 GMT
Content-Type: application/jose

{
  "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"],
      "jwks_uri": "https://openid.sunet.se/rp/jwks.json"
    }
  },
  "jwks": {
    "keys": [
      {
        "alg": "RS256",
        "e": "AQAB",
        "ext": true,
        "key_ops": ["verify"],
        "kid": "key1",
        "kty": "RSA",
        "n": "pnXBOusEANuug6ewezb9J_...",
        "use": "sig"
      }
    ]
  },
  "authority_hints": [
      "https://edugain.org/federation"
  ]
}

6.2. Trust Negotiation (OPTIONAL)

An entity may use the trust negotiation operation in order to fetch resolved metadata about itself as seen/trusted by a remote peer. The result may, for instance, tell an RP what operations, scopes and claims an OP would allow the RP to use if a specific trust anchor was used.

6.2.1. Trust Negotiation Request

The request MUST be an HTTP request using the GET method and the https scheme to a resolved federation API endpoint with the following query string parameters:

operation

REQUIRED. MUST be set to resolve_metadata.
respondent

REQUIRED. The entity identifier of the entity whose metadata are requested. Because of the normalization of the URL, multiple entity identifiers may resolve to a shared federation API. This parameter makes it explicit exactly which entity is expected.
peer

REQUIRED. The entity identifier of the entity the information is requested for. This must be a leaf entity.
type

REQUIRED. The metadata type to resolve. In this document, we use the metadata types listed in Section 3.
anchor

REQUIRED. The trust anchor the remote peer MUST use when resolving the metadata. The value is an entity identifier.

The following is a non-normative example of an API request for trust negotiation:

GET /federation_api_endpoint?
operation=resolve_metadata&
respondent=https%3A%2F%2Fopenid.sunet.se%2Ffederation&
type=openid_provider&
anchor=https%3A%2F%2Fswamid.se&
peer=https%3A%2F%2Fidp.umu.se%2Fopenid HTTP/1.1
Host: openid.sunet.se

6.2.2. Trust Negotiation Response

The response is a metadata statement that is the result of applying the metadata policies in the trust chain on the entity's metadata.

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

200 OK
Last-Modified: Wed, 22 Jul 2018 19:15:56 GMT
Content-Type: application/json

{
  "organization": "University of Ume?",
  "contacts": ["legal@umu.se", "technical@umu.se"],
  "logo_uri":
    "https://www.umu.se/SRWStatic/img/umu-logo-left-neg-SE.svg",
  "policy_uri":
    "https://www.umu.se/en/about-the-website/legal-information/",
  "authorization_endpoint":
    "https://idp.umu.se/openid/authorization",
  "token_endpoint": "https://idp.umu.se/openid/token",
  "response_types_supported": ["code", "code id_token", "token"],
  "grant_types_supported": [
    "authorization_code",
    "implicit",
    "urn:ietf:params:oauth:grant-type:jwt-bearer"
  ],
  "subject_types_supported": ["pairwise"],
  "id_token_signing_alg_values_supported": ["RS256"]
}

6.3. Entity Listings (OPTIONAL)

An entity may query another entity for a list of all the entities immediately subordinate to that entity and about which that entity is prepared to issue statements about. (In some cases, this may be a very large list.)

6.3.1. Entity Listings Request

The request MUST be an HTTP request using the GET method and the https scheme to a resolved federation API endpoint with the following query string parameters:

operation

REQUIRED. MUST be set to listing.
iss

REQUIRED. The entity identifier of the entity from which an entity listing is requested. Because of the normalization of the URL, multiple entity identifiers may resolve to a shared federation API. This parameter makes it explicit exactly which entity is expected.
is_leaf

OPTIONAL. If left out, result should include both leaf entities and intermediate nodes. If set to true, the response should contain only leaf entities. If set to false, the response should contain only intermediate nodes.

The following is a non-normative example of an API request for trust negotiation:

GET /federation_api_endpoint?
operation=listing&
iss=https%3A%2F%2Fopenid.sunet.se%2Ffederation HTTP/1.1
Host: openid.sunet.se

6.3.2. Entity Listing Response

The response MUST contain an JSON list with the known entity identifiers.

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

200 OK
Last-Modified: Wed, 22 Jul 2018 19:15:56 GMT
Content-Type: application/json

[
  "https://ntnu.andreas.labs.uninett.no/",
  "https://blackboard.ntnu.no/openid/callback",
  "https://serviceprovider.andreas.labs.uninett.no/application17"
]

6.4. Generic Error Response

If the request was malformed, or some error occurred during processing of the request, the following standardized error format should be used regardless of the operation specified.

The HTTP response code MUST be something in 400/500-range, giving an indication of the type of error. The response body MUST be a JSON object containing the claims below and the content type MUST be set to application/json.

operation

REQUIRED. The operation of the request.
error

REQUIRED. The error code.
error_description

REQUIRED. A human readable short text describing the error.

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

400 Bad request
Last-Modified: Wed, 22 Jul 2018 19:15:56 GMT
Content-Type: application/json

{
  "operation": "fetch",
  "error": "invalid_request",
  "error_description":
    "Required request parameter [iss] was missing."
}

7. Resolving Trust Chain and Metadata

An entity (e.g., the Consumer) that wants to establish trust with a remote peer, must have the remote peer's entity identifier and a list of entity identifiers of trust anchors together with the public version of their signing keys. The Consumer will first have to fetch sufficient entity statements to establish at least one chain of trust from the remote peer to one or more of the configured trust anchors. After that the entity MUST validate the trust chains independently, and -- if there are multiple valid trust chains and if the application demands it -- choose one.

7.1. Fetching Entity Statements to Establish a Trust Chain

Depending on the circumstances, the Consumer may either be handed the remote peer's self-issued entity statement, or it may have to fetch it by itself. If it needs to fetch it, it will use the process described in Section 6.1.1 with both iss and sub set to the entity identifier of the remote peer.

The next step is to iterate through the list of intermediates listed in authority_hints, ignoring the authority hints that end in an unknown trust anchor, requesting an entity statement about the remote peer from each of the intermediates. If the received entity statement contains an authority hint this process is repeated. This time with the iss set to the intermediates entity identifier and the sub to be the iss of the previous query. The Consumer SHOULD NOT attempt to fetch entity statements it already has fetched during this process (loop prevention).

A successful operation will return one or more lists of entity statements. Each of the lists terminating in a self-signed entity statement issued by a trust anchor.

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

7.2. Validating the Trust Chains

As described in Section 2.2, a trust chain consists of an ordered list of entity statements. So whichever way the Consumer has acquired the set of entity statements, it must now verify that it is a proper trust chain using the rules laid out in that section.

To validate the chain, the following must be done:

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

Consumers MAY cache Entity Statements or signature verification results for a given time until they expire Section 7.5.

7.3. Applying Constraints

A constraint specification can contain the following claims:

max_path_length

OPTIONAL. Integer. The maximum number of entities statements between this entity statement and the last entity statement in the trust chain.
naming_constraints

OPTIONAL. JSON object. Restriction on the entity identifiers of the entities below this entity. The behavior of this claim mimics what is defined in Section 4.2.1.10 in [RFC5280]. Restrictions are defined in terms of permitted or excluded name subtrees.

The following is a non-normative example of such a specification:

{
  "naming_constraints": {
    "permitted": [
      "https://.example.com"
    ],
    "excluded": [
      "https://east.example.com"
    ]
  },
  "max_path_length": 2
}

If a subordinate entity statement contains a constraint specification that is more restrictive then the one in effect, then the more restrictive constraint is in effect from here on.

If a subordinate entity statement contains a constraint specification that is less restrictive then the one in effect, then it MUST be ignored.

7.3.1. Max Path Length

The max_path_length constraint specifies the maximum number of entity statement a trust chain can have between the entity statement that contains the constraint specification and the leaf's entity statement.

A max_path_length constraint of zero indicates that no entity statement may appear between this entity statement and the leaf entity statement. Where it appears, the max_path_length constraint MUST have a value that is greater than or equal to zero. Where max_path_length does not appear, no limit is imposed.

Assuming that we have a trust chain with four entity statements:

  1. Leaf entity (LE)
  2. Intermediate 1 (I1)
  3. Intermediate 2 (I2)
  4. Trust Anchor (TA)

Then the trust chain fulfills the constraints if:

The trust chain does not fulfill the constraints if:

7.3.2. Naming Constraints

The name constraints indicates a name space within which all subject entity identifiers in subordinate entity statements in a trust chain MUST be located.

Restrictions are defined in terms of permitted or excluded name subtrees. Any name matching a restriction in the excluded claim is invalid regardless of information appearing in the permitted claim.

The constraint MUST be specified as a fully qualified domain name and MAY specify a host or a domain. Examples would be "host.example.com" and ".example.com". When the constraint begins with a period, it MAY be expanded with one or more labels. That is, the constraint ".example.com" is satisfied by both host.example.com and my.host.example.com. However, the constraint ".example.com" is not satisfied by "example.com". When the constraint does not begin with a period, it specifies a host.

7.4. Choosing One of the Valid Trust Chains

If multiple valid trust chains are found, the Consumer will need to decide on which one to use.

One simple rule would be to prefer a shorter chain over a longer one.

Consumers MAY follow other rules according to local policy.

7.5. Calculating the Expiration Time of a Trust Chain

Each entity statement in a trust chain is signed and MUST have an expiration time (exp) set. The expiration time of the whole trust chain is set to the minimum value of exp within the chain.

8. Updating Metadata, Key Rollover, and Revocation

This specification allows for a smooth process of updating metadata and public keys.

As described above in Section 7.5, each trust chain has an expiration time. A consumer of metadata using this specification MUST support refreshing a trust chain when it expires. How often a consumer should re-evaluate the trust chain depends on how quickly the consumer wants to find out that something has changed in the trust chain.

8.1. Protocol Key Rollover

If a leaf entity publishes its public keys in the metadata part using jwks, setting an expiration time on the self-signed entity statement can be used to control how often the receiving entity is fetching an updated version of the public key.

8.2. Key Rollover for a Trust Anchor

A trust anchor must publish a self-signed entity statement about itself. The trust anchor SHOULD set a reasonable expiration time on that statement, such that the consumers will re-fetch the entity statement at reasonable intervals. If the trust anchor wants to roll over its signing keys it would have to:

  1. Add the new keys to the jwks representing the trust anchors signing keys.
  2. Keep signing the entity statement using the old keys for a long enough time period to allow all subordinates to have gotten access to the new keys.
  3. Switch to signing with the new keys.
  4. After a reasonable time period remove the old keys. What is regarded as a reasonable time is dependent on the security profile and risk assessment of the trust anchor.

It must be taken into consideration that clients may have manually configured pubic keys as part of their configuration.

8.3. Revocation

Since the consumers are expected to check the trust chain at regular, reasonably frequent times, this specification does not specify a standard revocation process. Specific federations may make a different choice and will then have to add such a process.

9. OpenID Connect Communication

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

There are two alternative approaches to establish trust between an RP and an OP, which we call automatic and explicit registration. Members of a federation or a community should agree upon which one to use. While implementations should support both methods, deployments may choose to disable the use of one of them.

Independent of whether the RP uses automatic or explicit registration, the way that the RP learns about the OP is the same. It will use the procedure that is described in Section 7.

9.1. Automatic Registration

The client_id of the RP MUST be set identically to the RP entity identifier.

Without a registration process, the RP does not have a client_secret. Instead the automatic registration model requires the RP to make use of asymmetric cryptography.

The RP MUST host a Federation API that allows the OP to fetch the entity statements.

9.1.1. The Authentication Request

The authentication request is as specified in OpenID Connect Core.

The RP MUST authenticate at the authentication endpoint using the private_key_jwt method described in the client authentication section of OpenID Connect Core 1.0.

An authentication request example:

GET /authorization?
  redirect_uri=https%3A%2F%2Fexample.com%2Fauthz_cb
  &scope=openid+profile+email+address+phone
  &response_type=code
  &nonce=4LX0mFMxdBjkGmtx7a8WIOnB&
  &state=YmX8PM9I7WbNoMnnieKKBiptVW0sP2OZ
  &client_id=https%3A%2F%2Fexample.com%3A8090%2Firp
  &client_assertion=eyJhbGciOiJSUzI1NiIs ... qx7xHcvPOdIhnpg
  &client_assertion_type=
    urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
  HTTP/1.1
Host: example.org

9.1.2. Processing the Authentication Request

When the OP receives an incoming authentication request, the OP supports OpenID Connect Federation, the incoming client_id is a valid URL and the OP does not have the client_id registered as a known client then the OP should try to resolve and fetch trust chains starting with the RP's entity statement as described in Section 7.1.

The OP should validate the possible trust chains, as described in Section 7.2, and resolve the RP metadata with type openid_relying_party.

The OP should consider the resolved metadata of the RP, and verify that it complies with the client metadata specification in OpenID Connect Dynamic Client Registration 1.0.

Once the OP has the RP's metadata, it can verify the client authentication.

9.1.3. Authentication Error Response

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

In addition to the error codes defined in Section 3.1.2.6 of OpenID Connect core, this specification also defines the following error codes:

missing_trust_anchor

No trusted trust anchor could be found.
validation_failed

Trust chain validation failed.

The following is a non-normative example error response:

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

9.2. Explicit Registration

This method involves performing an explicit registration of a new client the first time an RP interacts with an OP using something that basically follows the steps in OpenID Connect Dynamic Client Registration 1.0 but where the client registration request is a signed entity statement.

9.2.1. Provider Discovery

The RP will start by gathering the OP's metadata using the process specified in Section 7 above.

9.2.2. Client Registration

9.2.2.1. Client Registration Request

The OP MUST support OpenID Dynamic Client Registration as extended by this specification. This is signaled by having the claim federation_registration_endpoint in the OP's metadata.

Given that the OP supports explicit registration, the RP progresses as follows:

  1. Once it has the list of acceptable trust chains for the OP it MUST choose the subset it wants to progress with. The subset can be as small as one trust chain, but it can also contain more than one.
  2. Based on the trust anchors referenced in the subset of trust chains, the RP will choose a set of authority_hints from its own set that terminates in those trust anchors.
  3. The RP will now construct a self-signed entity statement where the metadata statement chosen is influenced by the OPs metadata and the authority_hints included are picked by the process described above.
  4. The entity statement is sent, using POST, to the federation_registration_endpoint defined in this document. The content type MUST be set to application/jose.

9.2.2.2. Client Registration Response

9.2.2.2.1. The OP Constructing the Response

  1. After the OP receives the request, it collects and evaluates the trust chains starting with the authority_hints in the registration request. After it has verified at least one trust chain it MUST verify that the signature on the received registration request is correct.
  2. If it finds more than one acceptable trust chain, it MUST choose one trust anchor from those chains as the one it will proceed with.
  3. At this point, if there already exists a client registration under the same entity identifier then that registration MUST be regarded as invalid. Note that key material from the previous registration MUST be kept to make key rollover possible.
  4. The OP will now construct a metadata policy that, if applied to the RP's metadata statement, will result in metadata that the OP finds acceptable. Note that the client_id the OP chooses does not have to be the same as the entity identifier of the RP. To the entity statement it will add one or more authority_hints, from its collection, that terminate in the trust anchor chosen above.
  5. It will sign and return the registration response (a signed entity statement) to the RP.

9.2.2.2.2. The RP Parsing the Response

  1. The RP verifies the correctness of the received entity statement, making sure that the trust chains starting at the authority_hints terminates in trust anchors that were referenced in the entity statement it sent to the OP.
  2. The RP MUST NOT apply metadata policies from the trust chains that the OP provides because those are not valid for the RP's metadata. The RP MUST apply policies to the metadata using one of its own trust chains that ends in the trust anchor that the OP chose. Once it has applied those policies it can the apply the policy returned from the OP. When it has applied all the metadata policies to its metadata statement, it then stores the result and can continue communicating with the OP using the agreed-upon metadata.
  3. At this point the RP also knows which trust chain it should use when evaluating the OP's metadata. It can therefore apply the metadata policies on the OP's metadata using the relevant trust chain and store the result as the OPs metadata.
  4. If the RP does not accept the received entity statement for some reason, then it has the choice to restart the registration process or to give up.

9.2.3. After Client Registration

A client registration using this specification is not expected to be valid forever. The entity statements exchanged all have expiration times, which means that the registration will eventually time out. An OP can also for administrative reasons decide that a client registration is not valid anymore. An example of this could be that the OP leaves the federation in use.

9.2.3.1. What the RP MUST Do

At regular intervals, the RP MUST:

  1. Starting with the OP's entity statement, resolve and verify the trust chains it chooses to use when constructing the registration request. If those trust chains do not exist anymore or do not verify, then the registration should be regarded as invalid and a new registration process should be started.
  2. If the OP's entity statement was properly formed the RP must now verify that the entity statement it received about itself from the OP is still valid. Again, if that is not the case the registration should be regarded as invalid and a new registration process should be started.

What is regarded as reasonable intervals will depend on federation policies and risk assessment by the maintainer of the RP.

9.2.3.2. What the OP MUST Do

At regular intervals, the OP MUST:

  1. If the signature on the registration request has expired it MUST mark the registration as invalid and demand that the RP MUST re-register. Else
  2. starting with the RP's client registration request, the OP MUST verify that there still is a valid trust chain terminating in the trust anchor the OP chose during the registration process.

9.2.4. Expiration Times

An OP MUST NOT assign an expiration time to an RP's registration that is later than the trust chain's expiration time.

10. IANA Considerations

TBD Register federation_types_supported for OP metadata with initial values automatic, explicit.

TBD Register federation_type for RP registration metadata.

TBD Register federation_registration_endpoint for the OP metadata.

11. Security Considerations

TBD

12. References

12.1. Normative References

[OpenID.Core] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B. and C. Mortimore, "OpenID Connect Discovery 1.0", August 2015.
[OpenID.Discovery] Sakimura, N., Bradley, J., Jones, M. and E. Jay, "OpenID Connect Discovery 1.0", August 2015.
[OpenID.Registration] Sakimura, N., Bradley, J. and M. Jones, "OpenID Connect Dynamic Client Registration 1.0", August 2015.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R. and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008.
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012.
[RFC7515] Jones, M., Bradley, J. and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015.
[RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015.
[RFC7519] Jones, M., Bradley, J. and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015.
[RFC7591] Richer, J., Jones, M., Bradley, J., Machulak, M. and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, July 2015.
[RFC8414] Jones, M., Sakimura, N. and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018.
[RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019.

12.2. Informative References

[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018.

Appendix A. Provider Information Discovery and Client Registration in a Federation

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

The players

                       EduGAIN
                          |
       +------------------+------------------+
       |                                     |
    SWAMID                               InCommon
       |                                     |
     umu.se                                  |
       |                                     |
   op.umu.se                           wiki.ligo.org

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

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

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

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

Let us start with discovering Provider information.

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

Metadata discovery is a sequence of steps that starts with the RP fetching the self-signed entity statement of the leaf (in this case https://op.umu.se) using the process defined in Section 5. What follows thereafter is this sequence of steps:

  1. Pick out the immediate superior entities using the authority hints
  2. Fetch the configuration for each such entity. This uses the process defined in Section 5
  3. Using the federation API endpoint of the superiors do a fetch request Section 6.1.1 on the endpoint asking for information about the subordinate entity.

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

When building the trust chain, the entity statements issued by a superior about its subordinate is used together with the self-signed entity statement issued by the leaf.

The self-signed entity statement concerning intermediates are not part of the trust chain.

A.1.1. Configuration Information for op.umu.se

The LIGO WIKI RP fetches the self-signed entity statement from the OP (op.umu.se) using the process defined in Section 5.

The result is this entity statement.

{
    "authority_hints": [
        "https://umu.se"
    ],
    "exp": 1568397247,
    "iat": 1568310847,
    "iss": "https://op.umu.se",
    "jwks": {
        "keys": [
            {
                "e": "AQAB",
                "kid": "dEEtRjlzY3djcENuT01wOGxrZlkxb3RIQVJlMTY0...",
                "kty": "RSA",
                "n": "x97YKqc9Cs-DNtFrQ7_vhXoH9bwkDWW6En2jJ044yH..."
            }
        ]
    },
    "metadata": {
        "openid_provider": {
            "authorization_endpoint":
              "https://op.umu.se/openid/authorization",
            "federation_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"
            ],
            "logo_uri":
              "https://www.umu.se/img/umu-logo-left-neg-SE.svg",
            "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"
        }
    },
    "sub": "https://op.umu.se"
}

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

This entity statement is the first link in the trust chain.

A.1.2. Configuration Information for 'https://umu.se'

The LIGO RP fetches the self-signed entity statement from "https://umu.se" using the process defined in Section 5.

{
    "authority_hints": [
        "https://swamid.se"
    ],
    "exp": 1568397247,
    "iat": 1568310847,
    "iss": "https://umu.se",
    "jwks": {
        "keys": [
            {
                "e": "AQAB",
                "kid": "endwNUZrNTJsX2NyQlp4bjhVcTFTTVltR2gxV2RV...",
                "kty": "RSA",
                "n": "vXdXzZwQo0hxRSmZEcDIsnpg-CMEkor50SOG-1XUlM..."
            }
        ]
    },
    "metadata": {
        "federation_entity": {
            "contacts": "ops@umu.se",
            "federation_api_endpoint": "https://umu.se/oidc/fedapi",
            "homepage_uri": "https://www.umu.se",
            "name": "UmU"
        }
    },
    "sub": "https://umu.se"
}

The only piece of information that is used from this entity statement is the federation_api_endpoint, which is used in the next step.

A.1.3. Entity Statement Published by 'https://umu.se' about 'https://op.umu.se'

The RP uses the federation API and the "fetch" command as defined in Section 6.1.1 to fetch information about "https://op.umu.se" from the API endpoint published in https://umu.se's configuration.

{
    "authority_hints": [
        "https://swamid.se"
    ],
    "exp": 1568397247,
    "iat": 1568310847,
    "iss": "https://umu.se",
    "jwks": {
        "keys": [
            {
                "e": "AQAB",
                "kid": "dEEtRjlzY3djcENuT01wOGxrZlkxb3RIQVJlMTY0...",
                "kty": "RSA",
                "n": "x97YKqc9Cs-DNtFrQ7_vhXoH9bwkDWW6En2jJ044yH..."
            }
        ]
    },
    "metadata_policy": {
        "openid_provider": {
            "contacts": {
                "add": [
                    "ops@swamid.se"
                ]
            },
            "organization": {
                "value": "University of Ume\u00e5"
            },
            "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"
                ]
            }
        }
    },
    "sub": "https://op.umu.se"
}

This is the second link in the trust chain.

Notable here is that this path leads to two trust anchors using the same next step ("https://swamid.se").

A.1.4. Configuration Information for 'https://swamid.se'

The LIGO Wiki RP fetches the self-signed entity statement from "https://swamid.se" using the process defined in Section 5.

{
    "authority_hints": [
        "https://edugain.geant.org"
    ],
    "exp": 1568397247,
    "iat": 1568310847,
    "iss": "https://swamid.se",
    "jwks": {
        "keys": [
            {
                "e": "AQAB",
                "kid": "N1pQTzFxUXZ1RXVsUkVuMG5uMnVDSURGRVdhUzdO...",
                "kty": "RSA",
                "n": "3EQc6cR_GSBq9km9-WCHY_lWJZWkcn0M05TGtH6D9S..."
            }
        ]
    },
    "metadata": {
        "federation_entity": {
            "contacts": "ops@swamid.se",
            "federation_api_endpoint":
              "https://swamid.sunet.se/fedapi",
            "homepage_uri": "https://www.sunet.se/swamid/",
            "name": "SWAMID"
        }
    },
    "sub": "https://swamid.se"
}

The only piece of information that is used from this entity statement is the federation_api_endpoint, which is used in the next step.

A.1.5. Entity Statement Published by 'https://swamid.se' about 'https://umu.se'

The LIGO Wiki RP uses the federation API and the "fetch" command as defined in Section 6.1.1 to fetch information about "https://umu.se" from the API endpoint published in https://swamid.se's configuration.

{
    "authority_hints": [
        "https://edugain.geant.org"
    ],
    "exp": 1568397247,
    "iat": 1568310847,
    "iss": "https://swamid.se",
    "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"
                ]
            }
        }
    },
    "sub": "https://umu.se"
}

This is the third link in the trust chain.

If we assume that the issuer of this entity statement is not in the list of trust anchors the LIGO Wiki RP has access to we have to go one step further.

A.1.6. Configuration Information for 'https://edugain.geant.org'

RP fetches the self-signed entity statement from "https://edugain.geant.org" using the process defined in Section 5.

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

Again, the only thing we need is the federation_api_endpoint. As described in Section 8.2, note should also be taken to jwks as the trust anchor may be performing a key rollover.

A.1.7. Entity Statement Published by 'https://edugain.geant.org' about 'https://swamid.se'

The LIGO Wiki RP uses the federation API and the "fetch" command as defined in Section 6.1.1 to fetch information about "https://swamid.se" from the API endpoint published in https://edugain.geant.org's configuration.

{
    "exp": 1568397247,
    "iat": 1568310847,
    "iss": "https://edugain.geant.org",
    "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_part": {
            "contacts": {
                "add": "ops@edugain.geant.org"
            }
        }
    },
    "sub": "https://swamid.se"
}

If we assume that the issuer of this statement appears in the list of trust anchors the LIGO Wiki RP has access to this would be the fourth and final entity statement in the trust chain.

We now have the whole chain from the self-signed entity statement of the leaf up until the last one which is issued by a trust anchor. All in all, we have:

  1. Self-signed entity statement by the leaf (https://op.umu.se)
  2. Statement issued by https://umu.se about https://op.umu.se
  3. Statement issued by https://swamid.se about https://umu.se
  4. Statement issued by https://edugain.geant.org about https://swamid.se

Using the public keys of the trust anchor that the LIGO Wiki RP has been provided with in some secure out-of-band way, it can now verify the trust chain as described in Section 7.2.

A.1.8. Verified Metadata for op.umu.se

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

Merging the metadata policies from the tree entity statements we have, by a superior about its subordinate, 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@edugain.geant.org",
    "federation_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"
    ],
    "logo_uri":
      "https://www.umu.se/img/umu-logo-left-neg-SE.svg",
    "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"
}

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

A.2. The Two Ways of Doing Client Registration

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

Automatic

No negotiation between the RP and the OP is made regarding what features the client should use in future communication are done. The RP's published metadata filtered by the chosen trust chain's metadata policies defines the metadata that is to be used.
Explicit

The RP will access the federation_registration_endpoint, which provides the metadata for the RP to use. The OP MAY return a metadata policy that adds restrictions over and above what the trust chain already has defined.

A.2.1. RP Sends Authentication Request (Automatic Registration)

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

Here is an example of an authentication request:

GET /authorize?
  response_type=code
  &scope=openid%20profile%20email
  &client_id=https%3A%2F%2Fwiki.ligo.org%2F
  &state=2ff7e589-3848-46da-a3d2-949e1235e671
  &redirect_uri=https%3A%2F%2Fwiki.ligo.org%2Fopenid%2Fcallback
  &client_assertion=eyJhbGciOiJSUzI1NiIs ... qx7xHcvPOdIhnpg
  &client_assertion_type=
    urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
  HTTP/1.1
Host: op.umu.se

The OP receiving this authentication request will, unless the RP is cached or statically configured, start to dynamically fetch and establish trust with the RP.

A.2.1.1. OP Fetches Entity Statements

The OP needs to establish a trust chain for the RP (wiki.ligo.org). The OP in this example are configured with public key of 2 federations:

The OP starts to resolve metadata for the client identifier https://wiki.ligo.org by fetching the self-issued entity statement using the process described in Section 5.

The process is the same as described in Appendix A.1 and will result in a trust chain with the following entity statements:

  1. Self-signed entity statement by the leaf https://wiki.ligo.org
  2. Statement issued by https://incommon.org about https://wiki.ligo.org
  3. Statement issued by https://edugain.geant.org about https://incommon.org

A.2.1.2. OP Evaluates the RP Metadata

Using the public keys of the trust anchor that the LIGO Wiki RP has been provided with in some secure out-of-band way, it can now verify the trust chain as described in Section 7.2.

    "metadata_policy": {
        "openid_provider": {
            "contacts": {
                "add": "ops@edugain.geant.org"
            }
        },
        "openid_relying_party": {
            "contacts": {
                "add": "ops@edugain.geant.org"
            }
        }
    }
                
    "metadata_policy": {
        "openid_relying_party": {
            "application_type": {
                "one_of": [
                    "web",
                    "native"
                ]
            },
            "contacts": {
                "add": "ops@incommon.org"
            },
            "grant_types": {
                "subset_of": [
                    "authorization_code",
                    "refresh_token"
                ]
            }
        }
    }
                

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

edugain.geant.org
incommon.org

If you combine these and apply them to the metadata for wiki.ligo.org :

"metadata": {
    "openid_relying_party": {
        "application_type": "web",
        "client_name": "LIGO Wiki",
        "contacts": [
            "ops@ligo.org"
        ],
        "grant_types": [
            "authorization_code",
            "refresh_token"
        ],
        "id_token_signing_alg_values_supported": [
            "RS256",
            "RS512"
        ],
        "jwks_uri": "https://wiki.ligo.org/jwks.json",
        "redirect_uris": [
            "https://wiki.ligo.org/callback"
        ],
        "response_types": [
            "code"
        ],
        "subject_type": "public"
    }
}

You will get

{
    "application_type": "web",
    "client_name": "LIGO Wiki",
    "contacts": [
        "ops@ligo.org",
        "ops@incommon.org",
        "ops@edugain.geant.org"
    ],
    "grant_types": [
        "authorization_code",
        "refresh_token"
    ],
    "id_token_signing_alg_values_supported": [
        "RS256",
        "RS512"
    ],
    "jwks_uri": "https://wiki.ligo.org/jwks.json",
    "redirect_uris": [
        "https://wiki.ligo.org/callback"
    ],
    "response_types": [
        "code"
    ],
    "subject_type": "public"
}

Having that, the "registration" is done, and the OP must now use the keys found at the URL specified in jwks_uri to verify the client assertion in the authentication request.

A.2.2. Client Starts with Registration (Explicit Client Registration)

Here the LIGO Wiki RP sends a client registration request to the federation_registration_endpoint of the OP (op.umu.se). What it sends is a self-signed entity statement.

Once the OP has the entity statement, it proceeds with the same sequence of steps as laid out in Appendix A.1.

The OP will end up with the same RP metadata as was described in Appendix A.2.1.2, but what it now can do is return a metadata policy that it wants to be applied to the RP's metadata. This metadata policy will be combined with the trust chain's combined metadata policy before being applied to the RP's metadata.

If we assume that the OP has a bit more strict view on which type of crypto keys to use, it may want to add a metadata policy that says:

"metadata_policy":
   {
      "openid_relying_party": {
         "id_token_signing_alg_values_supported": [
            "RS512"
        ]
      }
}

In which case the metadata used by the RP should be described like this:

{
    "application_type": "web",
    "client_name": "LIGO Wiki",
    "contacts": [
        "ops@ligo.org",
        "ops@incommon.org",
        "ops@edugain.geant.org"
    ],
    "grant_types": [
        "authorization_code",
        "refresh_token"
    ],
    "id_token_signing_alg_values_supported": [
        "RS512"
    ],
    "jwks_uri": "https://wiki.ligo.org/jwks.json",
    "redirect_uris": [
        "https://wiki.ligo.org/callback"
    ],
    "response_types": [
        "code"
    ],
    "subject_type": "public"
}

Appendix B. Notices

Copyright (c) 2019 The OpenID Foundation.

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

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

Appendix C. Acknowledgements

The authors wish to acknowledge the contributions of the following individuals and organizations to this specification: Heather Flanagan, Misha Salle, Peter Schober, Michael Schwartz, and the JRA3T3 task force of GEANT4-2.

Appendix D. Open Issues

The following open issues remain to be addressed in this specification.

Appendix E. Document History

[[ To be removed from the final specification ]]

-10

-09

-08

-07

-06

-05

-04

Authors' Addresses

Roland Hedberg (editor) independent EMail: roland@catalogix.se
Michael B. Jones Microsoft EMail: mbj@microsoft.com URI: http://self-issued.info/
Andreas Åkre Solberg Uninett AS EMail: andreas.solberg@uninett.no URI: https://www.linkedin.com/in/andreassolberg/
Samuel Gulliksson Schibsted Media Group EMail: samuel.gulliksson@gmail.com
John Bradley Yubico EMail: ve7jtb@ve7jtb.com URI: http://www.thread-safe.com/