Security Event Token (SET)
Extracted elements (30)
Multiple event identifiers within a single SET are intended to represent multiple aspects of the same state transition (e.g., classification or linkage information), not to aggregate distinct independent events. Allowing a SET to carry multiple aspects simplifies delivery while the restriction to a single state transition preserves semantic clarity.
SETs are explicitly designed as statements of fact (describing events that have already occurred), not commands or requests. Recipients independently decide what action, if any, to take upon receiving a SET. This design separates the event description from the business logic of the recipient.
The 'exp' claim is NOT RECOMMENDED in SETs because a SET describes something that has already happened and is historical in nature, making the concept of token expiration semantically inappropriate. Additionally, omitting 'exp' serves as a concrete defense against confusion with ID Tokens, which require 'exp'.
To distinguish SETs from OAuth 2.0 access tokens implemented as JWTs, SET profiles should prohibit 'exp', use separate 'aud' values, modify access token validators to detect the 'events' claim, and/or employ explicit 'typ' typing. The appropriate strategy is implementation-specific because access token JWT structure is not standardized.
When a SET profile might be confused with other JWT profiles (e.g., SIP PASSporT or RFC 8055), the most direct mitigation is explicit 'typ' typing combined with requiring token validators to check 'typ'. For contexts where 'typ' is not checked, omitting claims required by the target JWT type or requiring absence of the 'events' claim in non-SET validators are effective alternatives.
Event identifiers (the member names in the 'events' JSON object) MUST be URIs. Event identifiers SHOULD be stable values such as permanent URLs for event specifications.
Methods for distribution of SETs SHOULD require transport-layer security. Parties MUST support TLS 1.2 or higher and MAY support additional mechanisms. When using TLS the client MUST perform a TLS server certificate check per RFC 6125.
Profiling specifications MUST define how the event subject is identified in the SET and how to differentiate between the event subject's issuer and the SET issuer. Profiling specifications MUST clearly specify the validation steps a recipient MUST perform to confirm syntactic and semantic validity.
SETs distributed through third parties or that carry personally identifiable information MUST be encrypted using JWE (RFC 7516) or secured for confidentiality by other means.
SETs MAY include the 'application/secevent+jwt' media type in the JWT 'typ' header parameter to declare explicit typing. This MUST be included if the SET could be confused with other kinds of JWTs in the application context. The 'typ' value SHOULD be 'secevent+jwt' (omitting the 'application/' prefix per RFC 7515 Section 4.1.9).
The 'aud' (Audience) claim is RECOMMENDED and contains one or more audience identifiers for the SET.
The 'events' claim value MUST be a JSON object that contains at least one member. Multiple event identifiers with the same URI value MUST NOT be used. The 'events' claim MUST NOT be used to express multiple independent logical events.
The 'iat' (Issued At) claim is REQUIRED in every SET, representing when the SET was issued.
The 'iss' (Issuer) claim MUST be present in every SET, identifying the service provider publishing the SET. Implementers cannot assume the SET issuer is the same as the security subject's issuer unless the profiling specification says so.
The 'jti' (JWT ID) claim is REQUIRED in every SET. The identifier MUST be unique within a particular event feed and MAY be used by clients to track whether a particular SET has already been received.
Unless integrity of the JWT is ensured by other means, a SET MUST be signed using JWS (RFC 7515) by a trusted issuer so that the SET can be authenticated and validated by the recipient.
Use of the 'exp' (Expiration Time) claim in SETs is NOT RECOMMENDED because SETs represent historical facts that have already occurred, so the expiration concept does not typically apply.
A SET recipient may correlate different events to gain unintended information about a subject — for example, using 'iat' or precise 'toe' values to determine that two events relate to the same real-world event. SET issuers SHOULD minimize event correlation risk by using approximate 'toe' values or arbitrarily delaying SET issuance where tolerable.
SET issuers SHOULD attempt to specialize SETs so their content is targeted to the specific needs of intended recipients. When sharing personally identifiable information, SET issuers and recipients should have appropriate legal agreements and user consent in place. Where possible, subject identifiers should use salted hash values rather than direct identifiers.
A Security Event Token (SET) is a JWT whose Claims Set contains a top-level 'envelope' and an 'events' claim. The 'events' claim value is a JSON object whose member names are URI event identifiers and whose member values are JSON objects (the event payload) containing event-specific claims.
The 'events' claim contains one or more name/value pairs where each name is a URI event identifier and each value is a JSON object (possibly empty '{}') holding event-specific data defined by the profiling specification. Multiple event identifiers in a single SET represent multiple aspects of the same state transition, not distinct events.
Three new JWT claims are defined: 'events' (Security Events, required JSON object), 'toe' (Time of Event, optional NumericDate representing when the event occurred), and 'txn' (Transaction Identifier, optional string for correlating related JWTs).
The 'application/secevent+jwt' media type is registered in the IANA 'Media Types' registry to indicate that content is a SET. Encoding is binary (base64url-encoded JWT components separated by '.'). Intended usage is COMMON with no usage restrictions.
The '+jwt' structured syntax suffix is registered in the IANA 'Structured Syntax Suffix' registry, indicating that the media type is encoded as a JWT (a series of base64url-encoded values separated by period characters). Fragment identifier semantics for '+jwt' SHOULD follow those of 'application/jwt'.
Three new claims are registered in the IANA 'JSON Web Token Claims' registry: 'events' (Security Events, Section 2.2 of RFC 8417), 'toe' (Time of Event, Section 2.2), and 'txn' (Transaction Identifier, Section 2.2). Change controller is IESG.
A SET might be confused with another kind of JWT from the same issuer, because RFC 7519 states that unrecognized claims MUST be ignored. An attacker possessing a SET could attempt to use it in a context expecting a different JWT type. Mitigations include explicit typing via the 'typ' header, omitting claims required by other JWT types, and validating presence of the 'events' claim.
Because SETs may be delivered asynchronously and out-of-band, a SET may arrive before or after the process it describes, causing timing conflicts (e.g., a revocation SET arriving while the user is re-authenticating). Profiling specifications SHOULD consider revocation of specific sessions rather than broad logout statements, or use timestamps to bound effect.
This specification defines no ordering mechanism for multiple SETs. Profiling specifications and implementers SHOULD define a detection mechanism for event order when order matters (e.g., using the 'txn' claim as an ordered counter), and SHOULD be cautious about relying on timestamps ('iat', 'toe') due to clock skew in distributed systems.
To prevent confusion with OpenID Connect ID Tokens, SET profiles that could otherwise produce a valid-looking ID Token MUST require that the 'exp' claim be absent, since 'exp' is required by ID Tokens and its absence will cause rejection. Note that explicit 'typ' typing does not help here because ID Token validation rules do not use the 'typ' header parameter.
A SET is encoded as a JWT per RFC 7519: a JOSE Header, a base64url-encoded JWT Claims Set, and a JWS signature (possibly empty for unsecured tokens), concatenated with period ('.') separators. The JOSE Header for a typed SET includes 'typ':'secevent+jwt'.