OpenID Federation Extended Subordinate Listing 1.0 - draft 02

Table of Contents

1. Introduction

The Federation Extended Subordinate Listing endpoint has been created to address two outstanding issues identified in [OpenID.Federation].¶

2. Terminology

This specification uses the terms "Entity Identifier", "Subordinate Statement", "Trust Anchor", "Intermediate", " Federation Entity", "Entity", "federation_list_endpoint", and "Immediate Subordinate Entity" as defined in [OpenID.Federation], "NumericDate" as defined in [RFC7591].¶

3. Extended Subordinate Listing Endpoint

The Federation Extended Subordinate Listing endpoint is exposed by Federation Entities acting as a Trust Anchor or Intermediate. The endpoint lists the Immediate Subordinate Entities about which the Issuing Entity can issue Subordinate Statements.¶

While similar to the federation_list_endpoint, the Federation Extended Subordinate Listing Endpoint provides both pagination of the result, optionally extensive details about subject Immediate Subordinate Entities, and flexibility in the definition of custom filters.¶

This endpoint is particularly valuable in scenarios where a federation contains one or more Intermediates that manage a large number of Immediate Subordinate Entities. To efficiently handle potentially large datasets, the endpoint incorporates a pagination capability. This allows clients to retrieve the data in manageable chunks.¶

GET /list_extended HTTP/1.1
Host: trust-anchor.star-federation.example.net

GET /list_extended?from_entity_id=https://rp0.example.net/oidc/rp HTTP/1.1
Host: trust-anchor.star-federation.example.net

GET /list_extended?updated_after=946681201&entity_type=openid_relying_party HTTP/1.1
Host: trust-anchor.star-federation.example.net

GET /list_extended?claims=trust_marks HTTP/1.1
Host: trust-anchor.star-federation.example.net

GET /list_extended HTTP/1.1

200 OK
Content-Type: application/json

{
  "immediate_subordinate_entities": [
    {
      "id": "https://rp0.example.net/oidc/rp",
      "subordinate_statement": "eyJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU2Iiwia2lkIjoiQlh2ZnJ..."
    },
    {
      "id": "https://rp0.example.net/oidc/rp",
      "subordinate_statement": "eyH1eZUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
    }
  ]
}

GET /list_extended?audit_timestamps=true&claims=subordinate_statement HTTP/1.1

200 OK
Content-Type: application/json

{
  "immediate_subordinate_entities": [
    {
      "id": "https://rp0.example.net/oidc/rp",
      "subordinate_statement": "eyH1eZUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ...",
      "registered":1704217689,
      "updated":1704217789
    },
  ]
}

GET /list_extended?claims=subordinate_statement,trust_marks HTTP/1.1

200 OK
Content-Type: application/json

{
  "immediate_subordinate_entities": [
    {
      "id": "https://rp1.example.net/oidc/rp",
      "trust_marks": [
        {
          "id": "https://www.spid.gov.it/certification/rp",
          "trust_mark": "eyJraWQiOiJmdWtDdUtTS3hwWWJjN09lZUk3Ynlya3N5a0E1bDhP..."
        }
      ],
      "subordinate_statement": "eyH1eZUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ...",
    }
  ]
}

4. Federation Entity Property

In order for Entities to advertise the Federation Extended Subordinate Listing, a new property has been defined adding to the existing set of Federation Entity Metadata as defined in [OpenID.Federation].¶

5. Examples

This section contains non-normative examples that demonstrate how to use the Federation Extended Subordinate Listing endpoint to retrieve subsets of Subordinates.¶

GET /list_extended HTTP/1.1

200 OK
Content-Type: application/json
{
  "immediate_subordinate_entities": [
    {
      "id": "https://0.example.net",
      "subordinate_statement": "eyJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU2Iiwia2lkIjoiQlh2ZnJ..."
    },
    {
      "id": "https://1.example.net",
      "subordinate_statement": "eyH1eZUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
    },
    ...
    {
      "id": "https://99.example.net",
      "subordinate_statement": "eyK2aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
    }
  ],
  "next_entity_id": "https://100.example.net"
}

Figure 8: A Trust Anchor returns the results list consisting of a large number of Immediate Subordinate Entities, along with the subsequent Entity Identifier used to retrieve the next page. This request specified no limit however the Issuing Entity chose to limit the response size according to it's defined upper limit.¶

GET /list_extended?from_entity_id=https://100.example.net HTTP/1.1

200 OK
Content-Type: application/json

{
  "immediate_subordinate_entities": [
    {
      "id": "https://100.example.net",
      "subordinate_statement": "eyK2aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
    },
    {
      "id": "https://101.example.net",
      "subordinate_statement": "eyH4aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
    },
    {
      "id": "https://102.example.net",
      "subordinate_statement": "eyW9aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
    }
  ]
}

Figure 9: A Trust Anchor returns all Entities starting from the Entity id provided as a parameter.¶

GET /list_extended?updated_after=946681201&entity_type=openid_relying_party&audit_timestamps=true HTTP/1.1

200 OK
Content-Type: application/json

{
  "immediate_subordinate_entities": [
    {
      "id": "https://123.example.net",
      "subordinate_statement": "eyJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU2Iiwia2lkIjoiQlh2ZnJ...",
      "registered": 1704217689,
      "updated": 1704217789
    },
    {
      "id": "https://323.example.net",
      "subordinate_statement": "eyW9aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ...",
      "registered": 1704217689,
      "updated": 1704217789
    },
    ...
    {
      "id": "https://342.example.net",
      "subordinate_statement": "eyK2aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ...",
      "registered": 1704217689,
      "updated": 1704217789
    }
  ],
  "next_entity_id": "https://736.example.net"
}

Figure 10: Get list of Immediate Subordinates updated after certain moment in time. The response contains more than one page.¶

6. Security Considerations

The security considerations of OpenID Federation 1.0 [OpenID.Federation] apply to this specification.¶

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, Final Specification, or Final Specification Incorporating Errata Corrections solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts, Final Specifications, and Final Specification Incorporating Errata Corrections 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 (found at openid.net) requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. OpenID 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. Acknowledgements

We would like to thank the following individuals for their contributions to this specification: Ralph Bragg, Vladimir Dzhuvinov, and Roland Hedberg.¶

Appendix C. Document History

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

-02¶

• Editorial pass on various typos and formatting issues.¶
• Corrected example incorrectly still using the entity_statement query parameter renamed in 01.¶
• Removed references to the revoked parameter.¶
• Updates to pass the OIDF specification content validation checks.¶

-01¶

• Corrected section hierarchy for Extended Subordinate Listing Response subsection.¶
• Made OpenID Federation reference normative.¶
• Renamed the claim name entity_statement to subordinate_statement in the response.¶
• entity_statement is not mandatory in the response if not explicitly requested.¶
• Terminology alignments.¶
• Added Acknowledgements.¶

-00¶

• Initial version¶

Authors' Addresses