Overview#
OpenID Connect Federation 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.OpenID Connect Federation 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 OpenID Connect Federation 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.
OpenID Connect Federation treats OpenID Connect Providers and Relying Parties symmetrically, with metadata being published about both.
OpenID Connect Federation 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.
OpenID Connect Federation 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.
OpenID Connect Federation specifies how a Relying Party (RP) can discover metadata about an OpenID Connect Provider (OP), and then register to obtain client credentials. The Discovery Mechanism 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 Federation 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.
OpenID Connect Federation describes how an identity federation can be built around a trusted third party, the federation operator.
2.1 Entity Statement#
OpenID Connect Federation 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.
2.2. Trust Chain In an OpenID Connect Federation, entities that together build a trust chain can be of one Classification:
- Trust anchor - An entity that represents a trusted Third-party
- Leaf In an OpenID Connect Federation, an RP or an OP
- Intermediate - Neither a Leaf nor a Trust Anchor
3 OpenID Connect Federation Metadata#
OpenID Connect Federation does allow new metadata types to be defined, to support use cases outside OpenID Connect Federation. 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 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 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 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 75913.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 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 OpenID Connect Federation specifications:
More Information#
There might be more information for this subject on one of the following:- [#1] - OpenID Connect Federation 1.0
- based on information obtained 2017-06-15-