To deliver a SET to a given SET Recipient, the SET Transmitter makes a SET Transmission Request to the SET Recipient, with the SET itself contained within the request. The SET Recipient replies to this request with a response either acknowledging successful transmission of the SET or indicating that an error occurred while receiving, parsing, and/or validating the SET.
Upon receipt of a SET, the SET Recipient
SHALL validate that all of the following are true:
-
The SET Recipient can parse the SET.
-
The SET is authentic (i.e., it was issued by the issuer specified within the SET, and if signed, was signed by a key belonging to the issuer).
-
The SET Recipient is identified as an intended audience of the SET.
-
The SET Issuer is recognized as an issuer that the SET Recipient is willing to receive SETs from (e.g., the issuer is listed as allowed by the SET Recipient).
-
The SET Recipient is willing to accept this SET from this SET Transmitter (e.g., the SET Transmitter is expected to send SETs with the issuer and subject of the SET in question).
The mechanisms by which the SET Recipient performs this validation are out of scope for this document. SET parsing, issuer identification, and audience identification are defined in [
RFC 8417]. The mechanism for validating the authenticity of a SET is deployment specific and may vary depending on the authentication mechanisms in use and whether the SET is signed and/or encrypted (See
Section 3).
SET Transmitters
MAY transmit SETs issued by another entity. The SET Recipient may accept or reject (i.e., return an error response such as
access_denied) a SET at its own discretion.
The SET Recipient persists the SET in a way that is sufficient to meet the SET Recipient's own reliability requirements. The level and method of retention of SETs by SET Recipients is out of scope of this specification. Once the SET has been validated and persisted, the SET Recipient
SHOULD immediately return a response indicating that the SET was successfully delivered. The SET Recipient
SHOULD NOT perform further processing of the SET beyond the required validation steps prior to sending this response. Any additional steps
SHOULD be executed asynchronously from delivery to minimize the time the SET Transmitter is waiting for a response.
The SET Transmitter
MAY transmit the same SET to the SET Recipient multiple times, regardless of the response from the SET Recipient. The SET Recipient
MUST respond as it would if the SET had not been previously received by the SET Recipient. The SET Recipient
MUST NOT expect or depend on a SET Transmitter to retransmit a SET or otherwise make a SET available to the SET Recipient once the SET Recipient acknowledges that it was received successfully.
The SET Transmitter should not retransmit a SET unless the SET Transmitter suspects that previous transmissions may have failed due to potentially recoverable errors (such as network outage or temporary service interruption at either the SET Transmitter or SET Recipient). In all other cases, the SET Transmitter
SHOULD NOT retransmit a SET. The SET Transmitter
SHOULD delay retransmission for an appropriate amount of time to avoid overwhelming the SET Recipient (see
Section 4).
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
Content-Type header field of this request
MUST be
application/secevent+jwt as defined in Sections
2.3 and
7.2 of [
RFC 8417], and the
Accept header field
MUST be
application/json. The request body
MUST consist of the SET itself, represented as a [
RFC 7519].
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 messages.
The mechanisms by which the SET Transmitter determines the HTTP endpoint to use when transmitting a SET to a given SET Recipient are not defined by this specification and are deployment specific.
The following is a non-normative example of a SET Transmission Request:
POST /Events HTTP/1.1
Host: notify.rp.example.com
Accept: application/json
Accept-Language: en-US, en;q=0.5
Content-Type: application/secevent+jwt
eyJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJIUzI1NiJ9Cg
.
eyJpc3MiOiJodHRwczovL2lkcC5leGFtcGxlLmNvbS8iLCJqdGkiOiI3NTZFNjk
3MTc1NjUyMDY5NjQ2NTZFNzQ2OTY2Njk2NTcyIiwiaWF0IjoxNTA4MTg0ODQ1LC
JhdWQiOiI2MzZDNjk2NTZFNzQ1RjY5NjQiLCJldmVudHMiOnsiaHR0cHM6Ly9zY
2hlbWFzLm9wZW5pZC5uZXQvc2VjZXZlbnQvcmlzYy9ldmVudC10eXBlL2FjY291
bnQtZGlzYWJsZWQiOnsic3ViamVjdCI6eyJzdWJqZWN0X3R5cGUiOiJpc3Mtc3V
iIiwiaXNzIjoiaHR0cHM6Ly9pZHAuZXhhbXBsZS5jb20vIiwic3ViIjoiNzM3NT
YyNkE2NTYzNzQifSwicmVhc29uIjoiaGlqYWNraW5nIn19fQ
.
Y4rXxMD406P2edv00cr9Wf3_XwNtLjB9n-jTqN1_lLc
If the SET is determined to be valid, the SET Recipient
SHALL acknowledge successful transmission by responding with HTTP Response Status Code 202 (Accepted) (see
Section 6.3.3 of
RFC 7231). The body of the response
MUST be empty.
The following is a non-normative example of a successful receipt of a SET.
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
RFC 7231.
When the SET Recipient detects an error parsing, validating, 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 [
RFC 8259] object containing the following name/value pairs:
-
err:
-
A Security Event Token Error Code (see Section 2.4).
-
description:
-
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.
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
RFC 7231. 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
RFC 2277.
The following is a non-normative example error response indicating that the key used to encrypt the SET has been revoked.
HTTP/1.1 400 Bad Request
Content-Language: en-US
Content-Type: application/json
{
"err": "invalid_key",
"description": "Key ID 12345 has been revoked."
}
The following is a non-normative example error response indicating that the access token included in the request is expired.
HTTP/1.1 400 Bad Request
Content-Language: en-US
Content-Type: application/json
{
"err": "authentication_failed",
"description": "Access token has expired."
}
The following is a non-normative example error response indicating that the SET Receiver is not willing to accept SETs issued by the specified issuer from this particular SET Transmitter.
HTTP/1.1 400 Bad Request
Content-Language: en-US
Content-Type: application/json
{
"err": "invalid_issuer",
"description": "Not authorized for issuer https://iss.example.com/"
}
Security Event Token Error Codes are strings that identify a specific category of error that may occur when parsing or validating a SET. Every Security Event Token Error Code
MUST have a unique name registered in the IANA "Security Event Token Error Codes" registry established by
Section 7.1.
The following table presents the initial set of Error Codes that are registered in the IANA "Security Event Token Error Codes" registry:
Error Code |
Description |
invalid_request |
The request body cannot be parsed as a SET, or the Event Payload within the SET does not conform to the event's definition.
|
invalid_key |
One or more keys used to encrypt or sign the SET is invalid or otherwise unacceptable to the SET Recipient (expired, revoked, failed certificate validation, etc.).
|
invalid_issuer |
The SET Issuer is invalid for the SET Recipient. |
invalid_audience |
The SET Audience does not correspond to the SET Recipient. |
authentication_failed |
The SET Recipient could not authenticate the SET Transmitter.
|
access_denied |
The SET Transmitter is not authorized to transmit the SET to the SET Recipient.
|
Table 1: SET Error Codes
Other Error Codes may also be received, as the set of Error Codes is extensible via the IANA "Security Event Token Error Codes" registry established in
Section 7.1.