Management API for SET Event StreamsGooglemscurtescu@google.comAmazonrichanna@amazon.com
Security
seceventInternet-DraftSecurity Event Token (SET) delivery requires event receivers to indicate
to event transmitters the subjects about which they wish to receive
events, and how they wish to receive them. This specification defines an HTTP
API for a basic control plane that event transmitters can implement and
event receivers may use to manage the flow of events from one to the
other.This specification defines an HTTP API to be implemented by Event Transmitters
and that can be used by Event Receivers to query the Event Stream status, to
add and remove subjects and to trigger verification.How events are delivered and the structure of events are not in scope for this
specification.The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”,
“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this
document are to be interpreted as described in .In addition to terms defined in , this
specification uses the following terms:
A JSON object containing a set of one or more claims about a subject that
when taken together uniquely identify that subject. This set of claims
SHOULD be declared as an acceptable way to identify subjects of SETs by
one or more specifications that profile .Event Receivers manage how they receive events, and the subjects about which
they want to receive events over an Event Stream by making HTTP requests to
endpoints in the Event Stream Management API.The Event Stream Management API is implemented by the Event Transmitter and
consists of the following endpoints:
An endpoint used to read the Event Stream’s current configuration.
An endpoint used to read the Event Stream’s current status.
An endpoint used to add subjects to an Event Stream.
An endpoint used to remove subjects from an Event Stream.
An endpoint used to request the Event Transmitter transmit a Verification
Event over the Event Stream.An Event Transmitter MAY use the same URLs as endpoints for multiple streams,
provided that the Event Transmitter has some mechanism through which they can
identify the applicable Event Stream for any given request, e.g. from
authentication credentials. The definition of such mechanisms is outside the
scope of this specification.An Event Stream’s configuration is represented as a JSON object with the
following properties:
A string containing an audience claim as defined in JSON Web Token
(JWT) that identifies the Event Receiver for the Event Stream.
This property cannot be updated.
OPTIONAL. An array of URIs identifying the set of events which MAY be
delivered over the Event Stream. If omitted, Event Transmitters SHOULD make
this set available to the Event Receiver via some other means (e.g.
publishing it in online documentation).
A JSON object containing a set of name/value pairs specifying configuration
parameters for the SET delivery method. The actual delivery method is
identified by the special key “delivery_method” with the value being a URI as
defined in .
An integer indicating the minimum amount of time in seconds that must pass
in between verification requests. If an Event Receiver submits verification
requests more frequently than this, the Event Transmitter MAY respond with a
429 status code. An Event Transmitter SHOULD NOT respond with a 429 status
code if an Event Receiver is not exceeding this frequency.
A string indicating the current status of the event stream. It MUST have one
of the following values:
The transmitter will transmit events over the stream, according to the
stream’s configured delivery method.
The transmitter will not transmit events over the stream. The transmitter
will hold any events it would have transmitted while paused, and will
transmit them when the stream’s status becomes “enabled”.
The transmitter will not transmit events over the stream, and will not
hold any events for later transmission.An Event Receiver checks the current status of an event stream by making an
HTTP GET request to the stream’s Status Endpoint. On receiving a valid request
the Event Transmitter responds with a 200 OK response containing a
object with a single attribute “status”, whose string value is the value of
the stream’s status.The following is a non-normative example request to check an event stream’s
status:The following is a non-normative example response: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
representation of the stream’s configuration in the body.The following is a non-normative example request to read an Event Stream’s
configuration:The following is a non-normative example response:Errors are signaled with HTTP staus codes as follows:CodeDescription401if authorization failed or it is missing403if the Event Receiver is not allowed to read the stream configuration404if there is no Event Stream configured for this Event ReceiverAn 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} representation of the updated configuration. On receiving a valid
request the Event Transmitter responds with a 200 OK response containing a
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 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 read an Event Stream’s
configuration:The following is a non-normative example response:Errors are signaled with HTTP staus codes as follows:CodeDescription400if the request body cannot be parsed or if the request is otherwise invalid401if authorization failed or it is missing403if the Event Receiver is not allowed to update the stream configurationAn Event Receiver can indicate to an Event Transmitter whether or not the
receiver wants to receive events about a particular subject by “adding” or
“removing” that subject to the Event Stream, respectively.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 Subject
Identifier Object identifying the subject to be added. 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).Errors are signaled with HTTP staus codes as follows:CodeDescription400if the request body cannot be parsed or if the request is otherwise invalid401if authorization failed or it is missing403if the Event Receiver is not allowed to add this particular subject404if the subject is not recognized by the Event Transmitter, the Event Transmitter may chose to stay silent in this case and respond with 200429if the Event Receiver is sending too many requests in a gvien amount of timeThe following is a non-normative example request to add a subject to a
stream, where the subject is identified by an OpenID Connect email claim:The following is a non-normative example response to a successful request: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 Subject
Identifier Object 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 staus codes as follows:CodeDescription400if the request body cannot be parsed or if the request is otherwise invalid401if authorization failed or it is missing403if the Event Receiver is not allowed to remove this particular subject404if the subject is not recognized by the Event Transmitter, the Event Transmitter may chose to stay silent in this case and respond with 204429if the Event Receiver is sending too many requests in a gvien amount of timeThe following is a non-normative example request where the subject is
identified by a phone_number claim:The following is a non-normative example response to a successful request:In some cases, the frequency of event transmission on an Event Stream will
be very low, making it difficult for an Event Receiver to tell the
difference between expected behavior and event transmission failure due to a
misconfigured stream. Event Receivers can request that a verification event
be transmitted over the Event Stream, allowing the receiver to confirm that
the stream is configured correctly upon successful receipt of the event. The
acknowledgment of a Verification Event also confirms to the Event Transmitter
that end-to-end delivery is working, including signature verification and
encryption.An Event Transmitter MAY send a Verification Event at any time, even if one
was not requested by the Event Receiver.The Verification Event is a standard SET with the following attributes:
The Event Type URI is:
“urn:ietf:params:secevent:event-type:core:verification”.
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.4 of
).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.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
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:
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 staus codes as follows:CodeDescription400if the request body cannot be parsed or if the request is otherwise invalid401if authorization failed or it is missing429if the Event Receiver is sending too many requests in a gvien amount of timeThe following is a non-normative example request to trigger a verification
event:The following is a non-normative example response to a successful request:And the following is a non-normative example of a verification event sent to
the Event Receiver as a result of the above request:It may be possible for an Event Transmitter to leak information about subjects
through their responses to add subject requests. A 404 response may indicate
to the Event Receiver that the subject does not exist, which may inadvertantly
reveal information about the subject (e.g. that a particular individual does
or does not use the Event Transmitter’s service).Event Transmitters SHOULD carefully evaluate the conditions under which they
will return error responses to add subject requests. Event Transmitters MAY
return a 204 response even if they will not actually send any events related
to the subject, and Event Receivers MUST NOT assume that a 204 response means
that they will receive events related to the subject.SETs may contain personally identifiable information (PII) or other non-public
information about the event transmitter, the subject (of an event in the SET),
or the relationship between the two. It is important for Event Transmitters to
understand what information they are revealing to Event Receivers when
transmitting events to them, lest the event stream become a vector for
unauthorized access to private information.Event Transmitters SHOULD interpret add subject requests as statements of
interest in a subject by an Event Receiver, and ARE NOT obligated to transmit
events related to every subject an Event Receiver adds to the stream. Event
Transmitters MAY choose to transmit some, all, or no events related to any
given subject and SHOULD validate that they are permitted to share the
information contained within an event with the Event Receiver before
transmitting the event. The mechanisms by which such validation is performed
are outside the scope of this specification.A malicious party may find it advantageous to remove a particular subject from
a stream, in order to reduce the Event Receiver’s ability to detect
malicious activity related to the subject, inconvenience the subject, or for
other reasons. Consequently it may be in the best interests of the subject for
the Event Transmitter to continue to send events related to the subject for
some time after the subject has been removed from a stream.Event Transmitters MAY continue sending events related to a subject for some
amount of time after that subject has been removed from the stream. Event
Receivers MUST tolerate receiving events for subjects that have been removed
from the stream, and MUST NOT report these events as errors to the Event
Transmitter.The JavaScript Object Notation (JSON) Data Interchange FormatJavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data.This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance.JSON Web Token (JWT)JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted.Security Event Token (SET)SET Token Delivery Using HTTPKey words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.