]> 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 Recipient. 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 the following scenarios:

• The Transmitter of the SET has multiple outstanding SETs to be communicated to the Recipient
• The Transmitter wants to reduce the number of outbound requests to the same Recipient to optimize performance and avoid being rate-limited when the number of SETs to be communicated is high
• The Recipient wants to optimize processing multiple SETs
• The Recipient 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 does not define how the Transmitter and Recipient exchange configuration metadata, such as endpoint URLs, cryptographic keys, and implementation constraints like buffer size limitations.

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 Recipient 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. How the Transmitter obtains this endpoint from the Recipient 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 Recipient. The Recipient 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 Recipient 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 (success or failure) for 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., milliseconds). 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 Recipient 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 Recipient 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 an error response through a setErrs value, then it MUST generate a new SET that has a new (and unique) jti value. This specification does not mandate replay protection on the Recipient. However, if a Recipient receives a SET with a jti value that it has already acknowledged or reported an error for, it MAY silently drop the duplicate rather than reprocessing it.

Transmitting SETs To transmit a SET to a SET 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/secevents+json" (see ) and the Accept header field MUST be "application/json". A Transmitter may initiate communication with the Recipient in order to:

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

The body of this request 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 Recipients. 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 Recipient. Figure 2: Example of empty SET transmission In the above example, the Transmitter is sending zero SETs to the Recipient. This placeholder/empty request allows the Recipient 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 Recipient MUST respond 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 . Note that the authentication_failed and access_denied codes described therein apply to the SET Transmission Request as a whole rather than to an individual SET, and therefore MUST NOT be used in a setErrs value; such failures MUST instead be reported using the err field described in . 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 . 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 Recipient is successful in accepting 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 Recipient acknowledges one of the SETs it previously received. There are no errors reported by the Recipient. Figure 4: Example of SET Transmission response, ack and errors In the above example, the Recipient acknowledges three of the SETs it previously received. There are errors reported by the Recipient for acknowledging one SET.

Failure Response In the event of a general HTTP error condition that is not specific to an individual SET, the SET Recipient responds with the applicable HTTP status code, as defined in . When the SET Recipient rejects the request as a whole (for example, because the request is malformed, or the Transmitter is not authenticated or authorized), the SET Recipient SHOULD describe the failure using the problem details format defined in . The Content-Type header field of such a response MUST be "application/problem+json". In addition to the members defined in , the response MAY include the following extension member: err OPTIONAL. A short, machine-readable code identifying the reason the request failed. This code is not specific to any individual SET; it indicates a request-level or service-level failure. Note that failure responses in this specification are not specific to failures related to any individual SET. SET-specific errors are communicated in a success response payload as defined in the Section. Example values for the err extension member that can indicate request-level failures include, but are 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 (the Transmitter included too many SETs in a single request; this is an indication for the Transmitter to make a request with a lower number of SETs or to comply with the maximum SET count that the Recipient published outside of this specification)

Figure 5: Example Error Response (authentication_failed) The non-normative example above indicates 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.

Authentication and Authorization The Transmitter MUST verify the identity of the Recipient by validating the TLS certificate presented by the Recipient during the TLS handshake, and verifying that it is the intended recipient of the request, before sending the SETs. How the Transmitter and Recipient agree on authorization of the request is out of scope of this document. This section describes server-side authentication of the Recipient by the Transmitter. Authentication of the Transmitter by the Recipient (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 Recipient until:

• It receives an acknowledgement through the ack value for that SET in a subsequent communication with the Recipient
• It receives a setErrs object for that SET in a subsequent communication with the Recipient
• 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 Recipients

Additionally consider Delivery Reliability aspects discussed in .

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 Recipient. The event ordering in the request does not imply any chronological dependence. For chronological dependence, the Recipient should look at the time-related event claims. A Transmitter should not assume the ordered processing of the SETs by the Recipient sub-systems. This specification does not add any transactional requirements on the Recipient.

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 Recipient during JSON parsing or SET validation. Recipients MUST protect themselves against such attacks. It is RECOMMENDED that Recipients establish and document a reasonable upper limit on both the number of SETs and the total size, in bytes, of the request body they will process in a single request. Limiting the number of SETs alone is insufficient, since a request containing few but excessively large SETs can still exhaust memory or CPU resources. The Transmitter MUST obey the maximum number of SETs and maximum request body size communicated by the Recipient. This will avoid any potential truncations/loss of information at the Recipient. If a Recipient receives a request exceeding either limit, it SHOULD reject the entire request with a 413 Payload Too Large HTTP status code. How the Recipient conveys these upper limits to Transmitters is outside the scope of this specification (see for the sets field definition).

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

HTTP and TLS The Transmitter MUST use TLS to communicate with the Recipient and is subject to the security considerations of HTTP . Failure to properly validate the Recipient'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. Likewise, Recipients SHOULD respond with an ack or setErrs for each SET as soon as possible, without unduly delaying the response. 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 source of information leakage, disclosing internal details or enabling enumeration type attacks. It is RECOMMENDED that setErrs information be designed to be helpful without revealing sensitive information about internal architecture. For example, a description SHOULD NOT echo back tenant identifiers, internal user identifiers, or other values that could enable an attacker to enumerate valid accounts or infer details of the Recipient's internal architecture, such as stack traces or database identifiers. Additional security considerations in .

Privacy Considerations Privacy Considerations from apply.

IANA Considerations This document registers the application/secevents+json media type in the "Media Types" registry .

Media Type Registration

Registry Contents This section registers the application/secevents+json media type in the "Media Types" registry in the manner described in . This media type is used to indicate that the content is a JSON object carrying a batch of Security Event Tokens (SETs), as described in .

• Type name: application
• Subtype name: secevents+json
• Required parameters: N/A
• Optional parameters: N/A
• Encoding considerations: 8bit; the content is a JSON object as defined in and is always encoded using UTF-8
• Security considerations: See of this document and
• Interoperability considerations: N/A
• Published specification: of this document
• Applications that use this media type: Applications that deliver batches of Security Event Tokens (SETs) over HTTP
• Fragment identifier considerations: N/A
• Additional information:
  • Magic number(s): N/A
  • File extension(s): N/A
  • Macintosh file type code(s): N/A
• Person & email address to contact for further information: Apoorva Deshpande, apoorva.deshpande@okta.com
• Intended usage: COMMON
• Restrictions on usage: none
• Author: Apoorva Deshpande, apoorva.deshpande@okta.com
• Change controller: IETF
• Provisional registration? No

References 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. 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 defines a "problem detail" to carry machine-readable details of errors in HTTP response content to avoid the need to define new error response formats for HTTP APIs. This document obsoletes RFC 7807. 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 obsoletes RFC 8446, which specified TLS 1.3. This document obsoletes RFC 5246 (specifying TLS 1.2) and RFCs 5077, 6961, 7627, and 8422, all of which pertain to TLS 1.2 or earlier, and updates RFCs 5705 and 6066. This document also specifies new requirements for TLS 1.2 implementations. 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. This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice. 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. Informative References IANA

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, Martin Duke, Scott Kelly, Deb Cooley.