Push-Based Security Event Token (SET) Delivery Using HTTP
Extracted elements (25)
Earlier versions made TLS optional and described unencrypted-transport considerations. The working group decided to mandate HTTP over TLS and moved the unencrypted considerations to a non-normative appendix, reflecting that SET confidentiality cannot be reliably ensured without TLS.
Error codes are intended for automated processing and SHOULD identify distinct error classes to which an automated system can respond in a meaningfully different way (e.g., refreshing credentials and retrying for authentication_failed, vs. not retrying for invalid_request which represents a structural error unlikely to be resolved by retransmission).
The SET Recipient is designed to respond immediately after validation and persistence, deferring further processing asynchronously. This minimizes the time the SET Transmitter waits for a response, reducing the risk of timeouts and spurious retransmission.
Configuration metadata exchange (endpoint URLs, cryptographic keys, buffer size limitations) between the transmitter and recipient is explicitly out of scope for this specification and is deployment specific.
Push-based delivery (this specification) is one of two SET delivery methods; poll-based delivery is defined in RFC 8936. Push is applicable when the transmitter can make outbound HTTP requests and the recipient can host a TLS-enabled endpoint accessible to the transmitter.
Every Security Event Token Error Code MUST have a unique name registered in the IANA 'Security Event Token Error Codes' registry.
If the SET is valid, the SET Recipient SHALL acknowledge successful transmission by responding with HTTP 202 (Accepted). The body of the response MUST be empty.
Once a SET has been validated and persisted, the SET Recipient SHOULD immediately return a success response and SHOULD NOT perform further processing of the SET prior to sending this response; additional steps SHOULD be executed asynchronously.
SET Transmitters and SET Recipients MUST protect SET confidentiality when SETs contain sensitive or PII data. TLS MUST be used; in some cases, JWE encryption of the SET is also required.
The Content-Type header field of the SET Transmission Request MUST be 'application/secevent+jwt', the Accept header MUST be 'application/json', and the request body MUST consist of the SET represented as a JWT.
The event delivery endpoint MUST support at least TLS 1.2 and SHOULD support the newest version meeting its security requirements (TLS 1.3 at time of publication). The client MUST perform a TLS/SSL server certificate check using DNS-ID and/or DANE. RFC 7525 recommendations MUST be followed.
The failure response MUST include a Content-Language header. If no acceptable language is negotiated via Accept-Language, the SET Recipient MUST respond with messages understandable by an English-speaking person.
The SET Recipient MUST respond to a retransmitted SET as it would if the SET had not been previously received. The SET Recipient MUST NOT depend on a SET Transmitter to retransmit a SET once the SET Recipient has acknowledged successful receipt.
The TLS server certificate MUST be validated using DNS-ID (RFC 6125) and/or DANE (RFC 6698). Authorization may be determined using the SET Issuer identity, SET Transmitter identity, mutual TLS, or other authentication methods.
Upon receipt of a SET, the SET Recipient SHALL validate that the SET is parsable, authentic (issued by the stated issuer and properly signed), that the recipient is an intended audience, that the issuer is trusted, and that the transmitter is authorized to send that SET.
When a SET parsing, validation, or authentication error is detected, the SET Recipient SHALL respond with HTTP 400 (Bad Request). The Content-Type MUST be 'application/json' and the body MUST be a UTF-8 JSON object containing 'err' (error code) and 'description' fields.
Subject identifiers in SETs may themselves be sensitive; their inclusion could enable correlation or de-anonymization. SET Issuers and Transmitters should consider these ramifications and choose appropriate subject identifiers for their use cases.
When sharing PII or confidential user information, SET Transmitters and Recipients MUST have appropriate legal agreements and user consent in place. Data requiring confidentiality MUST be encrypted, at minimum with TLS and optionally with JWE.
A SET Transmission Request is an HTTP POST to a TLS-enabled endpoint operated by the SET Recipient. The SET Transmitter MAY include an Accept-Language header to indicate preferred language(s) for error messages.
Security Event Token Error Codes are case-sensitive ASCII strings consisting only of letters, digits, and underscores. Initial codes are: invalid_request, invalid_key, invalid_issuer, invalid_audience, authentication_failed, and access_denied.
IANA has created the 'Security Event Token Error Codes' registry. Future assignments require Specification Required registration policy. Error codes SHOULD identify distinct error classes to which automated systems can respond differently (e.g., by refreshing credentials and retrying).
JWS-signed SETs (per RFC 7515 and RFC 8417 Section 5) enable the SET Recipient to validate that the SET Issuer is authorized to provide actionable SETs, providing an authentication mechanism independent of transport-layer context.
The SET Recipient may be vulnerable to denial-of-service attacks where a malicious party sends high volumes of invalid SETs, exhausting resources on cryptographic operations. Mitigations include mutual TLS for transmitter authentication and rate-limiting problematic transmitters.
When a SET is forwarded or retrieved from storage, TLS and HTTP authentication context used at delivery time is typically unavailable. If authenticity validation outside the delivery context is required, the SET Recipient SHOULD ensure SETs are signed per RFC 7515.
The error response body is a UTF-8 encoded JSON object with two fields: 'err' (a Security Event Token Error Code string) and 'description' (a UTF-8 human-readable string whose exact content is implementation specific).