diff --git a/main.html b/main.html new file mode 100644 index 0000000..7e2cce8 --- /dev/null +++ b/main.html @@ -0,0 +1,1875 @@ + + + + + + +OpenID Federation Extended Subordinate Listing + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
openid-federation-extended-listingAugust 2024
De Marco, et al.Standards Track[Page]
+
+
+
+
Workgroup:
+
OpenID Connect A/B
+
Published:
+
+ +
+
Authors:
+
+
+
G. De Marco
+
Dipartimento per la trasformazione digitale
+
+
+
M. Fraser
+
Raidiam
+
+
+
L. Jaromin
+
Raidiam
+
+
+
M.B. Jones
+
Self-Issued Consulting
+
+
+
+
+

OpenID Federation Extended Subordinate Listing

+
+

Abstract

+

This specification acts as an extension to the [OpenID.Federation]. It outlines methods to interact with a given Federation with a potentially large number of registered Entities, as well as mechanisms to retrieve multiple entity statements along with associated details in a single request.

+
+
+
+ ▲

+Table of Contents +

+ +
+
+
+
+

+1. Introduction +

+

The extending listing endpoint has been created to address two outstanding issues identified in [OpenID.Federation].

+
+
+

+1.1. Response Size +

+

The standard federation_list_endpoint has limitations when entities are able to issue entity statements for an exceptionally large number of entities. Limitations can be encountered both when attempting to process receiving such a large response as well as more technical limitations such as response sizes of infrastructure. Pagination has been proposed as a solution for this.

+
+
+
+
+

+1.2. Bulk Retrieval +

+

For certain usecases, such as mass registration, consumers may encounter challenges when attempting to retrieve information on multiple entities. A flow with the standard federation_list_endpoint may involve a request to the list endpoint followed by a series of subsequent requests to retrieve an entity statement for each listed entity resulting in an N+1 operation. The extended listing endpoint seeks to solve this by providing a mechanism to include additional metadata for entities in the provided list.

+
+
+
+
+

+1.3. Requirements Notation and Conventions +

+

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

+
+
+
+
+
+
+

+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 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 Trust Anchor or Intermediate issues Subordinate Statements.

+

While similar to the federation_list_endpoint, the extended list endpoint provides pagination of the result, extensive details about 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 pagination functionality. This allows clients to retrieve the data in manageable chunks.

+

By segmenting the data into pages, the endpoint facilitates the efficient transmission and processing of data and also adds to the client's ability to navigate through the information. As pagination enables consumers of this endpoint to retrieve a section of the larger superset of data, some form of ordering on the response MUST be established by the issuing entity. No recommendation is made on which key the ordering is based upon and is left up to the choice of implementing entities.

+

The selected pagination type offers a mix of consistency and performance characteristics appropriate for the intended use of the endpoint. The size of the dataset does not impact performance. Changes made to previously fetched pages do not affect the overall result consistency, while any changes in pages yet to be fetched will be reflected in the overall result list.

+

The endpoint is accessible via the federation_extended_list_endpoint URL, which is published in the federation_metadata.

+
+
+

+3.1. Extended Subordinate Listing Request +

+

This endpoint follows the same rules that are defined in the federation_list_endpoint regarding client authentication, HTTP methods used, and the way parameters are passed.

+

The endpoint accepts all parameters defined in the federation_list_endpoint in addition to the parameters defined in the table below.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1
+ Parameter + + Availability + + Type + + Value +
from_entity_idOPTIONALEntity IdentifierIf this parameter is present, the resulting list MUST be the subset of the overall ordered response starting from the index of the entity referenced with this paramter. The list's size MUST NOT exceed the server's chosen upper limit.
+
+If the Entity Identifier that equals value of this parameter does not exist the HTTP status code 400 is returned and the content type application/json with the error code entity_id_not_found. TBD: Recommend client behavior on error.
limitOPTIONALPositive IntegerRequested number of results included in the response.
+
+ If this parameter is present, the number of results in the returned list must not be greater than the minimum of the server's upper limit and the value of this parameter.
+
+If this parameter is not present the server MUST fall back on the upper limit.
updated_afterOPTIONALNumericDateEpoch time constraining the response to include only Entity identifiers with updates at or after this time.
+
+When absent, there is no cutoff for how long ago updates occurred to Entities being listed.
+
+When present the registered, updated, revoked MUST be included in the response unless the audit_timestamps parameter is set to false.
updated_beforeOPTIONALNumericDateEpoch time constraining the response to include only Entity identifiers with updates at or before this time.
+
+When absent, there is no cutoff before which updates occurred to listed Entities.
+
+When present the registered, updated, revoked MUST be included in the response unless the audit_timestamps parameter is set to false.
claimsOPTIONALArrayList of claims to be included in the response for each returned Immediate Subordinate Entity.
+
+ If this parameter is NOT present or it is an empty array, the signed entity statement MUST be the only claim for each Immediate Subordinate Entity
+
+If this parameter is present and it is NOT an empty array each JSON object that represents the Immediate Subordinate Entity MUST include the requested claims for a subordinate entity statement if available.
+
+Entities that expose the extended subordinate listing endpoint MUST support all top level statement claims defined in [OpenID.Federation]. TBD: Support of requests for discrete entity metdata attributes.
audit_timestampsOPTIONALBooleanRequest parameter to control presence of the registered, updated, revoked audit timestamps attributes for all returned Immediate Subordiates.
+
+If this parameter absent the audit timestamp attributes mentioned above MUST NOT be present unless updated_after and/or updated_before parameters are present.
+
+If this parameter is present and set to true the response MUST include the above mentioned audit timestamp attributes for each Immediate Subordinate Entity included in the response.
+
+If this parameter is present and set to false the response MUST NOT include the above mentioned audit timestamp attributes for each Immediate Subordinate Entity included in the response. even irrespective whether the updated_after and/or updated_before request parameters are pressent.
+
+
+

Table 1: Additional request parameters accepted by the extended subordinate listing endpoint in addition to the those speficied by the federation_list_endpoint

+

Below are non-normative examples of an HTTP GET request to the federation extended list endpoint:

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

Figure 1: Initial request without parameters to list immediate subordinates. Typically an initial request.

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

Figure 2: Request with from_entity_id parameter to list immediate subordinate contained in a subseqent page.

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

Figure 3: Request to list entities of a certain type and updated since certain point in time.

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

Figure 4: Request to list all entities and only include trust marks in the response.

+
+
+
+
+
+
+

+4. Extended Subordinate Listing Response +

+

A successful response MUST use the HTTP status code 200 with the content type application/json. The response body is a JSON object containing data specified in the table below.

+ + + + + + + + + + + + + + + + + + + + + + + + +
Table 2
+ Attribute + + Availability + + Type + + Value +
immediate_subordinate_entitiesREQUIREDArrayArray of JSON objects, each describing an Immediate Subordinate Entity using the structure defined in the table below
next_entity_idOPTIONALEntity IdentifierEntity Identifier for the next element in the result list where the next page begins. This attribute is mandatory when additional results are available beyond those included in the returned immediate_subordinate_entities array.
+

Table 2: Top-level attributes included in the subordinate JSON object returned in the response body

+

Each JSON object in the returned immediate_subordinate_entities array MAY contain attributes from the sets defined for Entity Statements and Metadata in [OpenID.Federation] as well as those defined in the table below.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3
+ Attribute + + Availability + + Type + + Value +
idREQUIREDEntity IdentifierEntity Identifier for the subject entity of the current record.
entity_statementOPTIONALStringSigned entity statement for the subordinate entity as issued by the entity that exposes the extended subordinate listing endpoint.
+
+This entity_statement attribute MUST be returned if the claims parameter is NOT present in the request or it is present but the array is empty.
+
+This entity_statement attribute MUST NOT be returned if the claims parameter is NOT present in the request or it is present but the array is empty.
trust_marks, metadata, and/or other selected statement claimsOPTIONALN/ASelected Immediate Subrodianate claims as requested with the claims request attribute.
+
+These attributes MUST NOT be returned if the claims parameter is NOT present in the request or it is present but the array is empty.
registeredOPTIONALNumberTime when the Entity was registered with the issuing party using NumericDate format.
updatedOPTIONALNumberTime when the Entity was updated using the time format defined for the iat claim in [RFC7519]. This parameter may indicate that the Federation Entity Keys or metadatapolicies or constraints about this Entity was updated.
revokedOPTIONALNumberTime when the Entity was revoked using the time format defined for the iat claim in [RFC7519].
+

Table 3: Structure of the Immediate Entity JSON object in the immediate_subordinate_entities array

+

The following are non-normative examples of a JSON response from the Federation Extended List Endpoint:

+
+
GET /list_extended HTTP/1.1
+
+200 OK
+Content-Type: application/json
+
+{
+  "immediate_subordinate_entities": [
+    {
+      "id": "https://rp0.example.net/oidc/rp",
+      "entity_statement": "eyJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU2Iiwia2lkIjoiQlh2ZnJ..."
+    },
+    {
+      "id": "https://rp0.example.net/oidc/rp",
+      "entity_statement": "eyH1eZUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
+    }
+  ]
+}
+
+
+

Figure 5: Example extended list endpoint response that includes entity statements.

+
+
GET /list_extended?audit_timestamps=true&claims=entity_statement HTTP/1.1
+
+200 OK
+Content-Type: application/json
+
+{
+  "immediate_subordinate_entities": [
+    {
+      "id": "https://rp0.example.net/oidc/rp",
+      "entity_statement": "eyH1eZUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ...",
+      "registered":1704217689,
+      "updated":1704217789,
+      "revoked":1704217800
+    },
+  ]
+}
+
+
+

Figure 6: Example extended list endpoint response that includes an entity statement and audit timestampts

+
+
GET /list_extended?claims=entity_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",
+          "entity_statement": "eyH1eZUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ...",
+          "trust_mark": "eyJraWQiOiJmdWtDdUtTS3hwWWJjN09lZUk3Ynlya3N5a0E1bDhP..."
+        }
+      ]
+    }
+  ]
+}
+
+
+

Figure 7: Example extended list endpoint response that includes entity statements and trust marks

+
+
+
+
+

+5. Federation Entity Property +

+

In order for entities to advertise the new endpoint, a new property has been defined adding to the existing set of Federation Entity Metadata as defined in [OpenID.Federation].

+ + + + + + + + + + + + + + + + +
Table 4
+ Metadata + + Availability + + Description +
federation_extended_list_endpointOPTIONALThe extended list endpoint as described above. All constraints and restrictions on the listing of this endpoint are identical to that defined for the federation_list_endpoint as defined in OpenID Federation 1.0
+
+
+
+
+

+6. Examples +

+

This section contains non-normative examples that demonstrate how to use the Extended Subordinates 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/",
+      "entity_statement": "eyJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU2Iiwia2lkIjoiQlh2ZnJ..."
+    },
+    {
+      "id": "https://1.example.net/",
+      "entity_statement": "eyH1eZUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
+    },
+    ...
+    {
+      "id": "https://999.example.net/",
+      "entity_statement": "eyK2aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
+    }
+  ],
+  "next_entity_id": "https://1000.example.net/"
+}
+
+
+

Figure 8: A Trust Anchor returns the results list consisting of thousand immediate entities, along with the next entity id that the next page starts with, in response to the request to list all immediate subordinates.

+
+
GET /list_extended?from_entity_id=https://1000.example.net/ HTTP/1.1
+
+200 OK
+Content-Type: application/json
+
+{
+  "immediate_subordinate_entities": [
+    {
+      "id": "https://1000.example.net/",
+      "entity_statement": "eyK2aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
+    },
+    {
+      "id": "https://1001.example.net/",
+      "entity_statement": "eyH4aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
+    },
+    {
+      "id": "https://1003.example.net/",
+      "entity_statement": "eyW9aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ..."
+    }
+  ]
+}
+
+
+

Figure 9: A Trust Anchor returns all entities starting from the entity 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/",
+      "entity_statement": "eyJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU2Iiwia2lkIjoiQlh2ZnJ...",
+      "registered": 1704217689,
+      "updated": 1704217789,
+      "revoked": 1704217800
+    },
+    {
+      "id": "https://323.example.net/",
+      "entity_statement": "eyW9aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ...",
+      "registered": 1704217689,
+      "updated": 1704217789,
+      "revoked": 1704217800
+    },
+    ...
+    {
+      "id": "https://342.example.net/",
+      "entity_statement": "eyK2aKUkOgKlbnRpdHktc4RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU4Iiwia2lkIjoiQlh2ZnJ...",
+      "registered": 1704217689,
+      "updated": 1704217789,
+      "revoked": 1704217800
+    }
+  ],
+  "next_entity_id": "https://736.example.net/"
+}
+
+
+

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

+
+
+
+

+7. Normative References +

+
+
[RFC2119]
+
+Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
+
+
[RFC7519]
+
+Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, , <https://www.rfc-editor.org/info/rfc7519>.
+
+
[RFC7591]
+
+Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, , <https://www.rfc-editor.org/info/rfc7591>.
+
+
[RFC8174]
+
+Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
+
+
+
+
+

+8. Informative References +

+
+
[OpenID.Federation]
+
+Ed., R. H., Jones, M. B., Solberg, A., Bradley, J., Marco, G. D., and V. Dzhuvinov, "OpenID Federation 1.0", , <https://openid.net/specs/openid-federation-1_0.html>.
+
+
+
+
+
+

+Appendix A. Document History +

+

[[ To be removed from the final specification ]]

+

-00

+ +
+
+
+
+

+Authors' Addresses +

+
+
Giuseppe De Marco
+
Dipartimento per la trasformazione digitale
+ +
+
+
Michael Fraser
+
Raidiam
+ +
+
+
Lukasz Jaromin
+
Raidiam
+ +
+
+
Michael B. Jones
+
Self-Issued Consulting
+ +
+
+
+ + +