idnits 2.17.1 draft-ietf-secevent-token-05.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 (February 2, 2018) is 2275 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) == Unused Reference: 'RFC7617' is defined on line 907, but no explicit reference was found in the text == Unused Reference: 'RFC7009' is defined on line 942, but no explicit reference was found in the text == Unused Reference: 'RFC7517' is defined on line 954, but no explicit reference was found in the text ** 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) == Outdated reference: A later version (-07) exists of draft-ietf-oauth-jwt-bcp-00 Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Security Events Working Group P. Hunt, Ed. 3 Internet-Draft Oracle 4 Intended status: Standards Track M. Jones 5 Expires: August 6, 2018 Microsoft 6 W. Denniss 7 Google 8 M. Ansari 9 Cisco 10 February 2, 2018 12 Security Event Token (SET) 13 draft-ietf-secevent-token-05 15 Abstract 17 This specification defines the Security Event Token (SET) data 18 structure. A SET describes a statement of fact from the perspective 19 of an issuer, which is intended to be shared with one or more 20 recipients. A SET is a JSON Web Token (JWT), which can be optionally 21 signed and/or encrypted. SETs can be distributed via protocols such 22 as HTTP. 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 August 6, 2018. 41 Copyright Notice 43 Copyright (c) 2018 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 and Overview . . . . . . . . . . . . . . . . . . 2 59 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 60 1.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 61 2. The Security Event Token (SET) . . . . . . . . . . . . . . . 5 62 2.1. Illustrative Examples . . . . . . . . . . . . . . . . . . 6 63 2.1.1. SCIM Example . . . . . . . . . . . . . . . . . . . . 6 64 2.1.2. Logout Example . . . . . . . . . . . . . . . . . . . 7 65 2.1.3. Consent Example . . . . . . . . . . . . . . . . . . . 7 66 2.1.4. RISC Example . . . . . . . . . . . . . . . . . . . . 8 67 2.2. Core SET Claims . . . . . . . . . . . . . . . . . . . . . 9 68 2.3. Explicit Typing of SETs . . . . . . . . . . . . . . . . . 11 69 2.4. Security Event Token Construction . . . . . . . . . . . . 11 70 3. Requirements for SET Profiles . . . . . . . . . . . . . . . . 13 71 4. Security Considerations . . . . . . . . . . . . . . . . . . . 14 72 4.1. Confidentiality and Integrity . . . . . . . . . . . . . . 14 73 4.2. Delivery . . . . . . . . . . . . . . . . . . . . . . . . 14 74 4.3. Sequencing . . . . . . . . . . . . . . . . . . . . . . . 15 75 4.4. Timing Issues . . . . . . . . . . . . . . . . . . . . . . 15 76 4.5. Distinguishing SETs from ID Tokens . . . . . . . . . . . 15 77 4.6. Distinguishing SETs from Access Tokens . . . . . . . . . 16 78 4.7. Distinguishing SETs from other kinds of JWTs . . . . . . 17 79 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 17 80 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 81 6.1. JSON Web Token Claims Registration . . . . . . . . . . . 18 82 6.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 18 83 6.2. Media Type Registration . . . . . . . . . . . . . . . . . 19 84 6.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 19 85 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 86 7.1. Normative References . . . . . . . . . . . . . . . . . . 19 87 7.2. Informative References . . . . . . . . . . . . . . . . . 21 88 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 22 89 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 22 90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 92 1. Introduction and Overview 94 This specification defines an extensible Security Event Token (SET) 95 data structure, which can be exchanged using protocols such as HTTP. 96 The specification builds on the JSON Web Token (JWT) format [RFC7519] 97 in order to provide a self-contained token that can be optionally 98 signed using JSON Web Signature (JWS) [RFC7515] and/or encrypted 99 using JSON Web Encryption (JWE) [RFC7516]. 101 This specification profiles the use of JWT for the purpose of issuing 102 Security Event Tokens (SETs). This specification defines a base 103 format used by profiling specifications to define actual events and 104 their meanings. This specification uses non-normative example events 105 to demonstrate how events can be constructed. 107 This specification is scoped to security and identity related events. 108 While security event tokens may be used for other purposes, the 109 specification only considers security and privacy concerns relevant 110 to identity and personal information. 112 Security Events are not commands issued between parties. A security 113 event is a statement of fact from the perspective of an issuer about 114 the state of a security subject (e.g., a web resource, token, IP 115 address, the issuer itself) that the issuer controls or is aware of, 116 that has changed in some way (explicitly or implicitly). A security 117 subject MAY be permanent (e.g., a user account) or temporary (e.g., 118 an HTTP session) in nature. A state change could describe a direct 119 change of entity state, an implicit change of state, or other higher- 120 level security statements such as: 122 o The creation, modification, removal of a resource. 124 o The resetting or suspension of an account. 126 o The revocation of a security token prior to its expiry. 128 o The logout of a user session. Or, 130 o An indication that a user has been given control of an email 131 identifier that was previously controlled by another user. 133 While subject state changes are often triggered by a user agent or 134 security subsystem, the issuance and transmission of an event may 135 occur asynchronously and in a back channel to the action that caused 136 the change that generated the security event. Subsequently, an Event 137 Recipient, having received a SET, validates and interprets the 138 received SET and takes its own independent actions, if any. For 139 example, having been informed of a personal identifier being 140 associated with a different security subject (e.g., an email address 141 is being used by someone else), the Event Recipient may choose to 142 ensure that the new user is not granted access to resources 143 associated with the previous user. Or, the Event Recipient may not 144 have any relationship with the subject, and no action is taken. 146 While Event Recipients will often take actions upon receiving SETs, 147 security events cannot be assumed to be commands or requests. The 148 intent of this specification is to define a syntax for statements of 149 fact that Event Recipients may interpret for their own purposes. As 150 such, SETs have no capability for error signaling to ensure the 151 validation of a received SET. 153 1.1. Notational Conventions 155 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 156 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 157 "OPTIONAL" in this document are to be interpreted as described in BCP 158 14 [RFC2119] [RFC8174] when, and only when, they appear in all 159 capitals, as shown here. 161 For purposes of readability, examples are not URL encoded. 162 Implementers MUST percent encode URLs as described in Section 2.1 of 163 [RFC3986]. 165 Throughout this document, all figures MAY contain spaces and extra 166 line-wrapping for readability and space limitations. Similarly, some 167 URIs contained within examples have been shortened for space and 168 readability reasons. 170 1.2. Definitions 172 The following definitions are used with SETs: 174 Security Event Token (SET) 175 A SET is a JWT [RFC7519] conforming to this specification that is 176 distributed to one or more Event Recipients. 178 Event Issuer 179 A service provider that creates SETs to be sent to other providers 180 known as Event Recipients. 182 Event Recipient 183 An Event Recipient is an entity that receives SETs through some 184 distribution method. An Event Recipient is the same entity 185 referred as a "recipient" or "receiver" in [RFC7519] and related 186 specifications. 188 Subject 189 A SET describes an event or state change that has occurred about a 190 Subject. A Subject might, for instance, be a principal (e.g., 191 Section 4.1.2 of [RFC7519]), a web resource, an entity such as an 192 IP address, or the issuer of the SET. 194 Profiling Specification 195 A specification that profiles the SET data structure to define one 196 or more specific event types and their associated claims and 197 processing rules. 199 2. The Security Event Token (SET) 201 A SET is a JWT [RFC7519] data structure that represents one or more 202 related aspects of a security event about a Subject. The JWT Claims 203 Set in a SET has the following structure: 205 o The top-level claims in the JWT Claims Set are called the SET 206 "envelope". Some of these claims are present in every SET; others 207 will be specific to particular SET profiles or profile families. 208 Claims in the envelope SHOULD be registered in the "JSON Web Token 209 Claims" registry [IANA.JWT.Claims] or be Public Claims or Private 210 Claims, as defined in [RFC7519]. 212 o Envelope claims that are profiled and defined in this 213 specification are used to validate the SET and provide information 214 about the event data included in the SET. The claim "events" 215 contains the event identifiers and event-specific data expressed 216 about the Security Subject. The envelope MAY include event- 217 specific or profile-specific data. 219 o Each member of the "events" JSON object is a name/value pair. The 220 JSON member name is a URI string value is an event identifier, and 221 the corresponding value is a JSON object known as the event 222 "payload". The payload JSON object contains claims that pertain 223 to that event identifier and need not be registered as JWT claims. 224 These claims are defined by the Profiling Specification that 225 defines the event. An event with no payload claims SHALL be 226 represented as the empty JSON object ("{}"). 228 o When multiple event identifiers are contained in a SET, they 229 represent multiple aspects of the same state transition that 230 occurred to the Security Subject. They are not intended to be 231 used to aggregate distinct events about the same subject. Beyond 232 this, the interpretation of SETs containing multiple event 233 identifiers is out of scope for this specification; Profiling 234 Specifications MAY define their own rules regarding their use of 235 SETs containing multiple event identifiers, as described in 236 Section 3. Possible uses of multiple values include, but are not 237 limited to: 239 * Values to provide classification information (e.g., threat type 240 or level). 242 * Additions to existing event representations. 244 * Values used to link potential series of events. 246 * Specific-purpose event URIs used between particular Event 247 Issuers and Event Recipients. 249 2.1. Illustrative Examples 251 2.1.1. SCIM Example 253 The following is a non-normative example showing the JWT Claims Set 254 for a hypothetical SCIM [RFC7644] password reset SET. This example 255 uses a second "events" value ("https://example.com/scim/event/ 256 passwordResetExt") to convey additional information about the state 257 change -- in this case, the current count of reset attempts: 259 { 260 "iss": "https://scim.example.com", 261 "iat": 1458496025, 262 "jti": "3d0c3cf797584bd193bd0fb1bd4e7d30", 263 "aud": [ 264 "https://jhub.example.com/Feeds/98d52461fa5bbc879593b7754", 265 "https://jhub.example.com/Feeds/5d7604516b1d08641d7676ee7" 266 ], 267 "sub": "https://scim.example.com/Users/44f6142df96bd6ab61e7521d9", 268 "events": { 269 "urn:ietf:params:scim:event:passwordReset": 270 { "id": "44f6142df96bd6ab61e7521d9"}, 271 "https://example.com/scim/event/passwordResetExt": 272 { "resetAttempts": 5} 273 } 274 } 276 Figure 1: Example SCIM Password Reset Event 278 The JWT Claims Set consists of: 280 o The "events" claim specifying the hypothetical SCIM URN 281 ("urn:ietf:params:scim:event:passwordReset") for a password reset, 282 and a second value, "https://example.com/scim/event/ 283 passwordResetExt", that is used to provide additional event 284 information such as the current count of resets. 286 o The "iss" claim, denoting the Event Issuer. 288 o The "sub" claim, specifying the SCIM resource URI that was 289 affected. 291 o The "aud" claim, specifying the intended audiences for the event. 292 (The syntax of the "aud" claim is defined in Section 4.1.3 of 293 [RFC7519].) 295 In this example, the SCIM event indicates that a password has been 296 updated and the current password reset count is 5. Notice that the 297 value for "resetAttempts" is in the event payload of an event used to 298 convey this information. 300 2.1.2. Logout Example 302 Here is another example JWT Claims Set for a security event token, 303 this one for a Logout Token: 305 { 306 "iss": "https://server.example.com", 307 "sub": "248289761001", 308 "aud": "s6BhdRkqt3", 309 "iat": 1471566154, 310 "jti": "bWJq", 311 "sid": "08a5019c-17e1-4977-8f42-65a12843ea02", 312 "events": { 313 "http://schemas.openid.net/event/backchannel-logout": {} 314 } 315 } 317 Figure 2: Example OpenID Back-Channel Logout Event 319 Note that the above SET has an empty JSON object and uses the JWT 320 registered claims "sub" and "sid" to identify the subject that was 321 logged out. 323 2.1.3. Consent Example 324 In the following example JWT Claims Set, a fictional medical service 325 collects consent for medical actions and notifies other parties. The 326 individual for whom consent is identified was originally 327 authenticated via OpenID Connect. In this case, the issuer of the 328 security event is an application rather than the OpenID provider: 330 { 331 "iss": "https://my.med.example.org", 332 "iat": 1458496025, 333 "jti": "fb4e75b5411e4e19b6c0fe87950f7749", 334 "aud": [ 335 "https://rp.example.com" 336 ], 337 "events": { 338 "https://openid.net/heart/specs/consent.html": { 339 "iss": "https://connect.example.com", 340 "sub": "248289761001", 341 "consentUri": [ 342 "https://terms.med.example.org/labdisclosure.html#Agree" 343 ] 344 } 345 } 346 } 348 Figure 3: Example Consent Event 350 In the above example, the attribute "iss" contained within the 351 payload for the event "https://openid.net/heart/specs/consent.html" 352 refers to the issuer of the Security Subject ("sub") rather than the 353 event issuer "https://my.med.example.org". They are distinct from 354 the top-level value of "iss", which always refers to the issuer of 355 the event -- a medical consent service that is a relying party to the 356 OpenID Provider. 358 2.1.4. RISC Example 359 The following example JWT Claims Set is for an account disabled 360 event. This example was taken from a working draft of the RISC 361 events specification, where RISC is the OpenID RISC (Risk and 362 Incident Sharing and Coordination) working group [RISC]. The example 363 is subject to change. 365 { 366 "iss": "https://idp.example.com/", 367 "jti": "756E69717565206964656E746966696572", 368 "iat": 1508184845, 369 "aud": "636C69656E745F6964", 370 "events": { 371 "http://schemas.openid.net/secevent/risc/event-type/\ 372 account-disabled": { 373 "subject": { 374 "subject_type": "iss-sub", 375 "iss": "https://idp.example.com/", 376 "sub": "7375626A656374" 377 }, 378 "reason": "hijacking", 379 "cause-time": 1508012752 380 } 381 } 382 } 384 Figure 4: Example RISC Event 386 Notice that parameters to the event are included in the event 387 payload, in this case, the "reason" and "cause-time" values. The 388 subject of the event is identified using the "subject" payload value, 389 which itself is a JSON object. 391 2.2. Core SET Claims 393 The following claims from [RFC7519] are profiled for use in SETs: 395 iss 396 A string identifying the service provider publishing the SET (the 397 issuer). In some cases, the SET issuer is not the issuer of the 398 Security Subject. Therefore, implementers cannot assume that the 399 issuers are the same unless the Profiling Specification specifies 400 that they are for SETs conforming to that profile. This claim is 401 REQUIRED. 403 iat 404 As defined by Section 4.1.6 of [RFC7519], a value representing 405 when the event was issued. This claim is REQUIRED. 407 jti 408 As defined by Section 4.1.7 of [RFC7519] contains a unique 409 identifier for an event. The identifier SHOULD be unique within a 410 particular event feed and MAY be used by clients to track whether 411 a particular event has already been received. This claim is 412 REQUIRED. 414 aud 415 The syntax of the claim is as defined in Section 4.1.3 of 416 [RFC7519]. This claim contains one or more audience identifiers 417 for the SET. This claim is RECOMMENDED. 419 sub 420 As defined by Section 4.1.2 of [RFC7519], a String or URI value 421 representing the principal or the subject of the SET. This is 422 usually the entity whose "state" was changed. For example, an IP 423 Address was added to a black list. A URI representing a user 424 resource that was modified. A token identifier for a revoked 425 token. If used, the Profiling Specification SHOULD define the 426 content and format semantics for the value. This claim is 427 OPTIONAL, as the principal for any given profile may already be 428 identified without the inclusion of a subject claim. Note that 429 some SET profiles MAY choose to convey event subject information 430 in the event payload (either using the "sub" member name or 431 another name), particularly if the subject information is relative 432 to issuer information that is also conveyed in the event payload, 433 which may be the case for some identity SET profiles. 435 exp 436 As defined by Section 4.1.4 of [RFC7519], this claim is time after 437 which the JWT MUST NOT be accepted for processing. In the context 438 of a SET however, this notion does not apply, since a SET 439 represents something that has already occurred and is historical 440 in nature. While some profiles MAY choose to use this claim, its 441 use is NOT RECOMMENDED. 443 The following new claims are defined by this specification: 445 events 446 This claim contains a set of event statements that each provide 447 information describing a single logical event that has occurred 448 about a Security Subject (e.g., a state change to the subject). 449 Multiple event identifiers with the same value MUST NOT be used. 450 The "events" claim SHOULD NOT be used to express multiple 451 independent logical events. 453 The value of the "events" claim is a JSON object whose members are 454 name/value pairs whose names are URIs identifying the event 455 statements being expressed. Event identifiers SHOULD be stable 456 values (e.g., a permanent URL for an event specification). For 457 each name present, the corresponding value MUST be a JSON object. 458 The JSON object MAY be an empty object ("{}"), or it MAY be a JSON 459 object containing data described by the Profiling Specification. 461 txn 462 An OPTIONAL string value that represents a unique transaction 463 identifier. In cases in which multiple related JWTs are issued, 464 the transaction identifier claim can be used to correlate these 465 related JWTs. 467 toe 468 A value that represents the date and time at which the event 469 occurred. This value is a NumericDate (see Section 2 of 470 [RFC7519]). By omitting this claim, the issuer indicates that 471 they are not sharing an event time with the recipient. (Note that 472 in some use cases, the represented time might be approximate.) 473 This claim is OPTIONAL. 475 2.3. Explicit Typing of SETs 477 This specification registers the "application/secevent+jwt" media 478 type, which can be used to indicate that the content is a SET. SETs 479 MAY include this media type in the "typ" header parameter of the JWT 480 representing the SET to explicitly declare that the JWT is a SET. 481 This MUST be included if the SET could be used in an application 482 context in which it could be confused with other kinds of JWTs. 484 Per the definition of "typ" in Section 4.1.9 of [RFC7515], it is 485 RECOMMENDED that the "application/" prefix be omitted. Therefore, 486 the "typ" value used SHOULD be "secevent+jwt". 488 2.4. Security Event Token Construction 490 This section describes how to construct a SET. 492 The following is an example JWT Claims Set for a hypothetical SCIM 493 SET (which has been formatted for readability): 495 { 496 "iss": "https://scim.example.com", 497 "iat": 1458496404, 498 "jti": "4d3559ec67504aaba65d40b0363faad8", 499 "aud": [ 500 "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754", 501 "https://scim.example.com/Feeds/5d7604516b1d08641d7676ee7" 502 ], 504 "events": { 505 "urn:ietf:params:scim:event:create": { 506 "ref": 507 "https://scim.example.com/Users/44f6142df96bd6ab61e7521d9", 508 "attributes": ["id", "name", "userName", "password", "emails"] 509 } 510 } 511 } 513 Figure 5: Example Event Claims 515 The JSON Claims Set is encoded per [RFC7519]. 517 In this example, the SCIM SET claims are encoded in an unsecured JWT. 518 The JOSE Header for this example is: 520 {"typ":"secevent+jwt","alg":"none"} 522 Base64url encoding of the octets of the UTF-8 representation of the 523 JOSE Header yields: 525 eyJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJub25lIn0 527 The above example JWT Claims Set is encoded as follows: 529 eyJqdGkiOiI0ZDM1NTllYzY3NTA0YWFiYTY1ZDQwYjAzNjNmYWFkOCIsImlhdCI6MTQ1 530 ODQ5NjQwNCwiaXNzIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tIiwiYXVkIjpbImh0 531 dHBzOi8vc2NpbS5leGFtcGxlLmNvbS9GZWVkcy85OGQ1MjQ2MWZhNWJiYzg3OTU5M2I3 532 NzU0IiwiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tL0ZlZWRzLzVkNzYwNDUxNmIxZDA4 533 NjQxZDc2NzZlZTciXSwiZXZlbnRzIjp7InVybjppZXRmOnBhcmFtczpzY2ltOmV2ZW50 534 OmNyZWF0ZSI6eyJyZWYiOiJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcnMvNDRm 535 NjE0MmRmOTZiZDZhYjYxZTc1MjFkOSIsImF0dHJpYnV0ZXMiOlsiaWQiLCJuYW1lIiwi 536 dXNlck5hbWUiLCJwYXNzd29yZCIsImVtYWlscyJdfX19 537 The encoded JWS signature is the empty string. Concatenating the 538 parts yields this complete SET: 540 eyJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJub25lIn0. 541 eyJqdGkiOiI0ZDM1NTllYzY3NTA0YWFiYTY1ZDQwYjAzNjNmYWFkOCIsImlhdCI6MTQ1 542 ODQ5NjQwNCwiaXNzIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tIiwiYXVkIjpbImh0 543 dHBzOi8vc2NpbS5leGFtcGxlLmNvbS9GZWVkcy85OGQ1MjQ2MWZhNWJiYzg3OTU5M2I3 544 NzU0IiwiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tL0ZlZWRzLzVkNzYwNDUxNmIxZDA4 545 NjQxZDc2NzZlZTciXSwiZXZlbnRzIjp7InVybjppZXRmOnBhcmFtczpzY2ltOmV2ZW50 546 OmNyZWF0ZSI6eyJyZWYiOiJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcnMvNDRm 547 NjE0MmRmOTZiZDZhYjYxZTc1MjFkOSIsImF0dHJpYnV0ZXMiOlsiaWQiLCJuYW1lIiwi 548 dXNlck5hbWUiLCJwYXNzd29yZCIsImVtYWlscyJdfX19. 550 Figure 6: Example Unsecured Security Event Token 552 For the purpose of having a simpler example in Figure 6, an unsecured 553 token is shown. When SETs are not signed or encrypted, the Event 554 Recipient MUST employ other mechanisms such as TLS to provide 555 integrity, confidentiality, and issuer validation, as needed by the 556 application. 558 When validation (i.e., auditing), or additional transmission security 559 is required, JWS signing and/or JWE encryption MAY be used. To 560 create and or validate a signed and/or encrypted SET, follow the 561 instructions in Section 7 of [RFC7519]. 563 3. Requirements for SET Profiles 565 Profiling Specifications for SETs define the syntax and semantics of 566 SETs conforming to that SET profile and rules for validating those 567 SETs. The syntax defined by profiling specifications includes what 568 claims and event payload values are used by SETs utilizing the 569 profile. 571 Defining the semantics of the SET contents for SETs utilizing the 572 profile is equally important. Possibly most important is defining 573 the procedures used to validate the SET issuer and to obtain the keys 574 controlled by the issuer that were used for cryptographic operations 575 used in the JWT representing the SET. For instance, some profiles 576 may define an algorithm for retrieving the SET issuer's keys that 577 uses the "iss" claim value as its input. Likewise, if the profile 578 allows (or requires) that the JWT be unsecured, the means by which 579 the integrity of the JWT is ensured MUST be specified. 581 Profiling Specifications MUST define how the event Subject is 582 identified in the SET, as well as how to differentiate between the 583 event Subject's Issuer and the SET Issuer, if applicable. It is NOT 584 RECOMMENDED for Profiling Specifications to use the "sub" claim in 585 cases in which the Subject is not globally unique and has a different 586 Issuer from the SET itself. 588 Among the syntax and semantics of SETs that Profiling Specifications 589 define is whether and how multiple "events" values are used for SETs 590 conforming to those profiles. Many valid choices are possible. For 591 instance, some profiles might allow multiple event identifiers to be 592 present and specify that any that are not understood by recipients be 593 ignored, thus enabling extensibility. Other profiles might allow 594 multiple event identifiers to be present but require that all be 595 understood if the SET is to be accepted. Some profiles might require 596 that only a single value be present. All such choices are within the 597 scope of Profiling Specifications to define. 599 Profiling Specifications MUST clearly specify the steps that a 600 recipient of a SET utilizing that profile MUST perform to validate 601 that the SET is both syntactically and semantically valid. 603 4. Security Considerations 605 4.1. Confidentiality and Integrity 607 SETs may contain sensitive information. Therefore, methods for 608 distribution of events SHOULD require the use of a transport-layer 609 security mechanism when distributing events. Parties MUST support 610 TLS 1.2 [RFC5246] and MAY support additional transport-layer 611 mechanisms meeting its security requirements. When using TLS, the 612 client MUST perform a TLS/SSL server certificate check, per 613 [RFC6125]. Implementation security considerations for TLS can be 614 found in "Recommendations for Secure Use of TLS and DTLS" [RFC7525]. 616 Security Events distributed through third parties or that carry 617 personally identifiable information SHOULD be encrypted using JWE 618 [RFC7516] or secured for confidentiality by other means. 620 Unless integrity of the JWT is ensured by other means, it MUST be 621 signed using JWS [RFC7515] so that the SET can be authenticated and 622 validated by the Event Recipient. 624 4.2. Delivery 626 This specification does not define a delivery mechanism for SETs. In 627 addition to confidentiality and integrity (discussed above), 628 implementers and Profiling Specifications MUST consider the 629 consequences of delivery mechanisms that are not secure and/or not 630 assured. For example, while a SET may be end-to-end secured using 631 JWE encrypted SETs, without TLS, there is no assurance that the 632 correct endpoint received the SET and that it could be successfully 633 processed. 635 4.3. Sequencing 637 This specification defines no means of ordering multiple SETs in a 638 sequence. Depending on the type and nature of the events represented 639 by SETs, order may or may not matter. For example, in provisioning, 640 event order is critical -- an object cannot be modified before it is 641 created. In other SET types, such as a token revocation, the order 642 of SETs for revoked tokens does not matter. If, however, the event 643 conveys a logged in or logged out status for a user subject, then 644 order becomes important. 646 Profiling Specifications and implementers SHOULD take caution when 647 using timestamps such as "iat" to define order. Distributed systems 648 will have some amount of clock skew. Thus, time by itself will not 649 guarantee order. 651 Specifications profiling SET SHOULD define a mechanism for detecting 652 order or sequence of events when the order matters. For example, the 653 "txn" claim could contain an ordered value (e.g., a counter) that the 654 issuer includes. 656 4.4. Timing Issues 658 When SETs are delivered asynchronously and/or out-of-band with 659 respect to the original action that incurred the security event, it 660 is important to consider that a SET might be delivered to an Event 661 Recipient in advance of or behind the process that caused the event. 662 For example, a user having been required to log out and then log back 663 in again, may cause a logout SET to be issued that may arrive at the 664 same time as the user agent accesses a web site having just logged 665 in. If timing is not handled properly, the effect would be to 666 erroneously treat the new user session as logged out. Profiling 667 Specifications SHOULD be careful to anticipate timing and subject 668 selection information. For example, it might be more appropriate to 669 cancel a "session" rather than a "user". Alternatively, the 670 specification could use timestamps that allow new sessions to be 671 started immediately after a stated logout event time. 673 4.5. Distinguishing SETs from ID Tokens 675 Because [RFC7519] states that "all claims that are not understood by 676 implementations MUST be ignored", there is a consideration that a SET 677 might be confused with ID Token [OpenID.Core] if a SET is mistakenly 678 or intentionally used in a context requiring an ID Token. If a SET 679 could otherwise be interpreted as a valid ID Token (because it 680 includes the required claims for an ID Token and valid issuer and 681 audience claim values for an ID Token) then that SET profile MUST 682 require that the "exp" claim not be present in the SET. Because 683 "exp" is a required claim in ID Tokens, valid ID Token 684 implementations will reject such a SET if presented as if it were an 685 ID Token. 687 Excluding "exp" from SETs that could otherwise be confused with ID 688 Tokens is actually defense in depth. In any OpenID Connect contexts 689 in which an attacker could attempt to substitute a SET for an ID 690 Token, the SET would actually already be rejected as an ID Token 691 because it would not contain the correct "nonce" claim value for the 692 ID Token to be accepted in contexts for which substitution is 693 possible. 695 Note that the use of explicit typing, as described in Section 2.3, 696 will not achieve disambiguation between ID Tokens and SETs, as the ID 697 Token validation rules do not use the "typ" header parameter value. 699 4.6. Distinguishing SETs from Access Tokens 701 OAuth 2.0 [RFC6749] defines access tokens as being opaque. 702 Nonetheless, some implementations implement access tokens as JWTs. 703 Because the structure of these JWTs is implementation-specific, 704 ensuring that a SET cannot be confused with such an access token is 705 therefore likewise, in general, implementation specific. 706 Nonetheless, it is recommended that SET profiles employ the following 707 strategies to prevent possible substitutions of SETs for access 708 tokens in contexts in which that might be possible: 710 o Prohibit use of the "exp" claim, as is done to prevent ID Token 711 confusion. 713 o Where possible, use a separate "aud" claim value to distinguish 714 between the Event Recipient and the protected resource that is the 715 audience of an access token. 717 o Modify access token validation systems to check for the presence 718 of the "events" claim as a means to detect security event tokens. 719 This is particularly useful if the same endpoint may receive both 720 types of tokens. 722 o Employ explicit typing, as described in Section 2.3, and modify 723 access token validation systems to use the "typ" header parameter 724 value. 726 4.7. Distinguishing SETs from other kinds of JWTs 728 JWTs are now being used in application areas beyond the identity 729 applications in which they first appeared. For instance, the Session 730 Initiation Protocol (SIP) Via Header Field [RFC8055] and Personal 731 Assertion Token (PASSporT) [I-D.ietf-stir-passport] specifications 732 both define JWT profiles that use mostly or completely different sets 733 of claims than are used by ID Tokens. If it would otherwise be 734 possible for an attacker to substitute a SET for one of these (or 735 other) kinds of JWTs, then the SET profile must be defined in such a 736 way that any substituted SET will result in its rejection when 737 validated as the intended kind of JWT. 739 The most direct way to prevent confusion is to employ explicit 740 typing, as described in Section 2.3, and modify applicable token 741 validation systems to use the "typ" header parameter value. This 742 approach can be employed for new systems but may not be applicable to 743 existing systems. 745 Another way to ensure that a SET is not confused with another kind of 746 JWT is to have the JWT validation logic reject JWTs containing an 747 "events" claim unless the JWT is intended to be a SET. This approach 748 can be employed for new systems but may not be applicable to existing 749 systems. 751 For many use cases, the simplest way to prevent substitution is 752 requiring that the SET not include claims that are required for the 753 kind of JWT that might be the target of an attack. For example, for 754 [RFC8055], the "sip_callid" claim could be omitted and for 755 [I-D.ietf-stir-passport], the "orig" claim could be omitted. 757 In many contexts, simple measures such as these will accomplish the 758 task, should confusion otherwise even be possible. Note that this 759 topic is being explored in a more general fashion in JSON Web Token 760 Best Current Practices [I-D.ietf-oauth-jwt-bcp]. The proposed best 761 practices in that draft may also be applicable for particular SET 762 profiles and use cases. 764 5. Privacy Considerations 766 If a SET needs to be retained for audit purposes, the signature can 767 be used to provide verification of its authenticity. 769 Event Issuers SHOULD attempt to specialize SETs so that their content 770 is targeted to the specific business and protocol needs of the 771 intended Event Recipients. 773 When sharing personally identifiable information or information that 774 is otherwise considered confidential to affected users, Event Issuers 775 and Recipients MUST have the appropriate legal agreements and user 776 consent and/or terms of service in place. 778 The propagation of subject identifiers can be perceived as personally 779 identifiable information. Where possible, Event Issuers and 780 Recipients SHOULD devise approaches that prevent propagation -- for 781 example, the passing of a hash value that requires the Event 782 Recipient to know the subject. 784 In some cases, it may be possible for an Event Recipient to correlate 785 different events and thereby gain information about a subject that 786 the Event Issuer did not intend to share. For example, an Event 787 Recipient might be able to use "iat" values or highly precise "toe" 788 values to determine that two otherwise un-relatable events actually 789 relate to the same real-world event. The union of information from 790 both events could allow an Event Recipient to de-anonymize data or 791 recognize that unrelated identifiers relate to the same individual. 792 Event Issuers SHOULD take steps to minimize the chance of event 793 correlation, when such correlation would constitute a privacy 794 violation. For instance, they could use approximate values for the 795 "toe" claim or arbitrarily delay SET issuance, where such delay can 796 be tolerated. 798 6. IANA Considerations 800 6.1. JSON Web Token Claims Registration 802 This specification registers the "events", "toe", and "txn" claims in 803 the IANA "JSON Web Token Claims" registry [IANA.JWT.Claims] 804 established by [RFC7519]. 806 6.1.1. Registry Contents 808 o Claim Name: "events" 809 o Claim Description: Security Event URI 810 o Change Controller: IESG 811 o Specification Document(s): Section 2.2 of [[ this specification ]] 813 o Claim Name: "toe" 814 o Claim Description: Time of Event 815 o Change Controller: IESG 816 o Specification Document(s): Section 2.2 of [[ this specification ]] 818 o Claim Name: "txn" 819 o Claim Description: Transaction Identifier 820 o Change Controller: IESG 821 o Specification Document(s): Section 2.2 of [[ this specification ]] 823 6.2. Media Type Registration 825 6.2.1. Registry Contents 827 This section registers the "application/secevent+jwt" media type 828 [RFC2046] in the "Media Types" registry [IANA.MediaTypes] in the 829 manner described in [RFC6838], which can be used to indicate that the 830 content is a SET. 832 o Type name: application 833 o Subtype name: secevent+jwt 834 o Required parameters: n/a 835 o Optional parameters: n/a 836 o Encoding considerations: 8bit; A SET is a JWT; JWT values are 837 encoded as a series of base64url-encoded values (some of which may 838 be the empty string) separated by period ('.') characters. 839 o Security considerations: See the Security Considerations section 840 of [[ this specification ]] 841 o Interoperability considerations: n/a 842 o Published specification: Section 2.3 of [[ this specification ]] 843 o Applications that use this media type: TBD 844 o Fragment identifier considerations: n/a 845 o Additional information: 847 Magic number(s): n/a 848 File extension(s): n/a 849 Macintosh file type code(s): n/a 851 o Person & email address to contact for further information: 852 Michael B. Jones, mbj@microsoft.com 853 o Intended usage: COMMON 854 o Restrictions on usage: none 855 o Author: Michael B. Jones, mbj@microsoft.com 856 o Change controller: IESG 857 o Provisional registration? No 859 7. References 861 7.1. Normative References 863 [IANA.JWT.Claims] 864 IANA, "JSON Web Token Claims", 865 . 867 [IANA.MediaTypes] 868 IANA, "Media Types", 869 . 871 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 872 Requirement Levels", BCP 14, RFC 2119, 873 DOI 10.17487/RFC2119, March 1997, 874 . 876 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 877 Resource Identifier (URI): Generic Syntax", STD 66, 878 RFC 3986, DOI 10.17487/RFC3986, January 2005, 879 . 881 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 882 (TLS) Protocol Version 1.2", RFC 5246, 883 DOI 10.17487/RFC5246, August 2008, 884 . 886 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 887 Verification of Domain-Based Application Service Identity 888 within Internet Public Key Infrastructure Using X.509 889 (PKIX) Certificates in the Context of Transport Layer 890 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 891 2011, . 893 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 894 RFC 6749, DOI 10.17487/RFC6749, October 2012, 895 . 897 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 898 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 899 . 901 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 902 "Recommendations for Secure Use of Transport Layer 903 Security (TLS) and Datagram Transport Layer Security 904 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 905 2015, . 907 [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", 908 RFC 7617, DOI 10.17487/RFC7617, September 2015, 909 . 911 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 912 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 913 May 2017, . 915 7.2. Informative References 917 [I-D.ietf-oauth-jwt-bcp] 918 Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best 919 Current Practices", draft-ietf-oauth-jwt-bcp-00 (work in 920 progress), July 2017. 922 [I-D.ietf-stir-passport] 923 Wendt, C. and J. Peterson, "Personal Assertion Token 924 (PASSporT)", draft-ietf-stir-passport-11 (work in 925 progress), February 2017. 927 [OpenID.Core] 928 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 929 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 930 . 932 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 933 Extensions (MIME) Part Two: Media Types", RFC 2046, 934 DOI 10.17487/RFC2046, November 1996, 935 . 937 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 938 Specifications and Registration Procedures", BCP 13, 939 RFC 6838, DOI 10.17487/RFC6838, January 2013, 940 . 942 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 943 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 944 August 2013, . 946 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 947 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 948 2015, . 950 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 951 RFC 7516, DOI 10.17487/RFC7516, May 2015, 952 . 954 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 955 DOI 10.17487/RFC7517, May 2015, 956 . 958 [RFC7644] Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E., 959 and C. Mortimore, "System for Cross-domain Identity 960 Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, 961 September 2015, . 963 [RFC8055] Holmberg, C. and Y. Jiang, "Session Initiation Protocol 964 (SIP) Via Header Field Parameter to Indicate Received 965 Realm", RFC 8055, DOI 10.17487/RFC8055, January 2017, 966 . 968 [RISC] OpenID Foundation, "OpenID Risk and Incident Sharing and 969 Coordination (RISC) Working Group", 970 . 972 [saml-core-2.0] 973 Internet2, "Assertions and Protocols for the OASIS 974 Security Assertion Markup Language (SAML) V2.0", March 975 2005. 977 Appendix A. Acknowledgments 979 The editors would like to thank the members of the IETF SCIM working 980 group, which began discussions of provisioning events starting with 981 draft-hunt-scim-notify-00 in 2015. 983 The editors would like to thank the participants in the IETF id-event 984 mailing list, the Security Events working group, and related working 985 groups for their contributions to this specification. 987 Appendix B. Change Log 989 [[ to be removed by the RFC Editor before publication as an RFC ]] 991 From the original draft-hunt-idevent-token: 993 Draft 01 - PH - Renamed eventUris to events 995 Draft 00 - PH - First Draft 997 Draft 01 - PH - Fixed some alignment issues with JWT. Remove event 998 type attribute. 1000 Draft 02 - PH - Renamed to Security Events, removed questions, 1001 clarified examples and intro text, and added security and privacy 1002 section. 1004 Draft 03 - PH 1006 General edit corrections from Sarah Squire 1008 Changed "event" term to "SET" 1010 Corrected author organization for William Denniss to Google 1011 Changed definition of SET to be 2 parts, an envelope and 1 or more 1012 payloads. 1014 Clarified that the intent is to express a single event with 1015 optional extensions only. 1017 - mbj - Registered "events" claim, and proof-reading corrections. 1019 Draft 04 - PH - 1021 o Re-added the "sub" claim with clarifications that any SET type may 1022 use it. 1024 o Added additional clarification on the use of envelope vs. payload 1025 attributes 1027 o Added security consideration for event timing. 1029 o Switched use of "attribute" to "claim" for consistency. 1031 o Revised examples to put "sub" claim back in the top level. 1033 o Added clarification that SETs typically do not use "exp". 1035 o Added security consideration for distinguishing Access Tokens and 1036 SETs. 1038 Draft 05 - PH - Fixed find/replace error that resulted in claim being 1039 spelled claimc 1041 Draft 06 - PH - 1043 o Corrected typos 1045 o New txn claim 1047 o New security considerations Sequencing and Timing Issues 1049 Draft 07 - 1051 o PH - Moved payload objects to be values of event URI attributes, 1052 per discussion. 1054 o mbj - Applied terminology consistency and grammar cleanups. 1056 Draft 08 - PH - 1058 o Added clarification to status of examples 1059 o Changed from primary vs. extension to state that multiple events 1060 may be expressed, some of which may or may not be considered 1061 extensions of others (which is for the subscriber or profiling 1062 specifications to determine). 1064 o Other editorial changes suggested by Yaron 1065 From draft-ietf-secevent-token: 1067 Draft 00 - PH - First WG Draft based on draft-hunt-idevent-token 1069 Draft 01 - PH - Changes as follows: 1071 o Changed terminology away from pub-sub to transmitter/receiver 1072 based on WG feedback 1074 o Cleaned up/removed some text about extensions (now only used as 1075 example) 1077 o Clarify purpose of spec vs. future profiling specs that define 1078 actual events 1080 Draft 02 - Changes are as follows: 1082 o mbj - Added the Requirements for SET Profiles section. 1084 o mbj - Expanded the Security Considerations section to describe how 1085 to prevent confusion of SETs with ID Tokens, access tokens, and 1086 other kinds of JWTs. 1088 o mbj - Registered the "application/secevent+jwt" media type and 1089 defined how to use it for explicit typing of SETs. 1091 o mbj - Clarified the misleading statement that used to say that a 1092 SET conveys a single security event. 1094 o mbj - Added a note explicitly acknowledging that some SET profiles 1095 may choose to convey event subject information in the event 1096 payload. 1098 o PH - Corrected encoded claim example on page 10. 1100 o mbj - Applied grammar corrections. 1102 Draft 03 - Changes are as follows: 1104 o pjh - Corrected old "subscriber" to "Event Receiver". Added 1105 clarification in definition that Event Receiver is the same as JWT 1106 recipient. 1108 o pjh - Added definition for "toe" (and IANA registration). 1110 o pjh - Removed "nbf" claim. 1112 o pjh - Figure 3, moved "sub" to the events payload next to "iss". 1114 o pjh - Clarified the use of "nonce" in contexts where substitution 1115 is possible. 1117 o mbj - Addressed WGLC comments by Nat Sakimura. 1119 o mbj - Addressed WGLC comments by Annabelle Backman. 1121 o mbj - Addressed WGLC comments by Marius Scurtescu. 1123 Draft 04 - mbj - Changes were as follows: 1125 o Clarified that all "events" values must represent aspects of the 1126 same state change that occurred to the subject -- not an 1127 aggregation of unrelated events about the subject. 1129 o Removed ambiguities about the roles of multiple "events" values 1130 and the responsibilities of profiling specifications for defining 1131 how and when they are used. 1133 o Corrected places where the term JWT was used when what was 1134 actually being discussed was the JWT Claims Set. 1136 o Addressed terminology inconsistencies. In particular, 1137 standardized on using the term "issuer" to align with JWT 1138 terminology and the "iss" claim. Previously the term 1139 "transmitter" was sometimes used and "issuer" was sometimes used. 1140 Likewise, standardized on using the term "recipient" instead of 1141 "receiver" for the same reasons. 1143 o Added a RISC event example, courtesy of Marius Scurtescu. 1145 o Applied wording clarifications suggested by Annabelle Backman and 1146 Yaron Sheffer. 1148 o Applied numerous grammar, syntax, and formatting corrections. 1150 Draft 05 - mbj - Changes were as follows: 1152 o Simplified the definitions of the "iat" and "toe" claims in ways 1153 suggested by Annabelle Backman. 1155 o Added privacy considerations text suggested by Annabelle Backman. 1157 o Updated the RISC event example, courtesy of Marius Scurtescu. 1159 o Reordered the claim definitions to place the required claims 1160 first. 1162 o Changed to using the RFC 8174 boilerplate instead of the RFC 2119 1163 boilerplate. 1165 Authors' Addresses 1167 Phil Hunt (editor) 1168 Oracle Corporation 1170 Email: phil.hunt@yahoo.com 1172 Michael B. Jones 1173 Microsoft 1175 Email: mbj@microsoft.com 1176 URI: http://self-issued.info/ 1178 William Denniss 1179 Google 1181 Email: wdenniss@google.com 1183 Morteza Ansari 1184 Cisco 1186 Email: morteza.ansari@cisco.com