idnits 2.17.1 draft-backman-secevent-token-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 29, 2017) is 2311 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 secevent A. Backman 3 Internet-Draft Amazon 4 Intended status: Standards Track W. Denniss 5 Expires: June 2, 2018 Google 6 M. Ansari 7 Cisco 8 M. Jones 9 Microsoft 10 November 29, 2017 12 Security Event Token (SET) 13 draft-backman-secevent-token-03 15 Abstract 17 This specification defines the Security Event Token, which may be 18 distributed via a protocol such as HTTP. The Security Event Token 19 (SET) specification profiles the JSON Web Token (JWT), which can be 20 optionally signed and/or encrypted. A SET describes a statement of 21 fact from the perspective of an issuer that it intends to share with 22 one or more receivers. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on June 2, 2018. 41 Copyright Notice 43 Copyright (c) 2017 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 60 1.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 61 2. The Security Event Token (SET) . . . . . . . . . . . . . . . 5 62 2.1. SET Claims . . . . . . . . . . . . . . . . . . . . . . . 5 63 2.2. Subject Identifiers . . . . . . . . . . . . . . . . . . . 8 64 2.2.1. Email Subject Identifier Type . . . . . . . . . . . . 9 65 2.2.2. Phone Number Subject Identifier Type . . . . . . . . 9 66 2.2.3. Issuer and Subject Subject Identifier Type . . . . . 10 67 2.3. Explicit Typing of SETs . . . . . . . . . . . . . . . . . 10 68 2.4. Security Event Token Construction . . . . . . . . . . . . 11 69 3. Related Events . . . . . . . . . . . . . . . . . . . . . . . 12 70 3.1. Processing Related Events . . . . . . . . . . . . . . . . 12 71 4. Requirements for SET Profiles . . . . . . . . . . . . . . . . 14 72 4.1. Extending Events . . . . . . . . . . . . . . . . . . . . 14 73 5. Security Considerations . . . . . . . . . . . . . . . . . . . 14 74 5.1. Confidentiality and Integrity . . . . . . . . . . . . . . 14 75 5.2. Delivery . . . . . . . . . . . . . . . . . . . . . . . . 15 76 5.3. Sequencing . . . . . . . . . . . . . . . . . . . . . . . 15 77 5.4. Timing Issues . . . . . . . . . . . . . . . . . . . . . . 16 78 5.5. Distinguishing SETs from ID Tokens . . . . . . . . . . . 16 79 5.6. Distinguishing SETs from Access Tokens . . . . . . . . . 16 80 5.7. Distinguishing SETs from other kinds of JWTs . . . . . . 17 81 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 18 82 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 83 7.1. SET Subject Identifier Types Registry . . . . . . . . . . 18 84 7.2. JSON Web Token Claims Registration . . . . . . . . . . . 18 85 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 19 86 7.3. Media Type Registration . . . . . . . . . . . . . . . . . 19 87 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 19 88 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 89 8.1. Normative References . . . . . . . . . . . . . . . . . . 20 90 8.2. Informative References . . . . . . . . . . . . . . . . . 21 91 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 22 92 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 22 93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 95 1. Introduction 97 This specification defines an extensible Security Event Token (SET) 98 format which may be exchanged using protocols such as HTTP. The 99 specification builds on the JSON Web Token (JWT) format [RFC7519] in 100 order to provide a self-contained token that can be optionally signed 101 using JSON Web Signature (JWS) [RFC7515] and/or encrypted using JSON 102 Web Encryption (JWE) [RFC7516]. 104 This specification profiles the use of JWT for the purpose of issuing 105 security event tokens (SETs). This specification defines a base 106 format upon which profiling specifications define actual events and 107 their meanings. Unless otherwise specified, this specification uses 108 non-normative example events intended to demonstrate how events may 109 be constructed. 111 This specification is scoped to security and identity related events. 112 While security event tokens may be used for other purposes, the 113 specification only considers security and privacy concerns relevant 114 to identity and personal information. 116 Security Events are not commands issued between parties. A security 117 event is a statement of fact from the perspective of an issuer about 118 the state of a security subject (e.g., a web resource, token, IP 119 address, the issuer itself) that the issuer controls or is aware of, 120 that has changed in some way (explicitly or implicitly). A security 121 subject MAY be permanent (e.g., a user account) or temporary (e.g., 122 an HTTP session) in nature. A state change could describe a direct 123 change of entity state, an implicit change of state or other higher- 124 level security statements such as: 126 o The creation, modification, removal of a resource. 128 o The resetting or suspension of an account. 130 o The revocation of a security token prior to its expiry. 132 o The logout of a user session. Or, 134 o A cumulative conclusion such as to indicate that a user has taken 135 over an email identifier that may have been used in the past by 136 another user. 138 While subject state changes are often triggered by a user-agent or 139 security-subsystem, the issuance and transmission of an event often 140 occurs asynchronously and in a back-channel to the action which 141 caused the change that generated the security event. Subsequently, 142 an Event Receiver, having received a SET, validates and interprets 143 the received SET and takes its own independent actions, if any. For 144 example, having been informed of a personal identifier being 145 associated with a different security subject (e.g., an email address 146 is being used by someone else), the Event Receiver may choose to 147 ensure that the new user is not granted access to resources 148 associated with the previous user. Or, the Event Receiver may not 149 have any relationship with the subject, and no action is taken. 151 While Event Receivers will often take actions upon receiving SETs, 152 security events cannot be assumed to be commands or requests. The 153 intent of this specification is to define a way of exchanging 154 statements of fact that Event Receivers may interpret for their own 155 purposes. As such, SETs have no capability for error signaling other 156 to ensure the validation of a received SET. 158 1.1. Notational Conventions 160 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 161 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 162 "OPTIONAL" in this document are to be interpreted as described in 163 [RFC2119]. These keywords are capitalized when used to unambiguously 164 specify requirements of the protocol or application features and 165 behavior that affect the inter-operability and security of 166 implementations. When these words are not capitalized, they are 167 meant in their natural-language sense. 169 For purposes of readability, examples are not URL encoded. 170 Implementers MUST percent encode URLs as described in Section 2.1 of 171 [RFC3986]. 173 Throughout this document, all figures MAY contain spaces and extra 174 line-wrapping for readability and space limitations. Similarly, some 175 URIs contained within examples have been shortened for space and 176 readability reasons. 178 1.2. Definitions 180 The following definitions are used with SETs: 182 Security Event Token (SET) 183 A SET is a JWT [RFC7519] that contains an event payload describing 184 a security event. 186 Event Transmitter 187 A service provider that delivers SETs to other providers known as 188 Event Receivers. 190 Event Receiver 191 An Event Receiver is an entity that receives SETs through some 192 distribution method. An Event Receiver is the same entity 193 referred as "recipient" or "receiver" in and related 194 specifications. [RFC7519] 196 Subject 197 A SET describes an event or state change that has occurred about a 198 Subject. A Subject may be a principal (e.g., Section 4.1.2 199 [RFC7519]), a web resource, an entity such as an IP address, or 200 the issuer itself that a SET might reference. 202 Profiling Specification 203 A specification that uses the SET Token specification to define 204 one or more event types and the associated claims included. 206 2. The Security Event Token (SET) 208 A SET is a data structure that encodes an "event payload" describing 209 a security event, wrapped in an "envelope" providing metadata and 210 context for the security event. The SET envelope is a JWT Claims Set 211 as defined in [RFC7519], consisting of a JSON object containing a set 212 of claims. The event payload is a JSON object contained within the 213 SET envelope, itself containing claims that express information about 214 the event, e.g. the type of event, the subject of the event, and 215 other information defined in a Profiling Specification. 217 This specification defines a core set of claims for use in SET 218 envelopes and event payloads, however Profiling Specifications MAY 219 define additional claims of both types. It is RECOMMENDED that 220 Profiling Specifications define claims to be used in the event 221 payload rather than the envelope. If a Profiling Specification does 222 define envelope claims, those claims SHOULD be registered in the JWT 223 Token Claims Registry [IANA.JWT.Claims] or have Public Claim Names as 224 defined in Section 4.2 of [RFC7519]. 226 2.1. SET Claims 228 This specification profiles the following claims defined in [RFC7519] 229 for use in the SET envelope: 231 iss 232 A case-sensitive string identifying the principal that issued the 233 SET, as defined by Section 4.1.1 of [RFC7519]. This claim is 234 REQUIRED. 236 aud 237 A case-sensitive string or array of case-sensitive strings 238 identifying the audience for the SET, as defined by Section 4.1.3 239 of [RFC7519]. This claim is RECOMMENDED. 241 exp 242 As defined by Section 4.1.4 of [RFC7519], this claim is the time 243 after which the JWT MUST NOT be accepted for processing. In the 244 context of a SET however, this notion does not apply since a SET 245 reflects something that has already been processed and is 246 historical in nature. Use of this claim is NOT RECOMMENDED. 248 iat 249 A value identifying the time at which the SET was issued, as 250 defined by Section 4.1.6 of [RFC7519]. Since SETs typically 251 describe events that have already occurred, this is likely to be 252 different from the value stored in the "event_time" payload claim 253 (see below). This claim is REQUIRED. 255 jti 256 A unique identifier for an event, as defined by Section 4.1.7 of 257 [RFC7519]. This claim is REQUIRED. 259 This specification defines the following new claims for use in the 260 SET envelope: 262 event 263 A JSON object known as the "event payload", whose contents 264 identify the type of event contained within the SET and contain 265 additional information defined as part of an event type definition 266 in a Profiling Specification. 268 This specification defines the following claims for use in event 269 payloads: 271 event_type 272 A string containing a URI that uniquely identifies an event type 273 defined by a Profiling Specification. This claim is REQUIRED. 275 event_id 276 A string that identifies a specific "real world" event or state 277 change to which this event is related. Recipients MAY use this 278 claim to correlate events across different SETs received at 279 different times and/or by different systems. The value of this 280 claim MUST be unique with respect to the transmitter to a specific 281 "real world" event or state change, however recipients MUST NOT 282 interpret a difference in "event_id" values as a guarantee that 283 two events are not related. This claim is OPTIONAL. 285 event_subject 286 A Subject Identifier that identifies the subject of the event. 287 (See: Section 2.2) This claim is RECOMMENDED. Profiling 288 Specifications MAY omit this claim if the subject is implicitly 289 known, or if the subject is identified by the JWT "sub" claim, in 290 order to be compatible with one or more other specifications (e.g. 291 [OpenID.Core]). Profiling Specifications that use the JWT "sub" 292 claim MUST reference the document that defines the semantics for 293 that claim that the Profiling Specification is following, and MUST 294 omit the "event_subject" payload claim. 296 event_time 297 A number identifying the date and time at which the event is 298 believed to have occurred or will occur in the future. Its value 299 MUST take the form of a NumericDate value, as defined in Section 2 300 of [RFC7519]. This claim is OPTIONAL, however if it is not 301 present then the recipient MUST interpret that to mean that no 302 event time is being asserted, either because there is no specific 303 event time, the transmitter does not wish to share it, or the 304 transmitter does not know its value. 306 Both the SET envelope and event payload MAY contain additional 307 claims, such as those defined in a Profiling Specification. The 308 format and meaning of these claims is out of scope of this 309 specification. Implementations SHOULD ignore any claims in the SET 310 envelope or event payload that they do not understand. 312 The following is a non-normative example showing a SET envelope 313 expressing a hypothetical event with two additional claims in the 314 event payload: 316 { 317 "jti": "3d0c3cf797584bd193bd0fb1bd4e7d30", 318 "iss": "https://transmitter.example.com", 319 "aud": [ "https://receiver.example.com" ], 320 "iat": 1458496025, 321 "event": { 322 "event_type": "https://secevent.example.com/example_event", 323 "event_subject": { 324 "identifier_type": "urn:ietf:params:secevent:subject:email", 325 "email": "user@example.com" 326 }, 327 "event_time": 1458492425, 328 "claim_1": "foo", 329 "claim_2": "bar" 330 } 331 } 333 Figure 1: Example SET With Event Claims In Payload 335 The payload in this example contains the following: 337 o An "event_type" claim whose value is the URI identifying the 338 hypothetical event type. 340 o An "event_subject" claim whose value identifies a subject via 341 email address. 343 o An "event_time" claim whose value is the time at which the event 344 occured. 346 o Two claims "claim_1" and "claim_2" that are defined by the 347 hypothetical event type's Profiling Specification. 349 2.2. Subject Identifiers 351 The Subject Identifier provides a common syntax for expressing the 352 subject of a security event. A Subject Identifier is a JSON object 353 representing an instance of a Subject Identifier Type. A Subject 354 Identifier Type defines a way of identifying the subject of an event. 355 Typically this is done by defining a set of one or more claims about 356 a subject that when taken together collectively identify that 357 subject. Each Subject Identifier Type MUST have a name which MUST be 358 registered in the IANA "SET Subject Identifier Types" registry 359 established by Section 7.1. 361 A Subject Identifier MUST contain an "identifier_type" claim, whose 362 value is a string containing the name of the Subject Identifier's 363 Subject Identifier Type. All other claims within the Subject 364 Identifier MUST be defined by the Subject Identifier Type. 366 The names of the Subject Identifier Types defined below are 367 registered in the IANA "SET Subject Identifier Types" registry 368 established by Section 7.1. 370 2.2.1. Email Subject Identifier Type 372 The "Email" Subject Identifier Type identifies a subject by email 373 address. It has the name "email", and contains a single additional 374 claim: 376 email 377 A string containing an email address. Its value SHOULD conform to 378 [RFC5322]. This claim is REQUIRED. 380 The following is a non-normative example of a Subject Identifier 381 representing an instance of the Email Subject Identifier Type: 383 { 384 "identifier_type": "email", 385 "email": "user@example.com" 386 } 388 Figure 2: An Instance of the Email Subject Identifier Type 390 2.2.2. Phone Number Subject Identifier Type 392 The "Phone Number" Subject Identifier Type identifies a subject by 393 phone number. It has the name "phone_number", and contains a single 394 claim: 396 phone_number 397 A string containing a phone number. It SHOULD be formatted 398 according to [E.164]. This claim is REQUIRED. 400 The following is a non-normative example of a Subject Identifier 401 representing an instance of the Phone Number Subject Identifier Type: 403 { 404 "identifier_type": "phone_number", 405 "phone_number": "+1 206 555 0123" 406 } 408 Figure 3: An Instance of the Phone Number Subject Identifier Type 410 2.2.3. Issuer and Subject Subject Identifier Type 412 The "Issuer and Subject" Subject Identifier Type identifies a subject 413 by an issuer and subject pair. It has the name "iss-sub", and 414 contains two claims: 416 iss 417 A case-sensitive string identifying the principal who is 418 responsible for assignment of the identifier in the "sub" claim, 419 as defined by Section 4.1.1 of [RFC7519]. This claim is REQUIRED. 421 sub 422 A case-sensitive string containing an identifier that identifies a 423 subject within the context of the principal identified by the 424 "iss" claim, as defined by Section 4.1.2 of [RFC7519]. This claim 425 is REQUIRED. 427 The following is a non-normative example of a Subject Identifier 428 representing an instance of the Issuer and Subject Subject Identifier 429 Type: 431 { 432 "identifier_type": "iss-sub", 433 "iss": "http://id.example.com", 434 "sub": "example.user.1234" 435 } 437 Figure 4: An Instance of the Issuer and Subject Subject Identifier 438 Type 440 2.3. Explicit Typing of SETs 442 This specification registers the "application/secevent+jwt" media 443 type. SETs MAY include this media type in the "typ" header parameter 444 of the JWT containing the SET to explicitly declare that the JWT is a 445 SET. This MUST be included if the SET could be used in an 446 application context in which it could be confused with other kinds of 447 JWTs. Profiling Specifications MAY declare that this is REQUIRED for 448 SETs containing events defined by the Profiling Specification. 450 Per the definition of "typ" in Section 4.1.9 of [RFC7515], it is 451 RECOMMENDED that the "application/" prefix be omitted. Therefore, 452 the "typ" value used SHOULD be "secevent+jwt". 454 2.4. Security Event Token Construction 456 A SET is a JWT, and therefore it's construction follows that 457 described in [RFC7519]. 459 While this specification uses JWT to convey a SET, implementers SHALL 460 NOT use SETs to convey authentication or authorization assertions. 462 The following is the example JWT Claims Set from Figure 1, expressed 463 as an unsigned JWT. The JOSE Header is: 465 {"typ":"secevent+jwt","alg":"none"} 467 Base64url encoding of the octets of the UTF-8 representation of the 468 JOSE Header yields: 470 eyJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJub25lIn0 472 The example JWT Claims Set is encoded as follows: 474 ewogICJqdGkiOiAiM2QwYzNjZjc5NzU4NGJkMTkzYmQwZmIxYmQ0ZTdkMzAiLAogICJp 475 c3MiOiAiaHR0cHM6Ly90cmFuc21pdHRlci5leGFtcGxlLmNvbSIsCiAgImF1ZCI6IFsg 476 Imh0dHBzOi8vcmVjZWl2ZXIuZXhhbXBsZS5jb20iIF0sCiAgImlhdCI6IDE0NTg0OTYw 477 MjUsCiAgImV2ZW50IjogewogICAgImV2ZW50X3R5cGUiOiAiaHR0cHM6Ly9zZWNldmVu 478 dC5leGFtcGxlLmNvbS9leGFtcGxlX2V2ZW50IiwKICAgICJldmVudF9zdWJqZWN0Ijog 479 ewogICAgICAiaWRlbnRpZmllcl90eXBlIjogInVybjppZXRmOnBhcmFtczpzZWNldmVu 480 dDpzdWJqZWN0OmVtYWlsIiwKICAgICAgImVtYWlsIjogInVzZXJAZXhhbXBsZS5jb20i 481 CiAgICB9LAogICAgImV2ZW50X3RpbWUiOiAxNDU4NDkyNDI1LAogICAgImNsYWltXzEi 482 OiAiZm9vIiwKICAgICJjbGFpbV8yIjogImJhciIKICB9Cn0 484 The encoded JWS signature is the empty string. Concatenating the 485 parts yields the following complete JWT: 487 eyJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJub25lIn0. 488 ewogICJqdGkiOiAiM2QwYzNjZjc5NzU4NGJkMTkzYmQwZmIxYmQ0ZTdkMzAiLAogICJp 489 c3MiOiAiaHR0cHM6Ly90cmFuc21pdHRlci5leGFtcGxlLmNvbSIsCiAgImF1ZCI6IFsg 490 Imh0dHBzOi8vcmVjZWl2ZXIuZXhhbXBsZS5jb20iIF0sCiAgImlhdCI6IDE0NTg0OTYw 491 MjUsCiAgImV2ZW50IjogewogICAgImV2ZW50X3R5cGUiOiAiaHR0cHM6Ly9zZWNldmVu 492 dC5leGFtcGxlLmNvbS9leGFtcGxlX2V2ZW50IiwKICAgICJldmVudF9zdWJqZWN0Ijog 493 ewogICAgICAiaWRlbnRpZmllcl90eXBlIjogInVybjppZXRmOnBhcmFtczpzZWNldmVu 494 dDpzdWJqZWN0OmVtYWlsIiwKICAgICAgImVtYWlsIjogInVzZXJAZXhhbXBsZS5jb20i 495 CiAgICB9LAogICAgImV2ZW50X3RpbWUiOiAxNDU4NDkyNDI1LAogICAgImNsYWltXzEi 496 OiAiZm9vIiwKICAgICJjbGFpbV8yIjogImJhciIKICB9Cn0. 498 Figure 5: Example Unsecured Security Event Token 500 For the purpose of a simpler example in Figure 5, an unsecured token 501 was shown. When SETs are not signed or encrypted, the Event Receiver 502 MUST employ other mechanisms such as TLS and HTTP to provide 503 integrity, confidentiality, and issuer validation, as needed by the 504 application. 506 When validation (i.e. auditing), or additional transmission security 507 is required, JWS signing and/or JWE encryption MAY be used. To 508 create and or validate a signed and/or encrypted SET, follow the 509 instructions in Section 7 of [RFC7519]. 511 3. Related Events 513 In order to accommodate use cases that require communicating multiple 514 related security events to an Event Receiver, this section defines 515 the "Related Events" event type. A Related Events event is 516 essentially a container for two or more events that are related to 517 one another, in that they represent or express different aspects of 518 the same event or state change. The Related Events event SHOULD NOT 519 be used to combine unrelated events into a single set, and MUST NOT 520 be used as a general purpose batch transmission mechanism. Profiling 521 Specifications that require an event grouping mechanism with these or 522 other semantics are encouraged to define additional event types for 523 their use cases. 525 The event type for the Related Events event is the URN 526 "urn:ietf:secevents:related_events". 528 The Related Events event has a single additional event payload claim: 530 events 531 An array of event payloads, as defined in this document. These 532 event payloads can be referred to as Nested Events for the Related 533 Events event. This claim is REQUIRED. 535 3.1. Processing Related Events 537 Nested Events can inherit the "event_id", "event_subject", and 538 "event_time" claims from the Related Events payload. Transmitters 539 MAY omit some, all, or none of these claims from a Nested Event. 540 Transmitters MAY omit claims from some Nested Events and include them 541 in others within the same Related Events event. When a claim is 542 omitted, recipients MUST use the value of the corresponding claim in 543 the Related Event event's payload. 545 The following is a non-normative example of a SET containing a 546 Related Events event: 548 { 549 "jti": "1c0038c2-02db-40de-ad50-122a64724166", 550 "iss": "https://transmitter.example.com", 551 "aud": [ "https://receiver.example.com" ], 552 "iat": 1510666261, 553 "event": { 554 "event_type": "urn:ietf:secevent:related_events", 555 "event_subject": { 556 "identifier_type": "email", 557 "email": "user@example.com" 558 }, 559 "event_id": "container", 560 "event_time": 1510662661, 561 "events": [ 562 { 563 "event_id": "nested_1", 564 "event_type": "http://specs.example.com/set_profile/event_1" 565 }, 566 { 567 "event_id": "nested_2", 568 "event_type": "http://specs.example.com/set_profile/event_2", 569 "event_time": 151059061 570 } 571 ] 572 } 573 } 575 Figure 6: Example SET Containing A Related Events Event 577 The following table demonstrates how Nested Events inherit values for 578 omitted claims: 580 +-----------+------------+-------------------------------+ 581 | Event ID | Event Time | Event Subject | 582 +-----------+------------+-------------------------------+ 583 | container | 151062661 | { | 584 +-----------+ | "identifier_type": "email", | 585 | nested_1 | | "email": "user@example.com" | 586 +-----------+------------+ } | 587 | nested_2 | 151059061 | | 588 +-----------+------------+-------------------------------+ 590 Figure 7: Example of Event Payloads Inheriting Values for Omitted 591 Claims 593 Since the Nested Event with event ID "nested_1" omits the 594 "event_time" claim, it inherits the event time from the Related 595 Events event payload. Similarly, since both Nested Events "nested_1" 596 and "nested_2" omit the "event_subject" claim, both inherit the event 597 subject from the Related Events event payload. 599 4. Requirements for SET Profiles 601 Profiling Specifications for SETs define the syntax and semantics of 602 SETs conforming to that SET profile and rules for validating those 603 SETs. The syntax defined by Profiling Specifications includes what 604 SET envelope and event payload claims are used by SETs expressing and 605 event defined by the profile. 607 Defining the semantics of the SET contents for SETs utilizing the 608 profile is equally important. Possibly most important is defining 609 the procedures used to validate the SET issuer and to obtain the keys 610 controlled by the issuer that were used for cryptographic operations 611 used in the JWT representing the SET. For instance, some profiles 612 may define an algorithm for retrieving the SET issuer's keys that 613 uses the "iss" claim value as its input. Likewise, if the profile 614 allows (or requires) that the JWT be unsecured, the means by which 615 the integrity of the JWT is ensured MUST be specified. 617 Profiling Specifications MUST define how the event Subject is 618 identified in the SET, as well as how to differentiate between the 619 event Subject's Issuer and the SET Issuer, if applicable. It is NOT 620 RECOMMENDED for Profiling Specifications to use the "sub" claim 621 defined in [RFC7519] in cases in which the Subject is not globally 622 unique and has a different Issuer from the SET itself. 624 Profiling Specifications MUST clearly specify the steps that a 625 recipient of a SET utilizing that profile MUST perform to validate 626 that the SET is both syntactically and semantically valid. 628 4.1. Extending Events 630 As needs change and new use cases develop, it may be desirable to 631 augment existing event definitions with new claims. In order to 632 avoid collisions, Profiling Specifications that extend existing 633 events with additional event payload claims SHOULD use Collision- 634 Resistant Names as defined in Section 2 of [RFC7519] for the names of 635 the new claims. 637 5. Security Considerations 639 5.1. Confidentiality and Integrity 641 SETs may often contain sensitive information. Therefore, methods for 642 distribution of events SHOULD require the use of a transport-layer 643 security mechanism when distributing events. Parties MUST support 644 TLS 1.2 [RFC5246] and MAY support additional transport-layer 645 mechanisms meeting its security requirements. When using TLS, the 646 client MUST perform a TLS/SSL server certificate check, per 647 [RFC6125]. Implementation security considerations for TLS can be 648 found in "Recommendations for Secure Use of TLS and DTLS" [RFC7525]. 650 Security Events distributed through third-parties or that carry 651 personally identifiable information, SHOULD be encrypted using JWE 652 [RFC7516] or secured for confidentiality by other means. 654 Unless integrity of the JWT is ensured by other means, it MUST be 655 signed using JWS [RFC7515] so that individual events can be 656 authenticated and validated by the Event Receiver. 658 5.2. Delivery 660 This specification does not define a delivery mechanism by itself. 661 In addition to confidentiality and integrity (discussed above), 662 implementers and Profiling Specifications MUST consider the 663 consequences of delivery mechanisms that are not secure and/or not 664 assured. For example, while a SET may be end-to-end secured using 665 JWE encrypted SETs, without TLS there is no assurance that the 666 correct endpoint received the SET and that it could be successfully 667 processed. 669 5.3. Sequencing 671 As defined in this specification, there is no defined way to order 672 multiple SETs in a sequence. Depending on the type and nature of SET 673 event, order may or may not matter. For example, in provisioning, 674 event order is critical - an object could not be modified before it 675 was created. In other SET types, such as a token revocation, the 676 order of SETs for revoked tokens does not matter. If however, the 677 event was described as a log-in or logged-out status for a user 678 subject, then order becomes important. 680 Profiling Specifications and implementers SHOULD take caution when 681 using timestamps such as "iat" to define order. Distributed systems 682 will have some amount of clock-skew and thus time by itself will not 683 guarantee order. 685 Specifications profiling SET SHOULD define a mechanism for detecting 686 order or sequence of events. 688 5.4. Timing Issues 690 When SETs are delivered asynchronously and/or out-of-band with 691 respect to the original action that incurred the security event, it 692 is important to consider that a SET might be delivered to an Event 693 Receiver in advance or well behind the process that caused the event. 694 For example, a user having been required to logout and then log back 695 in again, may cause a logout SET to be issued that may arrive at the 696 same time as the user-agent accesses a web site having just logged- 697 in. If timing is not handled properly, the effect would be to 698 erroneously treat the new user session as logged out. Profiling 699 Specifications SHOULD be careful to anticipate timing and subject 700 selection information. For example, it might be more appropriate to 701 cancel a "session" rather than a "user". Alternatively, the 702 specification could use timestamps that allows new sessions to be 703 started immediately after a stated logout event time. 705 5.5. Distinguishing SETs from ID Tokens 707 Because [RFC7519] states that "all claims that are not understood by 708 implementations MUST be ignored", there is a consideration that a SET 709 token might be confused with ID Token [OpenID.Core] if a SET is 710 mistakenly or intentionally used in a context requiring an ID Token. 711 If a SET could otherwise be interpreted as a valid ID Token (because 712 it includes the required claims for an ID Token and valid issuer and 713 audience claim values for an ID Token) then that SET profile MUST 714 require that the "exp" claim not be present in the SET. Because 715 "exp" is a required claim in ID Tokens, valid ID Token 716 implementations will reject such a SET if presented as if it were an 717 ID Token. 719 Excluding "exp" from SETs that could otherwise be confused with ID 720 Tokens is actually defense in depth. In any OpenID Connect contexts 721 in which an attacker could attempt to substitute a SET for an ID 722 Token, the SET would actually already be rejected as an ID Token 723 because it would not contain the correct "nonce" claim value for the 724 ID Token to be accepted in contexts for which substitution is 725 possible. 727 Note that the use of explicit typing, as described in Section 2.2, 728 will not achieve disambiguation between ID Tokens and SETs, as the ID 729 Token validation rules do not use the "typ" header parameter value. 731 5.6. Distinguishing SETs from Access Tokens 733 OAuth 2.0 [RFC6749] defines access tokens as being opaque. 734 Nonetheless, some implementations implement access tokens as JWTs. 735 Because the structure of these JWTs is implementation-specific, 736 ensuring that a SET cannot be confused with such an access token is 737 therefore likewise, in general, implementation specific. 738 Nonetheless, it is recommended that SET profiles employ the following 739 strategies to prevent possible substitutions of SETs for access 740 tokens in contexts in which that might be possible: 742 o Prohibit use of the "exp" claim, as is done to prevent ID Token 743 confusion. 745 o Where possible, use a separate "aud" claim value to distinguish 746 between the Event Receiver and the protected resource that is the 747 audience of an access token. 749 o Modify access token validation systems to check for the presence 750 of the "events" claim as a means to detect security event tokens. 751 This is particularly useful if the same endpoint may receive both 752 types of tokens. 754 o Employ explicit typing, as described in Section 2.2, and modify 755 access token validation systems to use the "typ" header parameter 756 value. 758 5.7. Distinguishing SETs from other kinds of JWTs 760 JWTs are now being used in application areas beyond the identity 761 applications in which they first appeared. For instance, the Session 762 Initiation Protocol (SIP) Via Header Field [RFC8055] and Personal 763 Assertion Token (PASSporT) [I-D.ietf-stir-passport] specifications 764 both define JWT profiles that use mostly or completely different sets 765 of claims than are used by ID Tokens. If it would otherwise be 766 possible for an attacker to substitute a SET for one of these (or 767 other) kinds of JWTs, then the SET profile must be defined in such a 768 way that any substituted SET will result in its rejection when 769 validated as the intended kind of JWT. 771 The most direct way to prevent confusion is to employ explicit 772 typing, as described in Section 2.2, and modify applicable token 773 validation systems to use the "typ" header parameter value. This 774 approach can be employed for new systems but may not be applicable to 775 existing systems. 777 Another way to ensure that a SET is not confused with another kind of 778 JWT is to have the JWT validation logic reject JWTs containing an 779 "events" claim unless the JWT is intended to be a SET. This approach 780 can be employed for new systems but may not be applicable to existing 781 systems. 783 For many use cases, the simplest way to prevent substitution is 784 requiring that the SET not include claims that are required for the 785 kind of JWT that might be the target of an attack. For example, for 786 [RFC8055], the "sip_callid" claim could be omitted and for 787 [I-D.ietf-stir-passport], the "orig" claim could be omitted. 789 In many contexts, simple measures such as these will accomplish the 790 task, should confusion otherwise even be possible. Note that this 791 topic is being explored in a more general fashion in JSON Web Token 792 Best Current Practices [I-D.sheffer-oauth-jwt-bcp]. The proposed 793 best practices in that draft may also be applicable for particular 794 SET profiles and use cases. 796 6. Privacy Considerations 798 If a SET needs to be retained for audit purposes, JWS MAY be used to 799 provide verification of its authenticity. 801 Event Transmitters SHOULD attempt to specialize feeds so that the 802 content is targeted to the specific business and protocol needs of an 803 Event Receiver. 805 When sharing personally identifiable information or information that 806 is otherwise considered confidential to affected users, Event 807 Transmitters and Receivers MUST have the appropriate legal agreements 808 and user consent or terms of service in place. 810 The propagation of subject identifiers can be perceived as personally 811 identifiable information. Where possible, Event Transmitters and 812 Receivers SHOULD devise approaches that prevent propagation - for 813 example, the passing of a hash value that requires the Event Receiver 814 to know the subject. 816 7. IANA Considerations 818 7.1. SET Subject Identifier Types Registry 820 This section establishes the IANA "SET Subject Identifier Types" 821 registry // TODO 823 7.2. JSON Web Token Claims Registration 825 This specification registers the "event" claim in the IANA "JSON Web 826 Token Claims" registry [IANA.JWT.Claims] established by [RFC7519]. 828 7.2.1. Registry Contents 830 o Claim Name: "event" 832 o Claim Description: Security Event Payload 834 o Change Controller: IESG 836 o Specification Document(s): Section 2.1 of [[ this specification ]] 838 7.3. Media Type Registration 840 7.3.1. Registry Contents 842 This section registers the "application/secevent+jwt" media type 843 [RFC2046] in the "Media Types" registry [IANA.MediaTypes] in the 844 manner described in [RFC6838], which can be used to indicate that the 845 content is a SET. 847 o Type name: application 849 o Subtype name: secevent+jwt 851 o Required parameters: n/a 853 o Optional parameters: n/a 855 o Encoding considerations: 8bit; A SET is a JWT; JWT values are 856 encoded as a series of base64url-encoded values (some of which may 857 be the empty string) separated by period ('.') characters. 859 o Security considerations: See the Security Considerations section 860 of [[ this specification ]] 862 o Interoperability considerations: n/a 864 o Published specification: Section 2.2 of [[ this specification ]] 866 o Applications that use this media type: TBD 868 o Fragment identifier considerations: n/a 870 o Additional information: 872 o Magic number(s): n/a 874 o File extension(s): n/a 875 o Macintosh file type code(s): n/a 877 o Person & email address to contact for further information: Michael 878 B. Jones, mbj@microsoft.com 880 o Intended usage: COMMON 882 o Restrictions on usage: none 884 o Author: Michael B. Jones, mbj@microsoft.com 886 o Change controller: IESG 888 o Provisional registration? No 890 8. References 892 8.1. Normative References 894 [E.164] International Telecommunication Union, "The international 895 public telecommunication numbering plan", 2010, 896 . 898 [IANA.JWT.Claims] 899 IANA, "JSON Web Token Claims", n.d., 900 . 902 [IANA.MediaTypes] 903 IANA, "Media Types", n.d., 904 . 906 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 907 Requirement Levels", BCP 14, RFC 2119, 908 DOI 10.17487/RFC2119, March 1997, 909 . 911 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 912 Resource Identifier (URI): Generic Syntax", STD 66, 913 RFC 3986, DOI 10.17487/RFC3986, January 2005, 914 . 916 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 917 (TLS) Protocol Version 1.2", RFC 5246, 918 DOI 10.17487/RFC5246, August 2008, 919 . 921 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 922 DOI 10.17487/RFC5322, October 2008, 923 . 925 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 926 Verification of Domain-Based Application Service Identity 927 within Internet Public Key Infrastructure Using X.509 928 (PKIX) Certificates in the Context of Transport Layer 929 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 930 2011, . 932 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 933 RFC 6749, DOI 10.17487/RFC6749, October 2012, 934 . 936 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 937 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 938 . 940 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 941 "Recommendations for Secure Use of Transport Layer 942 Security (TLS) and Datagram Transport Layer Security 943 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 944 2015, . 946 8.2. Informative References 948 [I-D.ietf-stir-passport] 949 Wendt, C. and J. Peterson, "Personal Assertion Token 950 (PASSporT)", draft-ietf-stir-passport-11 (work in 951 progress), February 2017. 953 [I-D.sheffer-oauth-jwt-bcp] 954 Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best 955 Current Practices", draft-sheffer-oauth-jwt-bcp-01 (work 956 in progress), July 2017. 958 [OpenID.Core] 959 "OpenID Connect Core 1.0", n.d., 960 . 962 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 963 Extensions (MIME) Part Two: Media Types", RFC 2046, 964 DOI 10.17487/RFC2046, November 1996, 965 . 967 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 968 Specifications and Registration Procedures", BCP 13, 969 RFC 6838, DOI 10.17487/RFC6838, January 2013, 970 . 972 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 973 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 974 2015, . 976 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 977 RFC 7516, DOI 10.17487/RFC7516, May 2015, 978 . 980 [RFC8055] Holmberg, C. and Y. Jiang, "Session Initiation Protocol 981 (SIP) Via Header Field Parameter to Indicate Received 982 Realm", RFC 8055, DOI 10.17487/RFC8055, January 2017, 983 . 985 Appendix A. Acknowledgments 987 The editors would like to thank Phil Hunt for his SET draft - on 988 which much of this specification is based - and his continuing 989 contributions to this draft. 991 The editors would like to thank the participants on the IETF secevent 992 mailing list and related working groups for their support of this 993 specification. 995 Appendix B. Change Log 997 Draft 00 - A. Backman - Forked from draft-ietf-secevent-token-03 999 o Cleaned up text in section 2. 1001 o Simplified JWT claim descriptions in section 2.1. 1003 o Removed "txn" claim. 1005 o Replaced multi-part "events" claim with "event" claim that 1006 contains a single event payload. 1008 o Removed references to JWT "sub" claim and added 1009 "event.event_subject" claim. 1011 o Replaced JWT "toe" claim with "event.event_time" claim. 1013 o Added Subject Identifier Types and defined "implicit", "email", 1014 "phone_number", and "iss_sub" types. 1016 o Added Related Events event definition. 1018 o Added guidance for event extensions. 1020 Draft 01 - A. Backman 1022 o Added Acknowledgements section. 1024 o Relaxed event_subject claim definition to allow usage of JWT "sub" 1025 claim. 1027 Draft 02 - A. Backman 1029 o Added text to iat claim definition clarifying the difference 1030 between iat and event_time. 1032 o Removed "implicit" Subject Identifier Type. 1034 Authors' Addresses 1036 Annabelle Backman 1037 Amazon 1039 Email: richanna@amazon.com 1041 William Denniss 1042 Google 1044 Email: wdenniss@google.com 1046 Morteza Ansari 1047 Cisco 1049 Email: morteza.ansari@cisco.com 1051 Michael B. Jones 1052 Microsoft 1054 Email: mbj@microsoft.com 1055 URI: http://self-issued.info/