]> Okta

apoorva.deshpande@okta.com

Okta

aaron@parecki.com

Security Security Events security event secevent This specification defines how multiple Security Event Tokens (SETs) can be delivered to an intended recipient using HTTP POST over TLS. The SETs are 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. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Security Events Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction This specification 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 over TLS in a single POST request. focuses on the delivery of the single SET to the Receiver. When sending a large number of SETs, sending them one by one is inefficient. This specification defines a way to send batches of SETs in a single POST request for more efficient transport. Push-Based delivery for multiple SETs 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 requests 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
• The Receiver wants to acknowledge or provide error responses to previously received SETs, but wants to do so asynchronously, rather than within the response to the same HTTP POST in which it received the SET

This specification will handle all the use cases and scenarios for the and make it more extensible to support multiple SETs per one outbound POST request. Similar to this specification makes mechanism for exchanging configuration metadata such as endpoint URLs, cryptographic keys, and possible implementation constraints such as buffer size limitations between the Transmitter and Recipient is out of scope but is expected to be defined by profiles of this specification.

Conventions and Definitions 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.

Push endpoint to receive multiple SETs Each Receiver that supports this specification MUST support a new push endpoint that receives multiple SETs in a single request. This endpoint MUST be capable of serving HTTP POST requests. This endpoint MUST be TLS enabled and MUST reject any communication not using TLS. The Transmitter obtains this endpoint from the Receiver is outside the scope of this specification.

SET Delivery Semantics In this SET delivery using HTTP over TLS, a Transmitter delivers zero or more SETs in a JavaScript Object Notation (JSON) document to the SET Receiver. The Receiver either acknowledges the successful receipt of the SETs or indicates failure in processing of one or more SETs in a JSON document to the Transmitter. The Transmitter SHOULD periodically send a request with zero SETs to allow the Receiver to respond back with an ack or err for previously transmitted SETs that have not yet been acknowledged. 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. Transmitters may also discard undelivered SETs under deployment-specific conditions, such as if they have not been acknowledged (successful or failure) for over too long a period of time or if an excessive amount of storage is needed to retain them. If a Transmitter receives an acknowledgement or error for a SET it has no record of, the Transmitter MUST ignore that acknowledgement or error. Upon receiving a SET, the SET Recipient reads the SET and validates it in the manner described in . The SET Recipient MUST acknowledge receipt to the SET Transmitter, and SHOULD do so in a timely fashion (e.g., miliseconds). 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.

Acknowledgement for all SETs A Receiver MUST ensure that it includes the jti value of each SET it receives, either in an ack or a setErrs value, to the Transmitter from which it received the SETs. A Transmitter 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 Receiver in a reasonable time period. A Transmitter MAY limit the number of times it retries sending a SET. A Transmitter MAY publish the retry time period and maximum number of retries to its peers, but such publication is outside the scope of this specification.

Uniqueness of SETs A Transmitter MUST NOT send two SETs with the same jti value if the SET has been either acknowledged through ack value or produced an error indicated by a setErrs value. If a Transmitter wishes to re-send an event after it has received a error response through a setErrs value, then it MUST generate a new SET that has a new (and unique) jti value.

Transmitting SETs To transmit a SET to a SETs Recipient, the SET Transmitter makes an HTTP POST request to a TLS-enabled HTTP endpoint provided by the SET Recipient. The body of this request is of the content type "application/json" and the Accept header field MUST be "application/json". A Transmitter may initiate communication with the Receiver in order to:

• Send SETs to the Receiver
• Receive acknowledgement of SETs in response

It MUST contain the following fields:

The sets Field REQUIRED. A JSON object containing key-value pairs in which the key of a field is a string that contains the jti claim of the SET that is specified in the value of the field. This field MAY be an empty object to indicate that no SETs are being delivered by the initiator in this communication. The maximum number of SETs in a push MAY be set by the Transmitter for itself and SHOULD be communicated offline to the Receivers. The following is a non-normative example of a request. Figure 1: Example of SET Transmission In the above example, the Transmitter is sending 2 SETs to the Receiver. Figure 2: Example of empty SET transmission In the above example, the Transmitter is sending zero SETs to the Receiver. This placeholder/empty request provides the Receiver to respond back with ack/err for previously transmitted SETs. The SET Transmitter MAY include in the request an Accept-Language header field to indicate to the SET Recipient the preferred language(s) in which to receive error message descriptions.

Response Communication A Receiver MUST repond to the communication by sending an HTTP response. The body of this response is of the content type "application/json". It contains the following fields: ack REQUIRED. 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 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. Error codes are described in Section 2.4 of . description OPTIONAL. An explanation of why the SET failed to be processed If the response contains a description, then the response MUST include a Content-Language header field whose value indicates the language of the error descriptions included in the response body. If the SET Recipient can provide error descriptions in multiple languages, they SHOULD choose the language to use according to the value of the Accept-Language header field sent by the SET Transmitter in the transmission request, as described in Section 5.3.5 of . If the SET Transmitter did not send an Accept-Language header field, or if the SET Recipient does not support any of the languages included in the header field, the SET Recipient MUST respond with messages that are understandable by an English-speaking person, as described in Section 4.5 of .

Success Response If the Receiver is successful in processing the request, it MUST return the HTTP status code 202 (Accepted). The response MUST have the content-type "application/json". Figure 3: Example of SET Transmission response with ack In the above example, the Receiver acknowledges one of the SETs it previously received. There are no errors reported by the Receiver. Figure 4: Example of SET Transmission response, ack and errors In the above example, the Receiver acknowledges three of the SETs it previously received. There are errors reported by the Receiver for acklowledging one SET.

Failure Response In the event of a general HTTP error condition, the SET Recipient responds with the applicable HTTP Status Code, as defined in Section 6 of . When the SET Recipient detects an error parsing, or authenticating a SET transmitted in a SET Transmission Request, the SET Recipient SHALL respond with an HTTP Response Status Code of 400 (Bad Request). The Content-Type header field of this response MUST be "application/json", and the body MUST be a UTF-8 encoded JSON object containing the following name/value pairs: err REQUIRED. The short reason why the API failed to process the request. (Not specific to any SETs, but usually indicate service level failure or processing error) description OPTIONAL. A UTF-8 string containing a human-readable description of the error that may provide additional diagnostic information. The exact content of this field is implementation specific. Note that failure responses in this specification are not specific to any failures related to any specific SET processing. SET specific errors should be communicated by a success response payload defined in the Section. Example error codes that can indicate API level failures MAY include but not limited to:

• invalid_request (request is malformed)
• authentication_failed (authentication token provided by the Transmitter is expired, revoked or invalid)
• access_denied (The Transmitter does not have adequate permissions to invoke this API).
• too_many_sets (Transmitter included too many SETs in a single request, this is an indication for the Transmitter to make a request with lower number of SETs or to comply with max SETs count that Receiver published outside of this spec)

_Figure 5: Example Error Response (authentication_failed) Above non-normative example error response indicating that the access token included in the request is expired.

Out of order delivery 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.

Error Response The Receiver MUST respond with an error response if it is unable to process the request. The error response MUST include the appropriate error code as described in .

Authentication and Authorization The Transmitter MUST verify the identity of the Receiver by validating the TLS certificate presented by the Receiver during the TLS handshake, and verifying that it is the intended recipient of the request, before sending the SETs. How the Transmitter and Receiver agree on authorization of the request is out of scope of this document. This section describes server-side authentication of the Receiver by the Transmitter. Authentication of the Transmitter by the Receiver (e.g., via OAuth tokens, mutual TLS, or other mechanisms) is out of scope of this document and is expected to be defined by profiles of this specification.

Delivery Reliability A Transmitter MUST attempt to deliver any SETs it has previously attempted to deliver to a Receiver until:

• It receives an acknowledgement through the ack value for that SET in a subsequent communication with the Receiver
• It receives a setErrs object for that SET in a subsequent communication with the Receiver
• 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 Transmitter for itself and SHOULD be communicated offline to the Receivers

Additionally consider Delivery Reliability aspects discussed in .

Security Considerations The Security Considerations of , , and apply to this specification.

Too many SETs in the request This mechanism allows a Transmitter to send a large number of SETs in a single request. A malicious or misconfigured Transmitter could send an extremely large payload, attempting to exhaust memory or CPU resources on the Receiver during JSON parsing or SET validation. Receivers MUST protect themselves against such attacks. It is RECOMMENDED that Receivers establish and document a reasonable upper limit on the number of SETs they will process in a single request. Transmitter MUST obey the maximum number of SETs to be communicated to the Receiver. This will avoid any potential truncations/loss of information at the Receiver. If a Receiver receives a batch exceeding this limit, it SHOULD reject the entire request with a 413 Payload Too Large HTTP status code. How the Receiver conveys this upper limit to Transmitters is outside the scope of this specification (see for the sets field definition).

Authentication and Authorization Transmitter MUST follow the procedures described in section in order to securely authenticate and authorize Receiver

HTTP and TLS Transmitter MUST use TLS to communicate with Receiver and is subject to the security considerations of HTTP . Failure to properly validate the Receiver's TLS certificate could allow a Transmitter to send SETs to an impersonating endpoint, resulting in the disclosure of sensitive security event information to an unauthorized party.

Event Delivery Latency The primary purpose of security event tokens is the timely communication of security-sensitive information. While this specification enables batching for efficiency, Transmitters MUST NOT unduly delay the transmission of events in an attempt to create larger batches. Delaying the transmission of a time-sensitive event, such as a credential compromise or session revocation, defeats the purpose of the protocol and provides an adversary with a larger window of opportunity to act. It is RECOMMENDED that Transmitters implement a batching policy that sends a pending batch of SETs when either of the following conditions is met:

• The number of SETs in the batch reaches a configured size limit.
• A configured amount of time (e.g., 1-2 seconds) has elapsed since the oldest SET in the batch was generated.

This ensures a balance between network efficiency and the real-time nature of the communication.

Information Disclosure in Error Responses The setErrs is designed for debugging and provides valuable feedback. However, if implemented incorrectly, it can become a souce of information leakage, disclosing internal details or enable enumeration type attacks. It is RECOMMENDED that setErrs information be designed to be helpful without revealing sensitive information about internal architecture.

Event Ordering and Processing Guarantees This specification is a transport efficiency mechanism and it does not address transactional aspects of the request. Every SET is an independent event in the request to the Receiver. The event ordering in the request does not imply any chronological dependence. For chronological dependence the Receiver should look at the time related event claims. A Transmitter should not assume the ordered processing of the SETs by the Receiver sub-systems. This specification does not add any transactional requirements on the Receiver. Additional security consideration in .

Privacy Considerations Privacy Considerations from apply.

IANA Considerations This document has no IANA actions.

Normative References 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. The Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems. This document defines the semantics of HTTP/1.1 messages, as expressed by request methods, request header fields, response status codes, and response header fields, along with the payload of messages (metadata and body content) and mechanisms for content negotiation. 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. 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. 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 a metadata format that an OAuth 2.0 client or authorization server can use to obtain the information needed to interact with an OAuth 2.0 protected resource. 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 document is the current policies being applied by the Internet Engineering Steering Group (IESG) towards the standardization efforts in the Internet Engineering Task Force (IETF) in order to help Internet protocols fulfill these requirements. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. 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. 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.

Acknowledgments The authors would like to acknowledge the following individuals who contributed ideas, feedback, and wording that shaped and formed the final specification: Atul Tulshibagwale, Yair Sarig, Yaron Sheffer.