OpenID Federation Entity Configuration Hosting 1.0 - draft 00

Table of Contents

1. Introduction

OpenID Federation 1.0 [OpenID.Federation] defines a configuration endpoint where Federation Entities should publish their Entity Configuration. The URL for this endpoint is the Entity Identifier URL concatenated with /.well-known/openid-federation.¶

One situation where a Federation Entity may not be able to make their Entity Configuration available at this URL is when their Entity Configuration is hosted by a Superior Entity and published under a URL based on a domain name that is owned by the Superior Entity. Reasons for this may be that an Entity registering to a federation is not fully OpenID Federation-compatible, or simply that it cannot expose its Entity Configuration at this URL.¶

Another situation is when a Federation Entity, for legacy or other reasons, has an identifier that is not a URL. This is a case that is valid according for several Entity Types that may be supported by OpenID Federation.¶

Not publishing the Entity Configuration at the configuration endpoint is a choice by the Federation Entity itself with the clear consequence that the Federation Entity will not be discoverable based on their Entity Identifier alone.¶

This specification defines the ec_location Claim to be used in Subordinate Statements, holding a location where the Entity Configuration of the subordinate can be obtained.¶

2. The ec_location Claim

This section defines the ec_location Claim that MAY be included in a Subordinate Statement.¶

Using this Claim, an alternative location for the subject’s Entity Configuration can be specified in a Subordinate Statement. Typically, this location differs from the configuration endpoint defined in Section 9 of [OpenID.Federation].¶

The value of the ec_location Claim is a single string that specifies the URL where the subject’s Entity Configuration is available. This URL MUST use either the https scheme or the data URL scheme [RFC2397], containing the complete Entity Configuration as a signed JWT.¶

A data URL MUST use the media type application/entity-statement+jwt and MUST NOT include a ;base64 declaration. The Entity Configuration data MUST be provided using compact serialization without additional Base64 encoding.¶

Note: Base64 encoding is omitted because the Entity Configuration JWT already uses a URL-safe format.¶

Section 9 of [OpenID.Federation] mandates that Intermediate Entities and Trust Anchors publish their Entity Configuration at the configuration endpoint. Therefore, it is RECOMMENDED to use the ec_location Claim in Subordinate Statements only for Leaf Entities.¶

An Intermediate Entity creating a Subordinate Statement that includes the ec_location Claim SHOULD NOT mark this Claim as critical (see Section 13.4 of [OpenID.Federation]). The reason is that Trust Chain validation does not depend on support for ec_location. If a peer supplies the full chain, it can be validated even when the Claim is not understood.¶

{
  "iss" : "https://superior-entity.example.com",
  "sub" : "urn:example:legacy:rp",
  ...
  "ec_location" : "https://superior-entity.example.com/hosted/ec/example-legacy-rp",
  ...
}

Example 1: Excerpt of the Subordinate Statement issued by https://superior-entity.example.com for the subject urn:example:legacy:rp, where the Intermediate Entity itself hosts the subject's Entity Configuration. This is indicated using the ec_location Claim.¶

  "ec_location" : "data:application/entity-statement+jwt,eyJhb...Qssw5c"

Example 2: Using a data URL as the value for ec_location.¶

3. Trust Chain Construction

Section 10.1 of [OpenID.Federation] describes the process of establishing a Trust Chain using a bottom-up approach. In this approach, the process starts with the Entity Configuration of the Entity whose metadata and Trust Chain are to be resolved, and then constructs a chain up to a trusted Trust Anchor. This process uses the authority_hints Claim of each fetched Entity Statement to identify the next Superior Entity. The procedure is repeated until at least one trusted Trust Anchor is reached, for which a complete chain of statements can be evaluated.¶

Using this process will not work unless a Leaf Entity publishes its Entity Configuration at the configuration endpoint, as specified in Section 9 of [OpenID.Federation]. Not all Entities within a federation may be able to adhere to this requirement. Therefore, alternative chain construction mechanisms need to be used.¶

Section 17.2.2 of [OpenID.Federation] defines a top-down discovery pattern, where a Trust Chain is built starting from a known Trust Anchor.¶

The most important difference between top-down and bottom-up chain construction, as defined in Section 10.1 of [OpenID.Federation], is the order in which Entity Statements are collected. In top-down construction, the Subordinate Statement of an Entity is fetched before the Entity Configuration for the same subject. This fact, together with the use of the ec_location Claim (Section 2), enables the construction of a chain even when a subject Entity does not publish its Entity Configuration at the configuration endpoint.¶

The top-down chain construction algorithm SHOULD be used in federations where Entity Configurations may be hosted at locations other than an Entity’s configuration endpoint.¶

Federations that rely on the use of Resolvers (see Section 10.6 of [OpenID.Federation]) implementing top-down chain construction can use this capability to enable hosting of Entity Configuration documents at more convenient locations, while still ensuring the availability of validated peer Entity data via resolve endpoints.¶

4. Security Considerations

                      +-------------+
                      |     TA      |
                      +-------------+
                          |     |
                __________|     |__________
               |                           |
        +------v------+             +------v------+
        |    IE-1     |             |     IE-2    |
        +-------------+             +--------+----+   +........................+
               |                             |________| https://op.example.com |
   +-----------v------------+                         +........................+
   | https://op.example.com |                                   Hosted
   +------------------------+

5. Acknowledgments

We would like to thank the following individuals for their comments, ideas, and contributions to this implementation profile and to the initial set of implementations.¶

• Leif Johansson, Siros¶
• Felix Hellman, Helagon¶

Appendix A. Notices

Copyright (c) 2025 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 B. Document History

[[ To be removed from the final specification ]]¶

-00¶

• Initial version¶

Authors' Addresses