!!! Overview
[{$pagename}] [specification] is being developed to enable large-scale [federations] to be deployed using [OpenID Connect] and enables [trust] among [federation] participants to be established through signed statements made by [federation] operators and organizations about [federation] participants.


[{$pagename}] specification builds upon the experiences gained in operating large-scale [SAML V2.0] [federations], and indeed, is authored by people having practical experience with these federations. A key innovation that differentiates [{$pagename}] from most SAML 2.0 federations is that OpenID Connect federation employs hierarchical [metadata], where participants directly publish statements about themselves, versus the aggregated [metadata] approach used by many [SAML] 2.0 [federations], where the federation operator publishes a single file concatenating all the metadata for all the federation participants. 

[{$pagename}] treats [OpenID Connect Providers] and [Relying Parties|Relying Party] symmetrically, with [metadata] being published about both.

[{$pagename}] [Entities] [MUST] have a [Unique Identifier] ([GUID]).

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

[{$pagename}] [trust] chains rely on [cryptographic] [Digital Signature] [JSON Web Token] ([JWT]) documents, and the [trust] chain __does not__ at all rely on [TLS]  in order to establish trust.


[{$pagename}] specifies how a [Relying Party] ([RP]) can [discover|Discovery Mechanism] [metadata] about an [OpenID Connect Provider] ([OP]), and then register to obtain client [credentials]. The [Discovery Mechanism] and [registration process|Credential Enrollment] 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]. [{$pagename}] specifies how [trust] can be dynamically obtained from resolving [trust] from a common trusted [Third-party].

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

[{$pagename}] describes how an identity federation can be built around a trusted third party, the federation operator.


!! 2.1 [Entity] Statement
[{$pagename}] defines an [Entity] Statement as always a signed [JWT]. An entity statement is issued by the iss, and the statement considers the subject entity, the sub. To be able to resolve [trust] and [metadata], one need to know the [identifier] of the target entity – we refer to this as the leaf entity. The leaf entity will always sign a statement about itself, and give some hints to other [entities] that may want to issue statements about itself. All other entities in a trust chain we refer to as intermediate entities. The local configured trust root, we refer to as the trust anchor.

An entity statement is composed of the following claims:
* [iss]
* [sub]
* [iat]
* [exp]
* [jwks]
* [aud] ([OPTIONAL])
* [authority_hints] ([OPTIONAL]) - Array of strings representing the entity IDs of intermediate entities that may issue an entity statement about the issuer entity. For all entities except for trust roots that do not have any superiors this is REQUIRED. This claim MUST be absent in an entity statement that belongs to a trust root with no superiors.
* [metadata] [REQUIRED] - [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 entity is a non-leaf entity it MUST contain a metadata object with a federation_entity object inside.
* [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. If the metadata type identifier is federation_entity, then the policy MUST be applied to the immediate subordinate in the trust chain unless that is a leaf entity. If the metadata type identifier is not federation_entity, then the policy MUST be applied to all subordinate nodes of that type in the trust chain. Only non-leaf entities MAY contain a metadata_policy claim. Leaf entities MUST NOT contain a metadata_policy claim.
* [crit] ([OPTIONAL]) - (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]) - (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]).

2.2. Trust Chain
In an [{$pagename}], [entities] that together build a [trust chain|Chain of trust] can be of one [Classification]:
* [Trust anchor] - An [entity] that represents a trusted [Third-party]
* [Leaf] In an [{$pagename}], 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).


!! 3 [{$pagename}] [Metadata]
[{$pagename}] does allow new [metadata] types to be defined, to support use cases outside [{$pagename}]. 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 [{$pagename}]s, 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] [JSONArray] 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|Organizational Entity] owning the [Relying Party].

! 3.2. [OP] [Metadata]
The metadata type identifier is [openid_provider] and 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] [JSONArray] 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|Organizational Entity] owning the [OpenID Connect Provider]. This is intended to be used in the user interface, being recognized by the end users that would be using the [OpenID Connect Provider] to [authenticate].
* [federation_registration_endpoint] - [OPTIONAL] - [URL] of the OP's Federation specific [OpenID Connect 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] [Metadata]
The metadata type identifier is [oauth_authorization_server] and all parameters defined in Section 2 of [RFC 8414] are applicable.

! 3.4. [OAuth Client] [Metadata]
The metadata type identifier is [oauth_client] all parameters defined in Section 2 of [RFC 7591]

! 3.5. OAuth [Protected Resource] [Metadata]
The metadata type identifier is [oauth_resource].

! 3.6. [Federation] [Entity]
The metadata type identifier is [federation_entity] and 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].
* [trust_anchor_id] - [OPTIONAL] - An OP MUST used this to tell the [Relying Party] which [Trust Anchor] it chose to use when responding to an explicit client registration.
* name - [OPTIONAL] - [String]. The [human] readable name describing the subject entity. This may be, for example, the name of an organization.
* contacts - [OPTIONAL] - [JSONArray] with one or more [strings]. Contact persons at the entity. These may contain [names], [Email Address], descriptions, [Phone Numbers], etc.
* [policy_uri] - [OPTIONAL] - [URL] to documentation of conditions and [policies|Policy] relevant to this entity.
* [homepage_uri] - [OPTIONAL] - [URL] to a generic home page representing this entity.
* [max_path_length] - [OPTIONAL] - [Integer]. The maximum number of intermediate entities below this [entity].
* [naming_constraints] - [OPTIONAL]- [JSON Object]. Restriction on the entity IDs of the entities below this entity. The behavior of this claim mimics what is defined in Section 4.2.1.10 in [RFC 5280]. Restrictions are defined in terms of permitted or excluded name subtrees.

Some other [{$pagename}] specifications:
* [OpenID Connect Federation Async]

!! More Information
There might be more information for this subject on one of the following:
[{ReferringPagesPlugin before='*' after='\n' }]
----
* [#1] - [OpenID Connect Federation 1.0|https://openid.net/specs/openid-connect-federation-1_0.html|target='_blank'] - based on information obtained 2017-06-15-