idnits 2.17.1 draft-ietf-secevent-token-00.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 seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document date (January 23, 2017) is 2643 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: 'RFC7517' is defined on line 724, 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) Summary: 3 errors (**), 0 flaws (~~), 3 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 W. Denniss 5 Expires: July 27, 2017 Google 6 M. Ansari 7 Cisco 8 M. Jones 9 Microsoft 10 January 23, 2017 12 Security Event Token (SET) 13 draft-ietf-secevent-token-00 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) and may be 20 optionally signed and/or encrypted. A SET describes a statement of 21 fact that may be shared by an event publisher with event subscribers. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on July 27, 2017. 40 Copyright Notice 42 Copyright (c) 2017 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 2 58 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 59 1.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 60 2. The Security Event Token (SET) . . . . . . . . . . . . . . . 5 61 2.1. Core SET Claims . . . . . . . . . . . . . . . . . . . . . 8 62 2.2. Security Event Token Construction . . . . . . . . . . . . 10 63 3. Security Considerations . . . . . . . . . . . . . . . . . . . 12 64 3.1. Confidentiality and Integrity . . . . . . . . . . . . . . 12 65 3.2. Delivery . . . . . . . . . . . . . . . . . . . . . . . . 13 66 3.3. Sequencing . . . . . . . . . . . . . . . . . . . . . . . 13 67 3.4. Timing Issues . . . . . . . . . . . . . . . . . . . . . . 13 68 3.5. Distinguishing SETs from Access Tokens . . . . . . . . . 14 69 4. Privacy Considerations . . . . . . . . . . . . . . . . . . . 14 70 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 71 5.1. JSON Web Token Claims Registration . . . . . . . . . . . 15 72 5.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 15 73 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 74 6.1. Normative References . . . . . . . . . . . . . . . . . . 15 75 6.2. Informative References . . . . . . . . . . . . . . . . . 16 76 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 17 77 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 17 78 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 80 1. Introduction and Overview 82 This specification defines an extensible Security Event Token (SET) 83 format which may be exchanged using protocols such as HTTP. The 84 specification builds on the JSON Web Token (JWT) format [RFC7519] in 85 order to provide a self-contained token that can be optionally signed 86 using JSON Web Signature (JWS) [RFC7515] and/or encrypted using JSON 87 Web Encryption (JWE) [RFC7516]. 89 For the purpose of this specification, an event is a statement of 90 fact by a publisher (also known as the event issuer) that the state 91 of a security subject (e.g., a web resource, token, IP address) it 92 controls or is aware of, has changed in some way (explicitly or 93 implicitly). A security subject may be permanent (e.g., a user 94 account) or temporary (e.g., an HTTP session) in nature. A state 95 change may include direct changes of entity state, implicit changes 96 to state or other higher-level security statements such as: 98 o The creation, modification, removal of a resource. 100 o The resetting or suspension of an account. 102 o The revocation of a security token prior to its expiry. 104 o The logout of a user session. Or, 106 o A cumulative conclusion such as to indicate that a user has taken 107 over an email identifier that may have been used in the past by 108 another user. 110 Based on some externally agreed criteria for an event feed, the 111 publisher distributes events to the appropriate subscribers of a 112 feed. While an event may be delivered via synchronous means (e.g., 113 HTTP POST), the distribution of the event often happens 114 asynchronously to the change of state which generated the security 115 event. As an example, an OAuth2 Authorization Server [RFC6749], 116 having received a token revocation request [RFC7009], may issue a 117 token revocation event to downstream web resource providers. Having 118 been informed of a token revocation, the OAuth2 web resource service 119 provider may add the token identifier to its local revocation list 120 assuming the token has not already expired. 122 A subscriber having received an event, validates and interprets the 123 event and takes its own independent action, if any. For example, 124 having been informed of a personal identifier now being associated 125 with a different security subject (i.e., is being used by someone 126 else), the subscriber may choose to ensure that the new user is not 127 granted access to resources associated with the previous user. Or it 128 may not have any relationship with the subject, and no action is 129 taken. 131 While subscribers will often take actions upon receiving one or more 132 events, events MUST NOT be assumed to be commands or requests. To do 133 so requires complex bi-directional signals and error recovery 134 mechanisms that fall outside the scope of this specification. The 135 intent of this specification is to define a way of exchanging 136 statements of fact that subscribers may interpret for their own 137 purposes. Since events are typically historical statements by a 138 publisher and are not commands, idempotency or lack thereof, does not 139 apply. 141 Unless otherwise specified, this specification uses example events 142 intended to serve as non-normative examples showing how an event may 143 be constructed. It is expected that other "profiling" specifications 144 will use this specification to define normative events within some 145 specified context or protocol. 147 This specification is scoped to security and identity related events. 148 While security event tokens may be used for other purposes, the 149 specification only considers security and privacy concerns relevant 150 to identity and personal information. 152 1.1. Notational Conventions 154 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 155 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 156 document are to be interpreted as described in [RFC2119]. These 157 keywords are capitalized when used to unambiguously specify 158 requirements of the protocol or application features and behavior 159 that affect the inter-operability and security of implementations. 160 When these words are not capitalized, they are meant in their 161 natural-language sense. 163 For purposes of readability, examples are not URL encoded. 164 Implementers MUST percent encode URLs as described in Section 2.1 of 165 [RFC3986]. 167 Throughout this document, all figures MAY contain spaces and extra 168 line-wrapping for readability and space limitations. Similarly, some 169 URIs contained within examples have been shortened for space and 170 readability reasons. 172 1.2. Definitions 174 The following definitions are used with SETs: 176 Feed Publisher 177 The Feed Publisher creates SETs to be distributed to registered 178 subscribers. In JWT terminology, the Feed Publisher is also known 179 as the issuer ("iss"). 181 Security Event Token (SET) 182 An SET is a JWT that is to be distributed to one or more 183 registered subscribers. A SET MAY be signed or encrypted using 184 JWS and/or JWE for authentication and confidentiality reasons. 186 Feed 187 A Feed is a logical grouping of SETs or a context under which SETs 188 may be issued. A Subscriber registers with the Feed Publisher to 189 subscribe to SETs associated with a Feed. How a Feed is defined 190 or the method for subscription is out-of-scope of this 191 specification. 193 Subscriber 194 A Subscriber registers to receive SETs from a Feed Publisher using 195 a protocol such as HTTP. The method of registration and delivery 196 is out-of-scope of this specification. 198 Security Subject 199 A Security Subject is the entity to which a SET refers. A 200 Security Subject may be a principle (e.g., Section 4.1.2 201 [RFC7519]), a web resource, or other thing such as an IP address 202 that a SET might reference. 204 2. The Security Event Token (SET) 206 A SET conveys a statement (in the form of a JWT [RFC7519]) about a 207 single security event in relation to a Security Subject that may be 208 of interest to a Subscriber or set of Subscribers receiving SETs from 209 a Feed Publisher. 211 The schema and structure of a SET follows the JWT [RFC7519] 212 specification. A SET has the following structure: 214 o An outer JSON structure that acts as the SET envelope. The 215 envelope contains a set of name/value pairs called the JWT Claims 216 Set, typically common to every SET or common to a number of 217 different Security Events within a single profiling specification 218 or a related series of specifications. Claims in the envelope 219 SHOULD be registered in the JWT Token Claims Registry Section 10.1 220 [RFC7519] or be Public Claims or Private Claims as also defined in 221 [RFC7519]. 223 o Envelope claims that are profiled and defined in this 224 specification are used to validate a SET and declare the event 225 data included in the SET. The claim "events" identifies the 226 security event types being expressed related to the Security 227 Subject and MAY also include event-specific data. 229 o Each JSON member of the "events" object is a name/value pair. The 230 JSON attribute name is a URI String value that expresses an event 231 type. The corresponding value is a JSON object known as the event 232 "payload". The payload JSON object contains claims typically 233 unique to the event's URI type value and are not registered as JWT 234 claims. These claims are defined by their associated event 235 specification. An event with no payload claims SHALL be 236 represented as the empty JSON object ("{}"). In many cases, one 237 event URI expresses the primary event URI, while other events 238 might be considered extensions that MAY be used to do things such 239 as: 241 * A categorization event type to provide classification 242 information (e.g., threat type or level). 244 * An enhancement of an existing specifications the arise over 245 time. 247 * An extensions needed to link a potential series of events. 249 * Localized specific purpose extensions needed between a 250 particular publisher and subscriber. 252 The following is a non-normative example showing the JWT Claims Set 253 for a hypothetical SCIM password reset SET. This example shows an 254 extension ("https://example.com/scim/event/passwordResetExt") that is 255 used to convey additional information -- in this case, the current 256 count of reset attempts: 258 { 259 "jti": "3d0c3cf797584bd193bd0fb1bd4e7d30", 260 "iat": 1458496025, 261 "iss": "https://scim.example.com", 262 "aud": [ 263 "https://jhub.example.com/Feeds/98d52461fa5bbc879593b7754", 264 "https://jhub.example.com/Feeds/5d7604516b1d08641d7676ee7" 265 ], 266 "sub": "https://scim.example.com/Users/44f6142df96bd6ab61e7521d9", 267 "events": { 268 "urn:ietf:params:scim:event:passwordReset": 269 { "id":"44f6142df96bd6ab61e7521d9"}, 270 "https://example.com/scim/event/passwordResetExt": 271 { "resetAttempts":5} 272 } 273 } 275 Figure 1: Example SCIM Password Reset Event 277 The event in the figure above expresses hypothetical password reset 278 event for SCIM [RFC7644]. The JWT consists of: 280 o An "events" claim specifying the hypothetical SCIM URN 281 ("urn:ietf:params:scim:event:passwordReset") for a password reset, 282 and a custom extension, "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 An "iss" claim, denoting the event publisher. 288 o The "sub" claim specifies the SCIM resource URI that was affected. 290 o The "aud" claim specifies the intended audiences for the event. 291 In practical terms, an audience MAY be the URI for an event feed 292 that a client has subscribed to. 294 In this example, the SCIM event indicates that a password has been 295 updated and the current password reset count is 5. Notice that the 296 value for "resetAttempts" is actually part of its own JSON object 297 associated with its own event URI attribute. 299 Here is another example JWT Claims Set for a security event token, 300 this one for a Logout Token: 302 { 303 "iss": "https://server.example.com", 304 "sub": "248289761001", 305 "aud": "s6BhdRkqt3", 306 "iat": 1471566154, 307 "jti": "bWJq", 308 "sid": "08a5019c-17e1-4977-8f42-65a12843ea02", 309 "events": { 310 "http://schemas.openid.net/event/backchannel-logout": {} 311 } 312 } 314 Figure 2: Example OpenID Back-Channel Logout Event 316 Note that the above SET has an empty JSON object and uses the JWT 317 registered claims "sub" and "sid" to identify the subject that was 318 logged-out. 320 In the following example JWT Claims Set, a fictional medical service 321 collects consent for medical actions and notifies other parties. The 322 individual for whom consent is identified was originally 323 authenticated via OpenID Connect. In this case, the issuer of the 324 security event is an application rather than the OpenID provider: 326 { 327 "jti": "fb4e75b5411e4e19b6c0fe87950f7749", 329 "sub": "248289761001", 330 "iat": 1458496025, 331 "iss": "https://my.examplemed.com", 332 "aud": [ 333 "https://rp.example.com" 334 ], 335 "events": { 336 "https://openid.net/heart/specs/consent.html":{ 337 "iss":"https://connect.example.com", 338 "consentUri":[ 339 "https://terms.examplemed.com/labdisclosure.html#Agree" 340 ] 341 } 342 } 343 } 345 Figure 3: Example Consent Event 347 In the above example, the attribute "iss" contained within the 348 payload for the event "https://openid.net/heart/specs/consent.html", 349 refers to the issuer of the Security Subject ("sub") rather than the 350 event issuer "https://my.examplemed.com". They are distinct from the 351 top level value of "iss" which always refers to the issuer of the 352 event - a medical consent service that is a relying party to the 353 OpenID Provider. 355 2.1. Core SET Claims 357 The following are claims that are based on [RFC7519] claim 358 definitions and are profiled for use in an event token: 360 jti 361 As defined by Section 4.1.7 [RFC7519] contains a unique identifier 362 for an event. The identifier SHOULD be unique within a particular 363 event feed and MAY be used by clients to track whether a 364 particular event has already been received. This claim is 365 REQUIRED. 367 iss 368 A single valued String containing the URI of the service provider 369 publishing the SET (the issuer). This claim is REQUIRED. Note 370 that when a SET is expressing an event about a Security Subject 371 for which the SET issuer is not the issuer of the Security 372 Subject, the conflict SHALL be resolved by including the Security 373 Subject "iss" value within the event "payload" (see "events" 374 claim). 376 aud 377 As defined in Section 4.1.3 [RFC7519], an array containing the 378 StringOrURI values representing the audience of the event. Values 379 are typically URLs of the feeds the event is associated with. 380 This claim is RECOMMENDED. 382 iat 383 As defined by Section 4.1.6 [RFC7519], a value containing a 384 NumericDate, which represents when the event was issued. Unless 385 otherwise specified, the value SHOULD be interpreted by the 386 subscriber as equivalent to the actual time of the event. This 387 claim is REQUIRED. 389 nbf 390 Defined by Section 4.1.5 [RFC7519], a number whose value is a 391 NumericDate. In the context of the SET token it SHALL be 392 interpreted to mean a date in which the event is believed to have 393 occurred (in the past) or will occur in the future. Note: there 394 MAY be some cases where "nbf" is still smaller than "iat" such as 395 when it took an extended time for a SET to be issued (for example 396 after some analysis). This claim is OPTIONAL. 398 sub As defined by Section 4.1.2 [RFC7519], a String or URI value 399 representing the principal or the subject of the SET. This is 400 usually the entity whose "state" was changed. For example, an IP 401 Address was added to a black list. A URI representing a user 402 resource that was modified. A token identifier for a revoked 403 token. If used, the profile specification SHOULD define the 404 content and format semantics for the value. This claim is 405 OPTIONAL, as the principal for any given profile may already be 406 identified without the inclusion of a subject claim. 408 exp As defined by [RFC7519], this claim is time on which the JWT 409 MUST NOT be accepted for processing. In the context of a SET 410 however, this notion does not apply since a SET reflects something 411 that has already been processed and is historical in nature. 412 While some specifications MAY have a need for this claim, its use 413 in general cases is NOT RECOMMENDED. 415 The following are new claims defined by this specification: 417 events 418 The semantics of this claim is to define a set of event statements 419 that each MAY add additional claims to fully describe a single 420 logical event that has occurred (e.g. a state change to a 421 subject). Multiple event statements of the same type SHALL NOT be 422 accepted. The "events" claim SHOULD NOT be used to express 423 multiple logical events. 425 The value of "events" is a JSON object whose members are a set of 426 JSON name/value pairs whose names are URIs representing the event 427 statements being expressed. Event URI values SHOULD be stable 428 values (e.g. a permanent URL for an event specification). For 429 each name present, the corresponding value SHALL be a JSON object. 430 The JSON object MAY be an empty object ("{}"), or it MAY be a JSON 431 object containing data as described by the profiling event 432 specification. 434 txn 435 An OPTIONAL String value that represents a unique transaction 436 identifier. In cases where multiple SETs are issued based on 437 different event URIs, the transaction identifier MAY be used to 438 correlate SETs to the same originating event or stateful change. 440 2.2. Security Event Token Construction 442 A SET is a JWT [RFC7519] that is constructed by building a JSON 443 structure that constitutes an event object and which is then used as 444 the body of a JWT. 446 While this specification uses JWT to convey a SET, implementers SHALL 447 NOT use SETs to convey authentication or authorization assertions. 449 The following is an example JWT Claims Set for a security event token 450 (which has been formatted for readability): 452 { 453 "jti": "4d3559ec67504aaba65d40b0363faad8", 454 "iat": 1458496404, 455 "iss": "https://scim.example.com", 456 "aud": [ 457 "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754", 458 "https://scim.example.com/Feeds/5d7604516b1d08641d7676ee7" 459 ], 461 "events": { 462 "urn:ietf:params:scim:event:create": { 463 "ref": 464 "https://scim.example.com/Users/44f6142df96bd6ab61e7521d9", 465 "attributes":["id", "name", "userName", "password", "emails"] 466 } 467 } 468 } 470 Figure 4: Example Event Claims 472 When transmitted, the above JSON body must be converted into a JWT as 473 per [RFC7519]. 475 The following is an example of a SCIM Event expressed as an unsecured 476 JWT. The JWT header of: 478 {"alg":"none"} 480 Base64url encoding of the octets of the UTF-8 representation of the 481 header yields: 483 eyJhbGciOiJub25lIn0 485 The example JSON Event Data is encoded as follows: 487 e3sgIAogICJqdGkiOiAiNGQzNTU5ZWM2NzUwNGFhYmE2NWQ0MGIwMzYzZmFhZDgiLAog 488 ICJpYXQiOiAxNDU4NDk2NDA0LAogICJpc3MiOiAiaHR0cHM6Ly9zY2ltLmV4YW1wbGUu 489 Y29tIiwgIAogICJhdWQiOiBbCiAgICJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vRmVl 490 ZHMvOThkNTI0NjFmYTViYmM4Nzk1OTNiNzc1NCIsCiAgICJodHRwczovL3NjaW0uZXhh 491 bXBsZS5jb20vRmVlZHMvNWQ3NjA0NTE2YjFkMDg2NDFkNzY3NmVlNyIKICBdLCAgCiAg 492 CiAgImV2ZW50cyI6IHsKICAgICJ1cm46aWV0ZjpwYXJhbXM6c2NpbTpldmVudDpjcmVh 493 dGUiOiB7CiAgICAgICJyZWYiOgogICAgICAgICJodHRwczovL3NjaW0uZXhhbXBsZS5j 494 b20vVXNlcnMvNDRmNjE0MmRmOTZiZDZhYjYxZTc1MjFkOSIsCiAgICAgICJhdHRyaWJ1 495 dGVzIjpbImlkIiwgIm5hbWUiLCAidXNlck5hbWUiLCAicGFzc3dvcmQiLCAiZW1haWxz 496 Il0KICAgIH0KICB9Cn0 497 The encoded JWS signature is the empty string. Concatenating the 498 parts yields: 500 eyJhbGciOiJub25lIn0 501 . 502 e3sgIAogICJqdGkiOiAiNGQzNTU5ZWM2NzUwNGFhYmE2NWQ0MGIwMzYzZmFhZDgiLAog 503 ICJpYXQiOiAxNDU4NDk2NDA0LAogICJpc3MiOiAiaHR0cHM6Ly9zY2ltLmV4YW1wbGUu 504 Y29tIiwgIAogICJhdWQiOiBbCiAgICJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vRmVl 505 ZHMvOThkNTI0NjFmYTViYmM4Nzk1OTNiNzc1NCIsCiAgICJodHRwczovL3NjaW0uZXhh 506 bXBsZS5jb20vRmVlZHMvNWQ3NjA0NTE2YjFkMDg2NDFkNzY3NmVlNyIKICBdLCAgCiAg 507 CiAgImV2ZW50cyI6IHsKICAgICJ1cm46aWV0ZjpwYXJhbXM6c2NpbTpldmVudDpjcmVh 508 dGUiOiB7CiAgICAgICJyZWYiOgogICAgICAgICJodHRwczovL3NjaW0uZXhhbXBsZS5j 509 b20vVXNlcnMvNDRmNjE0MmRmOTZiZDZhYjYxZTc1MjFkOSIsCiAgICAgICJhdHRyaWJ1 510 dGVzIjpbImlkIiwgIm5hbWUiLCAidXNlck5hbWUiLCAicGFzc3dvcmQiLCAiZW1haWxz 511 Il0KICAgIH0KICB9Cn0 512 . 514 Figure 5: Example Unsecured Security Event Token 516 For the purpose of a simpler example in Figure 5 an unencrypted token 517 was shown. When SETs are not signed or encrypted, the subscriber 518 MUST depend upon TLS and HTTP to authenticate the sender and the 519 security of the channel to authenticate the SET and its sender. 521 When validation (i.e. auditing), or additional transmission security 522 is required, JWS Signing and JWS Encryption MAY be used. To create 523 and or validate a signed or encrypted SET, follow the instructions in 524 section 7 of [RFC7519]. 526 3. Security Considerations 528 3.1. Confidentiality and Integrity 530 SETs may often contain sensitive information. Therefore, methods for 531 distribution of events SHOULD require the use of a transport-layer 532 security mechanism when distributing events. Parties MUST support 533 TLS 1.2 [RFC5246] and MAY support additional transport-layer 534 mechanisms meeting its security requirements. When using TLS, the 535 client MUST perform a TLS/SSL server certificate check, per 536 [RFC6125]. Implementation security considerations for TLS can be 537 found in "Recommendations for Secure Use of TLS and DTLS" [RFC7525]. 539 Security Events distributed through third-parties or that carry 540 personally identifiable information, SHOULD be encrypted using JWE 541 [RFC7516] or secured for confidentiality by other means. 543 Security Events distributed without authentication over the channel, 544 such as via TLS ([RFC5246] and [RFC6125]), and/or OAuth2 [RFC6749], 545 or Basic Authentication [RFC7617], MUST be signed using JWS [RFC7515] 546 so that individual events MAY be authenticated and validated by the 547 subscriber. 549 3.2. Delivery 551 This specification does not define a delivery mechanism by itself. 552 In addition to confidentiality and integrity (discussed above), 553 implementers and profile specifications MUST consider the 554 consequences of delivery mechanisms that are not secure and/or not 555 assured. For example, while a SET may be end-to-end secured using 556 JWE encrypted SETs, without TLS there is no assurance that the 557 correct endpoint received the SET and that it could be successfully 558 processed. 560 3.3. Sequencing 562 As defined in this specification, there is no defined way to order 563 multiple SETs in a sequence. Depending on the type and nature of SET 564 event, order may or may not matter. For example, in provisioning, 565 event order is critical -- an object could not be modified before it 566 was created. In other SET types, such as a token revocation, the 567 order of SETs for revoked tokens does not matter. If however, the 568 event was described as a log-in or logged-out status for a user 569 subject, then order becomes important. 571 Extension specifications and implementers SHOULD take caution when 572 using timestamps such as "iat" to define order. Distributed systems 573 will have some amount of clock-skew and thus time by itself will not 574 guarantee order. 576 Specifications profiling SET SHOULD define a mechanism for detecting 577 order or sequence of events. For example, the "txn" claim could 578 contain an ordered value (e.g., a counter) that the publisher 579 defines. 581 3.4. Timing Issues 583 When SETs are delivered asynchronously and/or out-of-band with 584 respect to the original action that incurred the security event, it 585 is important to consider that a SET might be delivered to a 586 Subscriber in advance or well behind the process that caused the 587 event. For example, a user having been required to logout and then 588 log back in again, may cause a logout SET to be issued that may 589 arrive at the same time as the user-agent accesses a web site having 590 just logged-in. If timing is not handled properly, the effect would 591 be to erroneously treat the new user session as logged out. 592 Profiling specifications SHOULD be careful to anticipate timing and 593 subject selection information. For example, it might be more 594 appropriate to cancel a "session" rather than a "user". 595 Alternatively, the specification could use timestamps that allows new 596 sessions to be started immediately after a stated logout event time. 598 3.5. Distinguishing SETs from Access Tokens 600 Because [RFC7519] states that "all claims that are not understood by 601 implementations MUST be ignored.", there is a consideration that a 602 SET token might be confused as an access or authorization token in 603 the case where a SET is mistakenly or intentionally intercepted and 604 presented as an access token. To avoid this, it is recommended that 605 implementers consider one or more of the following: 607 o Avoid use of the JWT claim "exp" within the envelope. 609 o Where possible, use a separate "aud" claim value to distinguish 610 between the SET subscriber and the audience of an access token. 611 For example, a Logout while intended for the same relying party 612 could use a different audience to distinguish between normal 613 access and logout notification. 615 o Modify access validation systems to check for the presence of the 616 "events" claim as a means to detect security event tokens. This 617 is particularly useful if the same endpoint may receive both types 618 of tokens. 620 o Consider avoiding use of the "sub" claim at the top level. 622 4. Privacy Considerations 624 If a SET needs to be retained for audit purposes, JWS MAY be used to 625 provide verification of its authenticity. 627 Event Publishers SHOULD attempt to specialize feeds so that the 628 content is targeted to the specific business and protocol needs of 629 subscribers. 631 When sharing personally identifiable information or information that 632 is otherwise considered confidential to affected users, the 633 publishers and subscribers MUST have the appropriate legal agreements 634 and user consent in place. 636 The propagation of subject identifiers can be perceived as personally 637 identifiable information. Where possible, publishers and subscribers 638 should devise approaches that prevent propagation -- for example, the 639 passing of a hash value that requires the subscriber to already know 640 the subject. 642 5. IANA Considerations 644 5.1. JSON Web Token Claims Registration 646 This specification registers the "events" and "txn" claims in the 647 IANA "JSON Web Token Claims" registry [IANA.JWT.Claims] established 648 by [RFC7519]. 650 5.1.1. Registry Contents 652 o Claim Name: "events" 653 o Claim Description: Security Event Object 654 o Change Controller: IESG 655 o Specification Document(s): Section 2 of [[ this specification ]] 657 o Claim Name: "txn" 658 o Claim Description: Transaction Identifier 659 o Change Controller: IESG 660 o Specification Document(s): Section 2 of [[ this specification ]] 662 6. References 664 6.1. Normative References 666 [IANA.JWT.Claims] 667 IANA, "JSON Web Token Claims", 668 . 670 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 671 Requirement Levels", BCP 14, RFC 2119, 672 DOI 10.17487/RFC2119, March 1997, 673 . 675 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 676 Resource Identifier (URI): Generic Syntax", STD 66, 677 RFC 3986, DOI 10.17487/RFC3986, January 2005, 678 . 680 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 681 (TLS) Protocol Version 1.2", RFC 5246, 682 DOI 10.17487/RFC5246, August 2008, 683 . 685 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 686 Verification of Domain-Based Application Service Identity 687 within Internet Public Key Infrastructure Using X.509 688 (PKIX) Certificates in the Context of Transport Layer 689 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 690 2011, . 692 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 693 RFC 6749, DOI 10.17487/RFC6749, October 2012, 694 . 696 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 697 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 698 . 700 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 701 "Recommendations for Secure Use of Transport Layer 702 Security (TLS) and Datagram Transport Layer Security 703 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 704 2015, . 706 [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", 707 RFC 7617, DOI 10.17487/RFC7617, September 2015, 708 . 710 6.2. Informative References 712 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 713 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 714 August 2013, . 716 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 717 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 718 2015, . 720 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 721 RFC 7516, DOI 10.17487/RFC7516, May 2015, 722 . 724 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 725 DOI 10.17487/RFC7517, May 2015, 726 . 728 [RFC7644] Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E., 729 and C. Mortimore, "System for Cross-domain Identity 730 Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, 731 September 2015, . 733 Appendix A. Acknowledgments 735 The editors would like to thank the participants in the IETF id-event 736 mailing list and related working groups for their support of this 737 specification. 739 Appendix B. Change Log 741 Draft 01 - PH - Renamed eventUris to events 743 Draft 00 - PH - First Draft 745 Draft 01 - PH - Fixed some alignment issues with JWT. Remove event 746 type attribute. 748 Draft 02 - PH - Renamed to Security Events, removed questions, 749 clarified examples and intro text, and added security and privacy 750 section. 752 Draft 03 - PH 754 General edit corrections from Sarah Squire 755 Changed "event" term to "SET" 756 Corrected author organization for William Denniss to Google 757 Changed definition of SET to be 2 parts, an envelope and 1 or more 758 payloads. 759 Clarified that the intent is to express a single event with 760 optional extensions only. 762 - mbj - Registered "events" claim, and proof-reading corrections. 764 Draft 04 - PH - 766 o Re-added the "sub" claim with clarifications that any SET type may 767 use it. 768 o Added additional clarification on the use of envelope vs. payload 769 attributes 770 o Added security consideration for event timing. 771 o Switched use of "attribute" to "claim" for consistency. 772 o Revised examples to put "sub" claim back in the top level. 773 o Added clarification that SETs typically do not use "exp". 774 o Added security consideration for distinguishing Access Tokens and 775 SETs. 777 Draft 05 - PH - Fixed find/replace error that resulted in claim being 778 spelled claimc 780 Draft 06 - PH - 781 o Corrected typos 782 o New txn claim 783 o New security considerations Sequencing and Timing Issues 785 Draft 07 - 787 o PH - Moved payload objects to be values of event URI attributes, 788 per discussion. 789 o mbj - Applied terminology consistency and grammar cleanups. 791 Draft 08 - PH - 793 o Added clarification to status of examples 794 o Changed from primary vs. extension to state that multiple events 795 may be expressed, some of which may or may not be considered 796 extensions of others (which is for the subscriber or profiling 797 specifications to determine). 798 o Other editorial changes suggested by Yaron 800 Authors' Addresses 802 Phil Hunt (editor) 803 Oracle Corporation 805 Email: phil.hunt@yahoo.com 807 William Denniss 808 Google 810 Email: wdenniss@google.com 812 Morteza Ansari 813 Cisco 815 Email: morteza.ansari@cisco.com 817 Michael B. Jones 818 Microsoft 820 Email: mbj@microsoft.com 821 URI: http://self-issued.info/