]> SGNL

atul@sgnl.ai

Okta

apoorva.deshpande@okta.com

Okta

aaron@parecki.com

sec saag JSON Web Token JWT Security Event Token SET Delivery JavaScript Object Notation JSON This specification defines how multiple Security Event Tokens (SETs) can be delivered and received to and by an intended recipeint using HTTP POST over TLS or WebSocket binding. This specification enabled following two use cases - In situations where a transmitter of Security Event Tokens (SETs) to a network peer is also a receiver of SETs from the same peer, it is helpful to have an efficient way of sending and receiving SETs in one HTTP transaction. In many cases, such as when using the OpenID Shared Signals Framework (SSF), the situation where each entity is both a transmitter and receiver is getting increasingly common. In situations where a transmitter of Security Event Tokens (SETs) wants to transmit multiple SETs to the reciever in a single HTTP call. Using current mechanisms such as "Push-Based Delivery of Security Event Tokens (SETs) Using HTTP" or "Poll-Based Delivery of Security Event Tokens (SETs) Using HTTP" both require two or more HTTP connections to exchange SETs between peers. This is inefficient due to the latency of setting up each communication. This specification enables mutiple events to be transmitted in bi-directional transmission and reception of multiple SETs in one HTTP connection, and enables them to do so over a single HTTP or WebSocket binding. The latest revision of this draft can be found at . Status information for this document may be found at . Source for this draft and an issue tracker can be found at .

Introduction Entities that exchange SETs with each other ("Transceivers") can do so efficiently using the protocol defined in this specification. This specification extends the mechanisms described in the DeliveryPush and DeliveryPoll with the following additional mechanisms: A Transceiver initiating a communication can send multiple SETs in one HTTP connection to a Peer The Transceiver initiating communication can acknowledge previously received SETs in the same HTTP connection to the Peer The Peer responding to the communication can send multiple SETs in its response to a connection from the Transceiver The Peer responding to the communication can acknowledge previously received SETs in its response to the Transceiver This specification also defines a mechanism by which a transmitter of a Security Event Token (SET) can deliver multiple SETs to an intended SET Recipient via HTTP POST [RFC7231] over TLS in a single POST call. focuses on the delivery of the single SET to the receiver. This specification builds onto to transmit multiple SETs to the receiver in a single POST call. Multi-push SET delivery is intended to help in following scenarios: The transmitter of the SET has multiple outstanding SETs to be communicated to the receiver The transmitter wants to reduce the number of outbound calls to the same receiver to optimize performance, avoid being ratelimited when number of SETs to be communicated is high The receiver wants to optimize processing multiple SETs

Notational Conventions 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.

Terminology

Transmitter

A networked entity that can act as a transmitter of SETs. It communicates with other trusted Receivers to transmit using the protocol defined herein.

Receiver

A networked entity that can act as a receiver of SETs. It communicates with other trusted Transmitter to receive SETs using the protocol defined herein.

Transceiver

A networked entity that can act both as a transmitter of SETs and a receiver of SETs. It communicates with other trusted Transceivers to transmit and receive SETs using the protocol defined herein.

Peer

Another name for a Transceiver, used to signify the other end of the communication from a Transceiver.

Initiator

A Transceiver initiating communication with a Peer.

Responder

A Transceiver responding to communication from a Peer.

DeliveryPush

The IETF RFC titled "Push-Based Delivery of Security Event Tokens (SETs) Using HTTP" .

DeliveryPoll

The IETF RFC titled "Poll-Based Delivery of Security Event Tokens (SETs) Using HTTP" .

Pushpull Endpoint Each Transceiver that supports this specification MUST support a "Pushpull" endpoint. This endpoint MUST be capable of serving HTTP requests. This endpoint MUST be TLS enabled and MUST reject any communication not using TLS. The Pushpull endpoint MUST support the HTTP method POST and reject all other HTTP methods.

Communication Object A Communication Object is a JSON object , and is a unit of communication defined in this specification for use in both requests and responses. When used in a request, the Initiator MAY include additional fields defined in the later sections below. The common fields of this object are:

sets

OPTIONAL. A JSON object containing key-value pairs in which the key of a field is a string that contains the jti value of the SET that is specified in the value of the field. This field MAY be omitted to indicate that no SETs are being delivered by the initiator in this communication.

ack

OPTIONAL. An array of strings, in which each string is the jti value of a previously received SET that is acknowledged in this object. This array MAY be empty or this field MAY be omitted to indicate that no previously received SETs are being acknowledged in this communication.

setErrs

OPTIONAL. A JSON object containing key-value pairs in which the key of a field is a string that contains the jti value of a previously received SET that the sender of the communication object was unable to process. The value of the field is a JSON object that has the following fields:

err

REQUIRED. The short reason why the specified SET failed to be processed.

description

REQUIRED. An explanation of why the SET failed to be processed.

Example The following is a non-normative example of a Communication Object

HTTP Request Response Binding This section describes how Transceivers can use HTTP Requests and Responses to exchange Communication Objects described in .

Initiating Communication A Transceiver can initiate communication with a Peer in order to: Send one or more SETs to the Peer. Positively or negatively acknowledge previously received SETs from the Peer. Both acknowledge previously received SETs from the Peer and send SETs to the Peer. To initiate communication, the Initiator makes a HTTP POST request to the Responder's Pushpull Endpoint . The body of this request is of the content type application/json. It contains a Communication Object , and the following additional field MAY be present:

maxResponseEvents

OPTIONAL. A number which specifies the maximum number of events the Responder can include in its response to the Initiator. If this field is absent in the request, the Responder MAY include any number of events in the response. If this field is present, then the Responder MUST NOT include more events than the value of "maxResponseEvents" in its response to the specific request.

Response Communication A Responder MUST respond to a communication from an Initiator by sending an HTTP Response.

Success Response If the Responder is successful in receiving the request, it MUST return the HTTP status code 200 (OK). This status only indicates that the communication received was well formatted and was successfully parsed by the Responder. It does not indicate anything about whether any SETs in the communication were accepted or not. The response MUST have the content-type application/json and the response MUST include a Communication Object .

Error Response The Responder MUST respond with an error response if it is unable to process the request. This error response means that the responder was unable to parse the communication or the responder encountered a system error while attempting to process the communication. It does not indicate a positive or negative acknowledgement of any SETs in the communication. The error response MUST include the appropriate error code as described in Section 2.4 of DeliveryPush .

Out Of Order Responses A Communication Object in a Response may contain jti values in its ack or setErrs that do not correspond to the SETs received in the same Request to which the Response is being sent. They MAY consist of values received in previous Requests.

Example Request and Response The following is a non-normative example of a request and its corresponding response

Request

In the above example request, the Initiator does not acknowledge any previous events, delivers two SETs, and reports an error on a previously received SET.

Response The following is a non-normative example of a response:

In the above example, the Responder acknowledges one of the SETs it previously received and provides a SET to deliver to the initiator. There are no errors reported by the Responder.

WebSocket Binding Transceivers MAY use WebSockets to send and receive Communication Objects described in . Since WebSockets are a symmetric protocol, a Transceiver MAY send a Communication Object at any time to its Peer. In such communication, a Transceiver sends a Communication Object as Payload data over the WebSocket protocol to a Peer. Similarly, a Transceiver MAY receive a Communication Object from a Peer over a WebSocket connection, wherein the Communication Object is the Payload data. In all such WebSocket communication, the Payload data does not have any Extension data in it.

Using WebSockets During any communication initiated by a Transceiver, the Transceiver MAY request the Peer to use WebSockets by requesting that the connection be upgraded to a WebSocket connection. If the Transceiver and its Peer can successfully perform the WebSocket handshake for the Pushpull Subprotocol described in , then the Transceiver and Peer MUST use WebSockets until the connection is closed. If the handshake fails, the Transceiver and Peer MAY use the HTTP Request Response Binding as described in

Pushpull Subprotocol Handshake The Pushpull subprotocol is used to transport Communication Objects over a WebSocket connection. The Transceiver and its Peer agree to this subprotocol during the WebSocket handshake (see ). During the Websocket handshake, the Initiator MUST include the value pushpull in the list of protocols for the Sec-WebSocket-Protocol header. The reply from the Responder MUST also include the value pushpull in the list of values in its own Sec-WebSocket-Protocol header, in order for the Initiator and Responder to use WebSockets.

Authentication and Authorization

Verifying the Responder The Initiator MUST verify the identity of the Responder by validating the TLS certification presented by the Responder, and verifying that it is the intended recipient of the request, before sending the Communication Object .

Verifying the Initiator The Responder MUST verify the identity and authorization of the Initiator. The mechanism by which the Responder verifies the Initiator is out of scope of this specification, but may include mechanisms such as Mutual TLS (MTLS) client authentication, or OAuth access tokens. The Initiator MUST attempt to obtain the OAuth Protected Resource Metadata for the Responder endpoint. If such metadata is found, the Initiator MUST obtain an access token using an OAuth authorization server discovered in the metadata. If no such metadata is found, then the mechanism of authenticating to the Responder is out of scope of this specification.

Delivery Reliability A Transceiver MUST attempt to deliver any SETs it has previously attempted to deliver to a Peer until: It receives an acknowledgement through the ack value for that SET in a subsequent communication with the Peer It receives a setErrs object for that SET in a subsequent communication with the Peer It has attempted to deliver the SET a maximum number of times and has failed to communicate either due to communication errors or lack of inclusion in ack or setErrs in subsequent communications that were conducted for the maximum number of times. The maximum number of attempts MAY be set by the Transceiver for itself and SHOULD be communicated offline to the Peers. If a Transceiver previously attempted to deliver a SET in a response to a Peer's request, the Transceiver MAY Initiate a request to the Peer in order to retry delivery of the SET. A Peer MUST be able to either provide acks or setErrs for the same SETs either through requests or responses.

All SETs Accounted For A Transceiver MUST ensure that it includes the jti value of each SET it receives, either in an ack or a setErrs value, to the Transceiver from which it received the SETs. A Transceiver SHOULD retry sending the same SET again if it was never responded to either in an ack value or in a setErrs value by a receiving Transceiver in a reasonable time period. A Transceiver MAY limit the number of times it retries sending a SET. A Transceiver MAY publish the retry time period and maximum number of retries to its peers, but such publication is outside the scope of this specification.

Conformance This section describes conformance criteria for entities conforming to this specification.

Multi-Push The "Multi-Push" conformance class enables a Transmitter to deliver multiple SETs to a Receiver. To conform to the "Multi-Push" class, a Transceiver acts as only one role: a Transmitter or Receiver. A Transmitter MUST support sets in the request Communication Object. A Receiver MUST support acks and setErrs in the response Communication Object.

Push-Pull The "Push-Pull" conformance class enables bidirectional communication between Transceivers to both send and receive SETs in the same request and response. Transceivers MUST support sets, acks and setErrs in all Communication Objects.

Security Considerations

Authentication and Authorization Transceivers MUST follow the procedures described in in order to securely authenticate and authorize Peers.

HTTP and TLS Transceivers MUST use TLS to communicate with Peers and is subject to the security considerations of HTTP Section 17.

Denial of Service A Responder may be vulnerable to denial of service attacks wherein a large number of spurious requests need to be processed. Having efficient authorization mechanisms such as OAuth 2.0 can mitigate such attacks by leveraging standard infrastructure that is designed to handle such attacks.

Temporary Disconnection Transceivers must make sure they respond to each SET received in a timely manner as described in the "All SETs Accounted For" (). This ensures that if there was a temporary disconnection between two Transceivers, for example when a Responding Transceiver sent a Communication Object in the HTTP Response, that such disconnection is detected and the missing SETs can be retried.

Privacy Considerations SETs may contain confidential information, and Transceivers receiving SETs must be careful not to log such content or ensure that sensitive information from the SET is redacted before logging.

IANA Considerations The following WebSocket subprotocol will be added to the "WebSocket Subprotocol Name Registry" Subprotocol Identifier: pushpull Subprotocol Common Name: WebSocket transport for Pushpull delivery of SETs Subprotocol Definition: Section of this document.

In 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. The WebSocket Protocol enables two-way communication between a client running untrusted code in a controlled environment to a remote host that has opted-in to communications from that code. The security model used for this is the origin-based security model commonly used by web browsers. The protocol consists of an opening handshake followed by basic message framing, layered over TCP. The goal of this technology is to provide a mechanism for browser-based applications that need two-way communication with servers that does not rely on opening multiple HTTP connections (e.g., using XMLHttpRequest or s and long polling). [STANDARDS-TRACK] The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. JavaScript 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. This specification defines the Security Event Token (SET) data structure. A SET describes statements of fact from the perspective of an issuer about a subject. These statements of fact represent an event that occurred directly to or about a security subject, for example, a statement about the issuance or revocation of a token on behalf of a subject. This specification is intended to enable representing security- and identity-related events. A SET is a JSON Web Token (JWT), which can be optionally signed and/or encrypted. SETs can be distributed via protocols such as HTTP. This document specifies version 1.3 of the Transport Layer Security (TLS) protocol. TLS allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery. This document updates RFCs 5705 and 6066, and obsoletes RFCs 5077, 5246, and 6961. This document also specifies new requirements for TLS 1.2 implementations. This specification defines how a Security Event Token (SET) can be delivered to an intended recipient using HTTP POST over TLS. The SET is transmitted in the body of an HTTP POST request to an endpoint operated by the recipient, and the recipient indicates successful or failed transmission via the HTTP response. This specification defines how a series of Security Event Tokens (SETs) can 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. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230.

Contributors SGNL

erik@sgnl.ai