OpenID Federation Entity Collection Endpoint 1.0 - draft 00

2.1.1. Endpoint Location

The location of the Federation Entity Collection Endpoint is published in the federation_entity metadata, using the federation_collection_endpoint parameter.¶

The following is a non-normative example of an Entity Configuration payload, for an Trust Anchor that includes the federation_collection_endpoint:¶

{
  "iss": "https://ta.example.org",
  "sub": "https://ta.example.org",
  "iat": 1590000000,
  "exp": 1590086400,
  "jwks": {
    "keys": [
      {
        "kty": "RSA",
        "kid": "key1",
        "use": "sig",
        "n": "n4EPtAOCc9AlkeQHPzHStgAbgs7bTZLwUBZdR8_KuKPEHLd4rHVTeT",
        "e": "AQAB"
      }
    ]
  },
  "metadata": {
    "federation_entity": {
      "federation_fetch_endpoint": "https://ta.example.org/fetch",
      "federation_list_endpoint": "https://ta.example.org/list",
      "federation_resolve_endpoint": "https://ta.example.org/resolve",
      "federation_collection_endpoint": "https://ta.example.org/entities"
    }
  }
}

2.2.1. Request Format

When client authentication is not used, the request to the federation_collection_endpoint MUST be an HTTP request using the GET method with the following query parameters, encoded in application/x-www-form-urlencoded format:¶

• from_entity_id: (OPTIONAL) If 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 parameter.
  If the Entity Identifier in this parameter is not or not longer known to the responder, it MUST use the HTTP status code 404 and the content type application/json with the error code entity_id_not_found.
  If the responder does not support this feature, it MUST use the HTTP status code 400 and the content type application/json, with the error code unsupported_parameter.¶

• limit: (OPTIONAL) Requested 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 responder’s upper limit and the value of this parameter. If this parameter is not present the server MUST fall back on the upper limit.
  If the responder does not support this feature, it MUST use the HTTP status code 400 and the content type application/json, with the error code unsupported_parameter.¶

• entity_type: (OPTIONAL) The value of this parameter is an Entity Type Identifier. The result MUST be filtered to include only those entities that include the specified Entity Type. When multiple entity_type parameters are present, for example entity_type=openid_provider&entity_type=openid_relying_party, the result MUST be filtered to include all specified Entity Types. If the responder does not support this feature, it MUST use the HTTP status code 400 and the content type application/json, with the error code unsupported_parameter.¶

• trust_mark_type: (OPTIONAL) The value of this parameter is a Trust Mark Type Identifier. The list in the response is filtered to include only Entities that publish a Trust Mark with this Trust Mark Type in their Entity Configuration and is verified by the responder. The responder SHOULD verify the Trust Mark using the same Trust Anchor that is used to collect the Entities. When multiple trust_mark_type parameters are present, the result MUST be filtered to include all specified Trust Marks.
  If the responder does not support this feature, it MUST use the HTTP status code 400 and set the content type to application/json, with the error code unsupported_parameter.¶

• trust_anchor: (RECOMMENDED) The Trust Anchor that the collection endpoint MUST use when collecting Entities. The value is an Entity Identifier. If omitted, the responder sets this parameter to its own Entity Identifier. If the responder does not have a defined Entity Identifier, it MUST use the HTTP status code 400 and set the content type to application/json, with the error code invalid_request.¶

• query: (OPTIONAL) The value of this parameter is used by the responder to filter down the list of returned Entities to only entities that match this parameter value. It is entirely up to the responder to define when an Entity matches the query.
  If the responder does not support this feature, it SHOULD use the HTTP status code 400 and the content type application/json, with the error code unsupported_parameter.¶

• claims: (OPTIONAL) Array of claims to be included in the response for each returned Entity. If this parameter is NOT present it is at the discretion of the responder which claims are included or not.
  If this parameter is present and it is NOT an empty array, each JSON object that represents an Entity MUST include the requested claims if available.
  If the responder does not support a requested claim, it MUST use the HTTP status code 400 and set the content type to application/json, with the error code unsupported_parameter.¶

When Client authentication is used, the request MUST be an HTTP request using the POST method, with the parameters passed in the POST body.¶

GET /collection?entity_type=openid_provider&trust_mark_type=https%3A%2F%2Frp%2Erefeds.org%2Fsitfi&trust_anchor=https%3A%2F%2Fswamid.se HTTP/1.1
Host: openid.sunet.se

2.3.1. Response Format

A successful response MUST use the HTTP status code 200 and the content type application/json.¶

The response is a JSON object as described below.¶

If the response is negative, it will be a JSON object and the content type MUST be application/json and use the errors defined here or in [OpenID.Federation].¶

2.3.2. Response Claims

The claims in the entity collection response are:¶

• entities: (REQUIRED) Array of JSON objects, each representing an Federation Entity using the format described below. The list of Entities MUST only contain Entities that are in line with the requested parameters. The responder MAY also filter down the list further at its own discretion.¶
• next_entity_id: (OPTIONAL) Entity Identifier for the next element in the result list where the next page begins. This attribute is REQUIRED when additional results are available beyond those included in the entities array.¶
• last_updated: (RECOMMENDED) Number. Time when the responder last updated the result list. This is expressed as Seconds Since the Epoch, per [RFC7519]. If the last_updated time changes between paginated calls, this might be an indication for the client that it might have received outdated information in a previous call.¶

Additional claims MAY be defined and used in conjunction with the claims above.¶

{
  "federation_entities": [
    {
      "entity_id": "https://green.example.com",
      "entity_types": [
        "federation_entity"
      ],
      "ui_infos": {
        "federation_entity": {
          "display_name": "The green organization",
          "logo_uri": "https://green.example.com/logo.png"
        }
      }
    },
    {
      "entity_id": "https://red.example.com",
      "entity_types": [
        "openid_relying_party",
        "federation_entity"
      ],
      "ui_infos": {
        "federation_entity": {
          "display_name": "Red Organization",
          "logo_uri": "https://red.example.com/logo.png"
        },
        "openid_relying_party": {
          "display_name": "Red RP",
          "logo_uri": "https://red.example.com/logo.png"
        }
      }
    },
    {
      "entity_id": "https://op.example.com",
      "entity_types": [
        "openid_provider"
      ]
    }
  ]
}