Poll-Based Security Event Token (SET) Delivery Using HTTPAmazonrichanna@amazon.comMicrosoftmbj@microsoft.comhttp://self-issued.info/Coinbasemarius.scurtescu@coinbase.comCiscomorteza.ansari@cisco.comMicrosofttonynad@microsoft.comInternet-Draft
This specification defines how a series of Security Event Tokens
(SETs) may be delivered to an intended recipient
using HTTP POST over TLS initiated as a poll by the recipient. The
specification also defines how delivery can be assured, subject to
the SET Recipient's need for assurance.
This specification defines how a stream of
Security Event Tokens (SETs)
can be transmitted to an intended
SET Recipient using HTTP
over TLS. The specification defines a method to poll for SETs
using HTTP POST.
A mechanism for exchanging configuration metadata such as endpoint URLs
and cryptographic key parameters between the transmitter and recipient is
out of scope for this specification. How SETs are defined and the process
by which events are identified for SET Recipients is also out of scope for
this specification.
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
when, and only when, they appear in all capitals, as shown here.
Throughout this document, all figures MAY contain spaces and
extra
line wrapping for readability and due to space limitations.
This specification utilizes terminology defined in
and .
When a SET is available for a SET Recipient, the SET Transmitter
attempts to deliver the SET
by queueing the SET in a buffer so that
a SET Recipient can poll for SETs using HTTP/1.1 POST.
In Poll-Based SET Delivery Using HTTP, zero or more SETs are
delivered in a JSON document
to a SET Recipient in response to an HTTP POST request to the
SET Transmitter. Then in a following request, the SET Recipient
acknowledges received SETs and can poll for more. All requests and
responses are JSON documents and use a
Content-Type of
application/json, as described in
.
After successful (acknowledged) SET delivery, SET
Transmitters are not required to retain or record SETs for
retransmission. Once a SET is acknowledged, the SET Recipient SHALL be
responsible for retention, if needed.Transmitted SETs SHOULD be self-validating (signed)
if there is a requirement to verify they were issued by the SET
Transmitter at a later date when de-coupled from the original
delivery where authenticity could be checked via the HTTP or
TLS mutual authentication.
Upon receiving a SET, the SET Recipient reads the SET and validates
it in the manner described in Section 2 of .
The SET Recipient MUST acknowledge receipt to the SET Transmitter.
The SET Recipient SHALL NOT use the event acknowledgement mechanism
to report event errors other than those relating to the parsing and
validation of the SET.
This method allows a SET Recipient to use HTTP POST
(Section 4.3.3 of ) to acknowledge
SETs and to check for and receive zero or more SETs. Requests
MAY be made at a periodic interval (short polling) or requests
MAY wait, pending availability of new SETs using long polling,
per Section 2 of .The delivery of SETs in this method is facilitated by HTTP
POST requests initiated by the SET Recipient in which:The SET Recipient makes a request for available SETs
using an HTTP POST to a pre-arranged endpoint provided by the SET
Transmitter or,after validating previously received SETs, the SET Recipient
initiates another poll request using HTTP POST that includes
acknowledgement of previous SETs and waits for the next batch
of SETs.The purpose of the acknowledgement is to inform the
SET Transmitter that delivery has succeeded and
redelivery is no longer required. Before acknowledgement, SET
Recipients SHOULD ensure that received SETs have been validated and
retained in a manner appropriate to the recipient's
requirements. The level and method of retention of SETs
by SET Recipients is out of scope of this specification.When initiating a poll request, the SET Recipient constructs
a JSON document that consists of polling request parameters
and SET acknowledgement parameters in the form of JSON objects.
The request payloads are delivered in a JSON document, as described
in and .
When making a request, the HTTP header Content-Type
is set to application/json.The following JSON object members are used in a polling request:
An OPTIONAL JSON integer value
indicating the maximum number of unacknowledged SETs that
SHOULD be returned. If more than the maximum number of SETs
are available, the oldest SETs available SHOULD be returned
first. A value of 0 MAY be used by
SET Recipients that would like to perform an acknowledge only
request. This enables the Recipient to use separate HTTP requests
for acknowledgement and reception of SETs.
If this parameter is omitted, no limit is placed on
the number of SETs to be returned.
An OPTIONAL JSON
boolean value that indicates the SET Transmitter SHOULD return
an immediate response even if no results are available
(short polling). The default value is false,
which indicates the request is to be treated as an HTTP Long Poll,
per Section 2 of . The timeout for the
request is part of the configuration between the participants, which is out of
scope of this specification.An array of strings that each
corresponds to the jti of a
successfully received SET. If there are no
outstanding SETs to acknowledge, the member MAY be omitted.
When acknowledging a SET, the SET Transmitter is released from
any obligation to retain the SET.A JSON Object that contains
one or more nested JSON object members that correspond to the
jti of each invalid SET received.
The value of each is a JSON object whose contents is an
err member and
description member, whose values
correspond to the errors described in .In response to a poll request, the SET Transmitter checks for
available SETs and responds with a JSON document containing
the following JSON object members:
A JSON object that contains zero
or more nested JSON objects. Each nested JSON object's key
corresponds to the jti of a SET to
be delivered, and its value is a JSON string containing the
value of the encoded corresponding SET. If there are no
outstanding SETs to be transmitted, the JSON object SHALL be
empty.A JSON boolean value that
indicates if more unacknowledged SETs are available to be returned.
When making a response, the HTTP header Content-Type
is set to application/json.The SET Recipient performs an HTTP POST (see
Section 4.3.4 of ) to a pre-arranged
polling endpoint URI to check for SETs that are available.
Because the SET Recipient has no prior SETs to
acknowledge, the ack and
errs request parameters are omitted.If after a period of time, negotiated between the SET
Transmitter and Recipient, a SET Transmitter MAY redeliver SETs
it has previously delivered. The SET Recipient SHOULD accept
repeat SETs and acknowledge the SETs regardless of whether the
Recipient believes it has already acknowledged the SETs previously.
A SET Transmitter MAY limit the number of times it attempts to
deliver a SET.
If the SET Recipient has received SETs from the
SET Transmitter, the SET Recipient SHOULD parse and validate
received SETs to meet its own requirements and SHOULD acknowledge
receipt in a timely fashion (e.g., seconds or minutes) so that the SET
Transmitter can mark the SETs as received. SET Recipients SHOULD
acknowledge receipt before taking any local actions based on
the SETs to avoid unnecessary delay in acknowledgement, where
possible.Poll requests have three variations:
In which a SET Recipient
asks for the next set of events where no previous SET deliveries
are acknowledged (such as in the initial poll request).In which a SET
Recipient sets the maxEvents
value to 0 along with
ack and
err members indicating the
SET Recipient is acknowledging previously received SETs and
does not want to receive any new SETs in response to the
request. In
which a SET Recipient is both acknowledging previously
received SETs using the ack and
err members
and will wait for the next group of SETs in the SET Transmitters
response.In the case where no SETs were received in a previous poll (see
), the SET Recipient simply
polls without acknowledgement parameters (sets
and setErrs).A SET Recipient can poll using default parameter values by passing
an empty JSON object.In this variation, the SET Recipient acknowledges previously
received SETs and indicates it does not want to receive SETs in
response by setting the maxEvents
value to 0.This variation might be used, for instance, when a SET Recipient needs to
acknowledge received SETs independently (e.g., on separate threads)
from the process of receiving SETs.This variation allows a recipient thread to simultaneously
acknowledge previously received SETs and wait for the next
group of SETs in a single request.In the above acknowledgement, the SET Recipient has acknowledged
receipt of two SETs and has indicated it wants to wait until
the next SET is available.In the case where errors were detected in previously
delivered SETs, the SET Recipient MAY use the
setErrs member to communicate the errors
in the following poll request.
In response to a poll request, the service provider MAY
respond immediately if SETs are available to be delivered.
If no SETs are available at the time of the request, the
SET Transmitter SHALL delay responding until a SET is
available or the timeout interval has elapsed unless the poll request parameter
returnImmediately is true.As described in , a JSON document
is returned containing a number of members including
sets, which SHALL contain zero or more
SETs.In the above example, two SETs whose jti values
are 4d3559ec67504aaba65d40b0363faad8
and 3d0c3cf797584bd193bd0fb1bd4e7d30
are delivered.Upon receiving the JSON document (e.g., as shown in
), the SET Recipient parses
and verifies the received SETs and notifies the SET Transmitter
via the next poll request to the SET Transmitter, as described in
or .
If a SET is invalid,
error codes from the IANA "Security Event Token Delivery Error Codes"
registry established by
are used in error responses.
As described in Section 2.3 of ,
an error response is a JSON object providing details about the error
that includes the following name/value pairs:
A value from the
IANA "Security Event Token Delivery Error Codes" registry
that identifies the error.
A human-readable string that provides
additional diagnostic information.
When included as part of a batch of SETs, the above JSON is included
as part of the setErrs member, as
defined in and .
When the SET Recipient includes one or more error responses in a request to
the SET Transmitter, it must also include in the request a
Content-Language header whose value indicates the
language of the error descriptions included in the request. The method of
language selection in the case when the SET Recipient can provide error messages
in multiple languages is out of scope for this specification.
The SET delivery method described in this specification is
based upon HTTP and depends on the use of TLS and/or standard
HTTP authentication and authorization schemes, as per
.
As per Section 4.1 of , a SET
delivery endpoint SHALL indicate supported HTTP authentication
schemes via the WWW-Authenticate header.
Authorization for the ability to pick-up or deliver SETs can be determined by
using the identity of the SET issuer, or via an authentication
method above. This specification considers authentication as a
feature to prevent denial-of-service attacks. Because SETs are
not commands, SET Recipients are free to ignore SETs that
are not of interest after acknowledging their receipt.When using bearer tokens or proof-of-possession tokens that
represent an authorization grant such as issued by OAuth (see ), implementers SHOULD consider the type of
authorization granted, any authorized scopes (see Section 3.3 of ), and the security subject(s) that SHOULD be mapped
from the authorization when considering local access control rules.
Section 6 of the OAuth Assertion Framework specification
documents common scenarios for
authorization including:
Clients using an assertion to authenticate and/or act on behalf
of itself;Clients acting on behalf of a user; and,A Client acting on behalf of an anonymous user.When using OAuth access tokens, implementers MUST take
into account the threats and countermeasures documented in the
security considerations for the use of client authorizations (see
Section 8 of ). When using
other token formats or frameworks, implementers MUST take into account
similar threats and countermeasures, especially those documented by
the relevant specifications.In scenarios where HTTP authorization or TLS mutual authentication
are not used or are considered weak, JWS signed SETs SHOULD be
used (see and Section 5 of ).
This enables the SET Recipient
to validate that the SET issuer is authorized to deliver the SET.
SET delivery depends on the use of Hypertext Transfer Protocol and is thus
subject to the security considerations of HTTP Section 9 of and its related specifications.As stated in Section 2.7.1 of , an
HTTP requestor MUST NOT generate the userinfo
(i.e., username and password) component (and its "@" delimiter) when
an "http" URI reference is generated with a message, as they are now
disallowed in HTTP.
SETs may contain sensitive information that is considered
Personally Identifiable Information (PII).
In such cases, SET Transmitters and
SET Recipients MUST protect the confidentiality of the SET contents by
encrypting the SET as described in JWE ,
using a transport-layer security mechanism such as TLS, or both. If
an Event delivery endpoint supports TLS, it MUST support at least TLS
version 1.2 and SHOULD support the newest version
of TLS that meets its security requirements. When using TLS, the client MUST
perform a TLS/SSL server certificate check, per .
Implementation security considerations for TLS can be found in
"Recommendations for Secure Use of TLS and DTLS" .
When using access tokens, such as those issued by OAuth 2.0
, implementers MUST take into account threats
and countermeasures documented in Section 8 of .Due to the possibility of interception, Bearer tokens MUST be
exchanged using TLS.Bearer tokens SHOULD have a limited lifetime that can be determined
directly or indirectly (e.g., by checking with a validation service)
by the service provider. By expiring tokens, clients are forced to
obtain a new token (which usually involves re-authentication) for
continued authorized access. For example, in OAuth 2.0, a client MAY use
an OAuth refresh token to obtain a new bearer token after authenticating
to an authorization server, per Section 6 of .Implementations supporting OAuth bearer tokens need to factor in
security considerations of this authorization method . Since security is only as good
as the weakest link, implementers also need to consider authentication
choices coupled with OAuth bearer tokens. The security considerations
of the default authentication method for OAuth bearer tokens, HTTP
Basic, are well documented in , therefore implementers
are encouraged to prefer stronger authentication methods. Designating
the specific methods of authentication and authorization are
out of scope for the delivery of SETs, however this
information is provided as a resource to implementers.If a SET needs to be retained for audit purposes, a JWS signature MAY
be used to provide verification of its authenticity.SET Transmitters SHOULD attempt to deliver SETs that are
targeted to the specific business and
protocol needs of subscribers.When sharing personally identifiable information or information
that is otherwise considered confidential to affected users, SET
Transmitters and Recipients MUST have the appropriate legal agreements
and user consent or terms of service in place.The propagation of subject identifiers can be perceived as personally
identifiable information. Where possible, SET Transmitters and Recipients
SHOULD devise approaches that prevent propagation, for example, the
passing of a hash value that requires the subscriber to already know
the subject.
This specification requires no IANA actions.
The editors would like to thank the members of the SCIM working group, which
began discussions of provisioning events starting with draft-hunt-scim-notify-00 in 2015.The editors would like to thank Phil Hunt and the other the authors of draft-ietf-secevent-delivery-02,
on which this specification is based.The editors would like to thank the participants in the SecEvents
working group for their contributions to this specification.[[ to be removed by the RFC Editor before publication as an RFC ]]
Draft 00 - AB - Based on draft-ietf-secevent-delivery-02 with the
following additions:
Renamed to "Poll-Based SET Token Delivery Using HTTP"Removed references to the HTTP Push delivery method.
Draft 01 - mbj:
Addressed problems identified in my 18-Jul-18 review message titled
"Issues for both the Push and Poll Specs".
Changes to align terminology with RFC 8417, for instance,
by using the already defined term SET Recipient rather than SET Receiver.
Applied editorial and minor normative corrections.
Updated Marius' contact information.
Begun eliminating redundancies between this specification and
"Push-Based Security Event Token (SET) Delivery Using HTTP"
,
referencing, rather that duplicating common normative text.
Draft 02 - mbj:
Removed vestigial language remaining from when the push and poll
delivery methods were defined in a common specification.
Replaced remaining uses of the terms Event Transmitter and Event Recipient
with the correct terms SET Transmitter and SET Recipient.
Removed uses of the unnecessary term "Event Stream".
Removed dependencies between the semantics of
maxEvents and returnImmediately.
Said that PII in SETs is to be encrypted with TLS, JWE, or both.
Corrected grammar and spelling errors.
Draft 03 - mbj:
Corrected uses of "attribute" to "member" when describing JSON objects.
Further alignment with the push draft.
Draft 04 - AB + mbj
Referenced SET Transmitter definition in http-push.
Removed incorrect normative text regarding SET construction.
Consolidated general out-of-scope items under Introduction.
Removed unnecessary HTTP headers in examples and added Content-Type.
Added Content-Language requirement for error descriptions, aligning with http-push.
Stated that bearer tokens SHOULD have a limited lifetime.
Minor editorial fixes.