OpenID Federation Subordinate Events Endpoint 1.0 - draft 00

2.1.1. Endpoint Location

The location of the Federation Subordinate Events Endpoint is published in the federation_entity metadata, using the federation_subordinate_events_endpoint parameter.¶

The following is a non-normative example of an Entity Configuration payload, for an Immediate Superior that includes the federation_subordinate_events_endpoint:¶

{
  "iss": "https://immediate-superior.example.org",
  "sub": "https://immediate-superior.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://immediate-superior.example.org/fetch",
      "federation_list_endpoint": "https://immediate-superior.example.org/list",
      "federation_subordinate_events_endpoint": "https://immediate-superior.example.org/events",
      "federation_resolve_endpoint": "https://immediate-superior.example.org/resolve"
    }
  }
}

2.2.1. Request Format

The request to the federation_subordinate_events_endpoint MUST be an HTTP GET request with the following query parameters, encoded in application/x-www-form-urlencoded format:¶

• sub: (REQUIRED) The Entity Identifier of the subject for which the historical track is being requested.¶

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

GET /federation_subordinate_events_endpoint?sub=https%3A%2F%2Frp%2Eexample%2Eorg HTTP/1.1
Host: immediate-superior.example.org

2.3.1. Response Format

A successful response MUST use the HTTP status code 200 and the content type application/entity-events-statement+jwt. The response includes relevant events from the federation's perspective of the Entity. If it is a negative response, it will be a JSON object and the content type MUST be application/json and use the errors defined in [OpenID.Federation].¶

The response is a signed JWT that is explicitly typed by setting the typ header parameter to entity-events-statement+jwt to prevent cross-JWT confusion. It is signed with a Federation Entity Key.¶

2.3.2. JWT Claims

The claims in the Subordinate events statement response are:¶

• iss: (REQUIRED) String. Entity Identifier of the issuer of the response.¶
• sub: (REQUIRED) String. Entity Identifier of the subject of the response.¶
• iat: (REQUIRED) Number. Time when this response was issued, expressed as Seconds Since the Epoch.¶
• exp: (OPTIONAL) Number. Time when this resolution is no longer valid, expressed as Seconds Since the Epoch.¶
• federation_registration_events: (REQUIRED) Array of JSON objects, each representing an event of particular interest from the federation's perspective.¶

{
  "iss": "https://immediate-superior.example.org",
  "sub": "https://rp.example.org",
  "iat": 1590000000,
  "federation_registration_events": [
    {
      "iat": 1590000000,
      "event": "registration"
    },
    {
      "iat": 1590000000,
      "event": "jwks_updates"
    },
    {
      "iat": 1600000000,
      "event": "revocation",
      "event_description": "compromised node"
    },
    {
      "iat": 1610000000,
      "event": "registration"
    }
  ]
}

2.3.3. Subordinate Event Types

The following event types are defined in this specification:¶

• metadata_policy_update: Indicates when an Entity's metadata policy was updated in the Subordinate Statement about that entity, using the metadata_policy parameter.¶
• metadata_update: Indicates when an Entity's metadata was updated in the Subordinate Statement about that entity, using the metadata parameter.¶
• registration: Indicates when an Entity was registered in the federation. When a registration event is present, metadata_update, metadata_policy_update, and jwks_update events MUST NOT be provided at the same time, since the Entity registration is assumed to configure the initial configuration about that Entity.¶
• revocation: Indicates when an Entity's registration was revoked.¶
• suspension: Indicates when an Entity's registration was suspended.¶
• jwks_update: Indicates when an Entity's Federation Entity Keys were updated.¶

Additional event types MAY be defined by trust frameworks or federation operators to meet specific requirements. Such custom event types SHOULD be documented in the respective trust framework or federation operator's documentation.¶