OpenID Shared Signals and Events Framework Specification 1.0

7.1.1.1. Reading a Stream's Status

An Event Receiver checks the current status of an event stream by making an HTTP GET request to the stream's Status Endpoint.¶

The Stream Status method takes the following parameters:¶

subject

OPTIONAL. The subject for which the stream status is requested.¶

On receiving a valid request the Event Transmitter responds with a 200 OK response containing a JSON [RFC7159] object with an attribute status, whose string value MUST have one of the following values:¶

enabled

The Transmitter MUST transmit events over the stream, according to the stream's configured delivery method.¶

paused

The Transmitter MUST NOT transmit events over the stream. The transmitter will hold any events it would have transmitted while paused, and SHOULD transmit them when the stream's status becomes enabled. If a Transmitter holds successive events that affect the same Subject Principal, then the Transmitter MUST make sure that those events are transmitted in the order of time that they were generated OR the Transmitter MUST send only the last events that do not require the previous events affecting the same Subject Principal to be processed by the Receiver, because the previous events are either cancelled by the later events or the previous events are outdated.¶

disabled

The Transmitter MUST NOT transmit events over the stream, and will not hold any events for later transmission.¶

The following is a non-normative example request to check an event stream's status:¶

GET /sse/status HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer zzzz

The following is a non-normative example response:¶

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "status": "enabled"
}

The following is a non-normative example request to check an event stream's status for a specific subject:¶

GET /sse/status?subject=<url-encoded-subject> HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

The following is a non-normative example response with a Subject claim:¶

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "status": "enabled",
  "subject": {
    "tenant" : {
      "format" : "iss_sub",
      "iss" : "http://example.com/idp1",
      "sub" : "1234"
    }
  }
}

Errors are signaled with HTTP status codes as follows:¶

Examples:¶

1. If a Receiver makes a request with an invalid OAuth token, then the Transmitter MUST respond with a 401 error status.¶
2. If the Receiver presents a valid OAuth token, but the Transmitter policy does not permit the Receiver from obtaining the status, then the Transmitter MAY respond with a 403 error status.¶
3. If the Receiver requests the status for specific Subject, but the Transmitter policy does not permit the Receiver to read the status of that Subject, then the Transmitter MAY respond with a 404 error status in order to not reveal the policy decision.¶
4. If the specified Subject is invalid then the Transmitter MUST respond with a 404 error status.¶

7.1.1.2. Updating a Stream's Status

An Event Receiver updates the current status of a stream by making an HTTP POST request to the Status Endpoint. The POST body contains a JSON [RFC7159] object with the following fields:¶

status

REQUIRED. The new status of the Event Stream.¶

subject

OPTIONAL. The Subject to which the new status applies.¶

reason

OPTIONAL. A short text description that explains the reason for the change.¶

On receiving a valid request the Event Transmitter responds with a 200 OK response containing a JSON [RFC7159] representation of the updated stream status in the body.¶

The following is a non-normative example request to update an Event Stream's status:¶

POST /sse/status HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

{
  "status": "paused"
}

The following is a non-normative example of an Update Stream Status request with optional fields:¶

POST /sse/status HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

{
  "status": "paused",
  "subject": {
    "tenant" : {
      "format" : "iss_sub",
      "iss" : "http://example.com/idp1",
      "sub" : "1234"
    }
  },
  "reason": "Disabled by administrator action."
}

The following is a non-normative example response:¶

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "status": "paused"
}

Errors are signaled with HTTP status codes as follows:¶

Example:¶

1. If a Receiver makes a request to update the stream to enable it for a specific Subject, and the Transmitter is unable to decide whether or not to complete the request, then the Transmitter MUST respond with a 202 status code.¶

7.1.2.1. Reading a Stream's Configuration

An Event Receiver gets the current configuration of a stream by making an HTTP GET request to the Configuration Endpoint. On receiving a valid request the Event Transmitter responds with a 200 OK response containing a JSON [RFC7159] representation of the stream's configuration in the body.¶

The following is a non-normative example request to read an Event Stream's configuration:¶

GET /sse/stream HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

The following is a non-normative example response:¶

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "iss": "https://tr.example.com",
  "aud": [
      "http://receiver.example.com/web",
      "http://receiver.example.com/mobile"
    ],
  "delivery": {
    "delivery_method":
      "https://schemas.openid.net/secevent/risc/delivery-method/push",
      "url": "https://receiver.example.com/events"
  },
  "events_supported": [
    "urn:example:secevent:events:type_1",
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3"
  ],
  "events_requested": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3",
    "urn:example:secevent:events:type_4"
  ],
  "events_delivered": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3"
  ]
}

Errors are signaled with HTTP status codes as follows:¶

7.1.2.2. Updating a Stream's Configuration

An Event Receiver updates the current configuration of a stream by making an HTTP POST request to the Configuration Endpoint. The POST body contains a JSON [RFC7159] representation of the updated configuration. On receiving a valid request the Event Transmitter responds with a 200 OK response containing a JSON [RFC7159] representation of the updated stream configuration in the body.¶

The full set of editable properties must be present in the POST body, not only the ones that are specifically intended to be changed. Missing properties SHOULD be interpreted as requested to be deleted. Event Receivers should read the configuration first, modify the JSON [RFC7159] representation, then make an update request.¶

Properties that cannot be updated MAY be present, but they MUST match the expected value.¶

The following is a non-normative example request to update an Event Stream's configuration:¶

POST /sse/stream HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

{
  "iss": "https://tr.example.com",
  "aud": [
    "http://receiver.example.com/web",
    "http://receiver.example.com/mobile"
  ],
  "delivery": {
    "delivery_method":
      "https://schemas.openid.net/secevent/risc/delivery-method/push",
      "url": "https://receiver.example.com/events"
  },
  "events_requested": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3",
    "urn:example:secevent:events:type_4"
  ]
}

The following is a non-normative example response:¶

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "iss": "https://tr.example.com",
  "aud": [
    "http://receiver.example.com/web",
    "http://receiver.example.com/mobile"
  ],
  "delivery": {
    "delivery_method":
      "https://schemas.openid.net/secevent/risc/delivery-method/push",
      "url": "https://receiver.example.com/events"
  },
  "events_supported": [
    "urn:example:secevent:events:type_1",
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3"
  ],
  "events_requested": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3",
    "urn:example:secevent:events:type_4"
  ],
  "events_delivered": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3"
  ]
}

Pending conditions or errors are signaled with HTTP status codes as follows:¶

7.1.2.3. Removing a Stream Configuration

An Event Receiver removes the configuration of a stream by making an HTTP DELETE request to the Configuration Endpoint. On receiving a request the Event Transmitter responds with a 200 OK response if the configuration was successfully removed.¶

The following is a non-normative example request to remove an Event Stream's configuration:¶

DELETE /sse/stream HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

Errors are signaled with HTTP status codes as follows:¶

7.1.3.1. Adding a Subject to a Stream

To add a subject to an Event Stream, the Event Receiver makes an HTTP POST request to the Add Subject Endpoint, containing in the body a JSON object the following claims:¶

subject

REQUIRED. A Subject claim identifying the subject to be added.¶

verified

OPTIONAL. A boolean value; when true, it indicates that the Event Receiver has verified the Subject claim. When false, it indicates that the Event Receiver has not verified the Subject claim. If omitted, Event Transmitters SHOULD assume that the subject has been verified.¶

On a successful response, the Event Transmitter responds with an empty 200 OK response. The Event Transmitter MAY choose to silently ignore the request, for example if the subject has previously indicated to the transmitter that they do not want events to be transmitted to the Event Receiver. In this case, the transmitter MAY return an empty 200 OK response or an appropriate error code. See Security Considerations (Section 9).¶

Errors are signaled with HTTP status codes as follows:¶

The following is a non-normative example request to add a subject to a stream, where the subject is identified by an Email Subject Identifier.¶

POST /sse/subjects:add HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

{
  "subject": {
    "format": "email",
    "email": "example.user@example.com"
  },
  "verified": true
}

The following is a non-normative example response to a successful request:¶

HTTP/1.1 200 OK
Server: transmitter.example.com
Cache-Control: no-store
Pragma: no-cache

7.1.3.2. Removing a Subject

To remove a subject from an Event Stream, the Event Receiver makes an HTTP POST request to the Remove Subject Endpoint, containing in the body a JSON object with the following claims:¶

subject

REQUIRED. A Subject claim identifying the subject to be removed.¶

On a successful response, the Event Transmitter responds with a 204 No Content response.¶

Errors are signaled with HTTP status codes as follows:¶

The following is a non-normative example request where the subject is identified by a Phone Number Subject Identifier:¶

POST /sse/subjects:remove HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

{
  "subject": {
    "format": "phone",
    "phone_number": "+1 206 555 0123"
  }
}

The following is a non-normative example response to a successful request:¶

HTTP/1.1 204 No Content
Server: transmitter.example.com
Cache-Control: no-store
Pragma: no-cache

7.1.4.1. Verification Event

The Verification Event is a standard SET with the following attributes:¶

event type

The Event Type URI is: https://schemas.openid.net/secevent/sse/event-type/verification.¶

state

OPTIONAL An opaque value provided by the Event Receiver when the event is triggered. This is a nested attribute in the event payload.¶

Upon receiving a Verification Event, the Event Receiver SHALL parse the SET and validate its claims. In particular, the Event Receiver SHALL confirm that the value for state is as expected. If the value of state does not match, an error response of setData SHOULD be returned (see Section 2.3 of [DELIVERYPUSH] or [DELIVERYPOLL]).¶

In many cases, Event Transmitters MAY disable or suspend an Event Stream that fails to successfully verify based on the acknowledgement or lack of acknowledgement by the Event Receiver.¶

7.1.4.2. Triggering a Verification Event.

To request that a verification event be sent over an Event Stream, the Event Receiver makes an HTTP POST request to the Verification Endpoint, with a JSON [RFC7159] object containing the parameters of the verification request, if any. On a successful request, the event transmitter responds with an empty 204 No Content response.¶

Verification requests have the following properties:¶

state

OPTIONAL. An arbitrary string that the Event Transmitter MUST echo back to the Event Receiver in the verification event's payload. Event Receivers MAY use the value of this parameter to correlate a verification event with a verification request. If the verification event is initiated by the transmitter then this parameter MUST not be set.¶

A successful response from a POST to the Verification Endpoint does not indicate that the verification event was transmitted successfully, only that the Event Transmitter has transmitted the event or will do so at some point in the future. Event Transmitters MAY transmit the event via an asynchronous process, and SHOULD publish an SLA for verification event transmission times. Event Receivers MUST NOT depend on the verification event being transmitted synchronously or in any particular order relative to the current queue of events.¶

Errors are signaled with HTTP status codes as follows:¶

The following is a non-normative example request to trigger a verification event:¶

POST /sse/verify HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
Content-Type: application/json; charset=UTF-8

{
  "state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo="
}

The following is a non-normative example response to a successful request:¶

HTTP/1.1 204 No Content
Server: transmitter.example.com
Cache-Control: no-store
Pragma: no-cache

And the following is a non-normative example of a verification event sent to the Event Receiver as a result of the above request:¶

{
  "jti": "123456",
  "iss": "https://transmitter.example.com",
  "aud": "receiver.example.com",
  "iat": 1493856000,
  "events": {
    "https://schemas.openid.net/secevent/sse/event-type/verification":{
      "state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo="
    }
  }
}