idnits 2.17.1 draft-hunt-idevent-token-07.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 (November 23, 2016) is 2711 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 728, 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: May 27, 2017 Google 6 M. Ansari 7 Cisco 8 M. Jones 9 Microsoft 10 November 23, 2016 12 Security Event Token (SET) 13 draft-hunt-idevent-token-07 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 May 27, 2017. 40 Copyright Notice 42 Copyright (c) 2016 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 . . . . . . . . . . . . . . . . . . . 13 64 3.1. Confidentiality and Integrity . . . . . . . . . . . . . . 13 65 3.2. Delivery . . . . . . . . . . . . . . . . . . . . . . . . 13 66 3.3. Sequencing . . . . . . . . . . . . . . . . . . . . . . . 13 67 3.4. Timing Issues . . . . . . . . . . . . . . . . . . . . . . 14 68 3.5. Distinguishing SETs from Access Tokens . . . . . . . . . 14 69 4. Privacy Considerations . . . . . . . . . . . . . . . . . . . 15 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 . . . . . . . . . . . . . . . . . . 16 75 6.2. Informative References . . . . . . . . . . . . . . . . . 17 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., a login 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 agreed upon criteria for an event feed, the publisher 111 distributes events to the appropriate subscribers. While an event 112 may be delivered via synchronous means (e.g., HTTP POST), the 113 distribution of the event often happens asynchronously to the change 114 of state which generated the security event. As an example, an 115 OAuth2 Authorization Server [RFC6749], having received a token 116 revocation request [RFC7009], may issue a token revocation event to 117 downstream web resource providers. Having been informed of a token 118 revocation, the OAuth2 web resource service provider may add the 119 token identifier to its local revocation list assuming the token has 120 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 as non-normative examples showing how an event may be used. 143 It is expected that other specifications will use this specification 144 to define normative events. 146 This specification is scoped to security and identity related events. 147 While security event tokens may be used for other purposes, the 148 specification only considers security and privacy concerns relevant 149 to identity and personal information. 151 1.1. Notational Conventions 153 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 154 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 155 document are to be interpreted as described in [RFC2119]. These 156 keywords are capitalized when used to unambiguously specify 157 requirements of the protocol or application features and behavior 158 that affect the inter-operability and security of implementations. 159 When these words are not capitalized, they are meant in their 160 natural-language sense. 162 For purposes of readability, examples are not URL encoded. 163 Implementers MUST percent encode URLs as described in Section 2.1 of 164 [RFC3986]. 166 Throughout this document, all figures MAY contain spaces and extra 167 line-wrapping for readability and space limitations. Similarly, some 168 URIs contained within examples have been shortened for space and 169 readability reasons. 171 1.2. Definitions 173 The following definitions are used with SETs: 175 Feed Publisher 176 The Feed Publisher creates SETs to be distributed to registered 177 subscribers. In JWT terminology, the Feed Publisher is also known 178 as the issuer ("iss"). 180 Security Event Token (SET) 181 An SET is a JWT that is to be distributed to one or more 182 registered subscribers. A SET MAY be signed or encrypted using 183 JWS and/or JWE for authentication and confidentiality reasons. 185 Feed 186 A Feed is a logical grouping of SETs or a context under which SETs 187 may be issued. A Subscriber registers with the Feed Publisher to 188 subscribe to SETs associated with a Feed. How a Feed is defined 189 or the method for subscription is out-of-scope of this 190 specification. 192 Subscriber 193 A Subscriber registers to receive SETs from a Feed Publisher using 194 a protocol such as HTTP. The method of registration and delivery 195 is out-of-scope of this specification. 197 Security Subject 198 A Security Subject is the entity to which a SET refers. A 199 Security Subject may be a principle (e.g., Section 4.1.2 200 [RFC7519]), a web resource, or other thing such as an IP address 201 that a SET might reference. 203 2. The Security Event Token (SET) 205 A SET conveys a statement (in the form of a JWT [RFC7519]) about a 206 single security event in relation to a Security Subject that may be 207 of interest to a Subscriber or set of Subscribers receiving SETs from 208 a Feed Publisher. 210 The schema and structure of a SET follows the JWT [RFC7519] 211 specification. A SET has the following structure: 213 o An outer JSON structure that acts as the SET envelope. The 214 envelope contains a set of name/value pairs called the JWT Claims 215 Set, typically common to every SET or common to a number of 216 different Security Events within a single profiling specification 217 or a related series of specifications. Claims in the envelope 218 SHOULD be registered in the JWT Token Claims Registry Section 10.1 219 [RFC7519] or be Public Claims or Private Claims as also defined in 220 [RFC7519]. 222 o Envelope claims that are profiled and defined in this 223 specification are used to validate the SET and determine the event 224 data included. The claim "events" identifies the type of security 225 event and MAY also include event-specific data. While a SET 226 contains a single event, it MAY have multiple extensions providing 227 additional data about the same event. The primary event is 228 typically the first value in the "events" object, while event 229 extensions are the 2nd, 3rd, etc. 231 o Each JSON member of the "events" object is a name/value pair, 232 whose value is a JSON object known as the event "payload". The 233 payload object contains claims typically unique to the event's URI 234 value and are not registered as JWT claims. These claims are 235 defined by their associated event specification. An event with no 236 payload claims SHALL be represented as the empty JSON object 237 ("{}"). Event extensions can be used for many purposes. Some 238 examples include but are not limited to: 240 * A categorization extension applied to multiple event types to 241 provide classification information (e.g., threat type or 242 level). 244 * Enhancement of an existing specifications the arise over time. 246 * Correlation extensions needed to link a potential series of 247 events. 249 * Localized contextual extensions needed between a publisher and 250 subscriber. 252 The following is a non-normative example showing the JWT Claims Set 253 for a hypothetical SCIM password reset SET. This example is also one 254 in which the issuer has provided an extension 255 ("https://example.com/scim/event/passwordResetExt") that is used to 256 convey additional information -- in this case, the current count of 257 reset attempts: 259 { 260 "jti": "3d0c3cf797584bd193bd0fb1bd4e7d30", 261 "iat": 1458496025, 262 "iss": "https://scim.example.com", 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 event in the figure above expresses hypothetical password reset 279 event for SCIM [RFC7644]. The JWT consists of: 281 o An "events" claim specifying the hypothetical SCIM URN 282 ("urn:ietf:params:scim:event:passwordReset") for a password reset, 283 and a custom extension, "https://example.com/scim/event/ 284 passwordResetExt", that is used to provide additional event 285 information such as the current count of resets. 287 o An "iss" claim, denoting the event publisher. 289 o The "sub" claim specifies the SCIM resource URI that was affected. 291 o The "aud" claim specifies the intended audiences for the event. 292 In practical terms, an audience MAY be the URI for an event feed 293 that a client has subscribed to. 295 Additional extensions to an event may be added by adding more values 296 to the "events" claims. For each event URI value specified, there is 297 a corresponding JSON object that contains the claims associated with 298 that event, if any. In this example, the SCIM event indicates that a 299 password has been updated and the current password reset count is 5. 300 Notice that the value for "resetAttempts" is actually part of its own 301 JSON object associated with the extension URI. 303 Here is another example JWT Claims Set for a security event token, 304 this one for a Logout Token: 306 { 307 "iss": "https://server.example.com", 308 "sub": "248289761001", 309 "aud": "s6BhdRkqt3", 310 "iat": 1471566154, 311 "jti": "bWJq", 312 "sid": "08a5019c-17e1-4977-8f42-65a12843ea02", 313 "events": { 314 "http://schemas.openid.net/event/backchannel-logout": {} 315 } 316 } 318 Figure 2: Example OpenID Back-Channel Logout Event 320 Note that the above SET has an empty JSON object and uses the JWT 321 registered claims "sub" and "sid" to identify the subject that was 322 logged-out. 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 "jti": "fb4e75b5411e4e19b6c0fe87950f7749", 333 "sub": "248289761001", 334 "iat": 1458496025, 335 "iss": "https://my.examplemed.com", 336 "aud": [ 337 "https://rp.example.com" 338 ], 339 "events": { 340 "https://openid.net/heart/consent.html":{ 341 "consentUri":[ 342 "https://terms.examplemed.com/labdisclosure.html#Agree" 343 ] 344 } 345 } 346 } 348 Figure 3: Example Consent Event 350 In the above example "iss" and "sub" contained within the claim 351 "https://openid.net/heart/consent", refer to the subject and issuer 352 of the original OpendID Provider. They are distinct from the top 353 level value of "iss" which always refers to the issuer of the event - 354 a medical consent service that is a relying party to the OpenID 355 Provider. 357 2.1. Core SET Claims 359 The following are claims that are based on [RFC7519] claim 360 definitions and are profiled for use in an event token: 362 jti 363 As defined by Section 4.1.7 [RFC7519] contains a unique identifier 364 for an event. The identifier SHOULD be unique within a particular 365 event feed and MAY be used by clients to track whether a 366 particular event has already been received. This claim is 367 REQUIRED. 369 iss 370 A single valued String containing the URI of the service provider 371 publishing the SET (the issuer). This claim is REQUIRED. 373 aud 374 A multi-valued String containing the URIs representing the 375 audience of the event. Values are typically URLs of the feeds the 376 event is associated with. When an event has multiple audiences 377 that go to the same subscriber, the publisher is not obligated to 378 deliver repeated events to the same subscriber. This claim is 379 RECOMMENDED. 381 iat 382 As defined by Section 4.1.6 [RFC7519], a value containing a 383 NumericDate, which represents when the event was issued. Unless 384 otherwise specified, the value SHOULD be interpreted by the 385 subscriber as equivalent to the actual time of the event. This 386 claim is REQUIRED. 388 nbf 389 As defined by Section 4.1.5 [RFC7519], a value containing a 390 NumericDate, which represents a future date when the event will 391 occur. This claim is OPTIONAL. 393 sub As defined by Section 4.1.2 [RFC7519], a String or URI value 394 representing the principal or the subject of the SET. This is 395 usually the entity whose "state" was changed. For example, an IP 396 Address was added to a black list. A URI representing a user 397 resource that was modified. A token identifier for a revoked 398 token. If used, the profile specification SHOULD define the 399 content and format semantics for the value. This claim is 400 OPTIONAL, as the principal for any given profile may already be 401 identified without the inclusion of a subject claim. 403 exp As defined by [RFC7519], this claim is time on which the JWT 404 MUST NOT be accepted for processing. In the context of a SET 405 however, this notion does not apply since a SET reflects something 406 that has already been processed and is historical in nature. 407 While some specifications MAY have a need for this claim, its use 408 in general cases is NOT RECOMMENDED. 410 The following are new claims defined by this specification: 412 events 413 A JSON object whose members are a set of JSON name/value pairs 414 whose names are URIs representing the primary event (typically the 415 first member) and event extensions being expressed. For each name 416 present, the corresponding value SHALL be a JSON object. The JSON 417 object MAY be an empty object ("{}"), or it MAY be a JSON object 418 containing data as described by the profiling event specification. 420 txn 421 An OPTIONAL single-valued String value that represents a unique 422 transaction identifier. In cases where multiple SETs are issued 423 based on different event URIs, the transaction identifier MAY be 424 used to correlate SETs to the same originating event or stateful 425 change. 427 2.2. Security Event Token Construction 429 A SET is a JWT [RFC7519] that is constructed by building a JSON 430 structure that constitutes an event object and which is then used as 431 the body of a JWT. 433 While this specification uses JWT to convey a SET, implementers SHALL 434 NOT use SETs to convey authentication or authorization assertions. 436 The following is an example JWT Claims Set for a security event token 437 (which has been formatted for readability): 439 { 440 "jti": "4d3559ec67504aaba65d40b0363faad8", 441 "iat": 1458496404, 442 "iss": "https://scim.example.com", 443 "aud": [ 444 "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754", 445 "https://scim.example.com/Feeds/5d7604516b1d08641d7676ee7" 446 ], 448 "events": { 449 "urn:ietf:params:scim:event:create": { 450 "ref": 451 "https://scim.example.com/Users/44f6142df96bd6ab61e7521d9", 452 "attributes":["id", "name", "userName", "password", "emails"], 453 "values": { 454 "emails": [ 455 {"type": "work", "value": "jdoe@example.com"} 456 ], 457 "password": "not4u2no", 458 "userName": "jdoe", 459 "id": "44f6142df96bd6ab61e7521d9", 460 "name": { 461 "givenName": "John", 462 "familyName": "Doe" 463 } 464 } 465 } 466 } 467 } 469 Figure 4: Example Event Claims 471 When transmitted, the above JSON body must be converted into a JWT as 472 per [RFC7519]. In this example, because the event contains attribute 473 values, the token MUST be encrypted per JWE (see [RFC7516]) before 474 transmission. 476 The following is an example of a SCIM Event expressed as an unsecured 477 JWT. The JWT header of: 479 {"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 eyAgCiAgImp0aSI6ICI0ZDM1NTllYzY3NTA0YWFiYTY1ZDQwYjAzNjNmYWFkOCIsCiAg 488 ImlhdCI6IDE0NTg0OTY0MDQsCiAgImlzcyI6ICJodHRwczovL3NjaW0uZXhhbXBsZS5j 489 b20iLCAgCiAgImF1ZCI6IFsKICAgImh0dHBzOi8vc2NpbS5leGFtcGxlLmNvbS9GZWVk 490 cy85OGQ1MjQ2MWZhNWJiYzg3OTU5M2I3NzU0IiwKICAgImh0dHBzOi8vc2NpbS5leGFt 491 cGxlLmNvbS9GZWVkcy81ZDc2MDQ1MTZiMWQwODY0MWQ3Njc2ZWU3IgogIF0sICAKICAK 492 ICAiZXZlbnRzIjogewogICAgInVybjppZXRmOnBhcmFtczpzY2ltOmV2ZW50OmNyZWF0 493 ZSI6IHsKICAgICAgInJlZiI6CiAgICAgICAgImh0dHBzOi8vc2NpbS5leGFtcGxlLmNv 494 bS9Vc2Vycy80NGY2MTQyZGY5NmJkNmFiNjFlNzUyMWQ5IiwKICAgICAgImF0dHJpYnV0 495 ZXMiOlsiaWQiLCAibmFtZSIsICJ1c2VyTmFtZSIsICJwYXNzd29yZCIsICJlbWFpbHMi 496 XSwKICAgICAgInZhbHVlcyI6IHsKICAgICAgICAiZW1haWxzIjogWwogICAgICAgICB7 497 InR5cGUiOiAid29yayIsICJ2YWx1ZSI6ICJqZG9lQGV4YW1wbGUuY29tIn0KICAgICAg 498 ICBdLAogICAgICAgICJwYXNzd29yZCI6ICJub3Q0dTJubyIsCiAgICAgICAgInVzZXJO 499 YW1lIjogImpkb2UiLAogICAgICAgICJpZCI6ICI0NGY2MTQyZGY5NmJkNmFiNjFlNzUy 500 MWQ5IiwKICAgICAgICAibmFtZSI6IHsKICAgICAgICAgICJnaXZlbk5hbWUiOiAiSm9o 501 biIsCiAgICAgICAgICAiZmFtaWx5TmFtZSI6ICJEb2UiCiAgICAgICAgfQogICAgICB9 502 CiAgICB9CiAgfQp9 504 The encoded JWS signature is the empty string. Concatenating the 505 parts yields: 507 eyJhbGciOiJub25lIn0 508 . 509 eyAgCiAgImp0aSI6ICI0ZDM1NTllYzY3NTA0YWFiYTY1ZDQwYjAzNjNmYWFkOCIsCiAg 510 ImlhdCI6IDE0NTg0OTY0MDQsCiAgImlzcyI6ICJodHRwczovL3NjaW0uZXhhbXBsZS5j 511 b20iLCAgCiAgImF1ZCI6IFsKICAgImh0dHBzOi8vc2NpbS5leGFtcGxlLmNvbS9GZWVk 512 cy85OGQ1MjQ2MWZhNWJiYzg3OTU5M2I3NzU0IiwKICAgImh0dHBzOi8vc2NpbS5leGFt 513 cGxlLmNvbS9GZWVkcy81ZDc2MDQ1MTZiMWQwODY0MWQ3Njc2ZWU3IgogIF0sICAKICAK 514 ICAiZXZlbnRzIjogewogICAgInVybjppZXRmOnBhcmFtczpzY2ltOmV2ZW50OmNyZWF0 515 ZSI6IHsKICAgICAgInJlZiI6CiAgICAgICAgImh0dHBzOi8vc2NpbS5leGFtcGxlLmNv 516 bS9Vc2Vycy80NGY2MTQyZGY5NmJkNmFiNjFlNzUyMWQ5IiwKICAgICAgImF0dHJpYnV0 517 ZXMiOlsiaWQiLCAibmFtZSIsICJ1c2VyTmFtZSIsICJwYXNzd29yZCIsICJlbWFpbHMi 518 XSwKICAgICAgInZhbHVlcyI6IHsKICAgICAgICAiZW1haWxzIjogWwogICAgICAgICB7 519 InR5cGUiOiAid29yayIsICJ2YWx1ZSI6ICJqZG9lQGV4YW1wbGUuY29tIn0KICAgICAg 520 ICBdLAogICAgICAgICJwYXNzd29yZCI6ICJub3Q0dTJubyIsCiAgICAgICAgInVzZXJO 521 YW1lIjogImpkb2UiLAogICAgICAgICJpZCI6ICI0NGY2MTQyZGY5NmJkNmFiNjFlNzUy 522 MWQ5IiwKICAgICAgICAibmFtZSI6IHsKICAgICAgICAgICJnaXZlbk5hbWUiOiAiSm9o 523 biIsCiAgICAgICAgICAiZmFtaWx5TmFtZSI6ICJEb2UiCiAgICAgICAgfQogICAgICB9 524 CiAgICB9CiAgfQp9 525 . 527 Figure 5: Example Unsecured Security Event Token 529 To create and or validate a signed or encrypted SET, follow the 530 instructions in section 7 of [RFC7519]. 532 3. Security Considerations 534 3.1. Confidentiality and Integrity 536 SETs may often contain sensitive information. Therefore, methods for 537 distribution of events SHOULD require the use of a transport-layer 538 security mechanism when distributing events. Parties MUST support 539 TLS 1.2 [RFC5246] and MAY support additional transport-layer 540 mechanisms meeting its security requirements. When using TLS, the 541 client MUST perform a TLS/SSL server certificate check, per 542 [RFC6125]. Implementation security considerations for TLS can be 543 found in "Recommendations for Secure Use of TLS and DTLS" [RFC7525]. 545 Security Events distributed through third-parties or that carry 546 personally identifiable information, SHOULD be encrypted using JWE 547 [RFC7516] or secured for confidentiality by other means. 549 Security Events distributed without authentication over the channel, 550 such as via TLS ([RFC5246] and [RFC6125]), and/or OAuth2 [RFC6749], 551 or Basic Authentication [RFC7617], MUST be signed using JWS [RFC7515] 552 so that individual events MAY be authenticated and validated by the 553 subscriber. 555 3.2. Delivery 557 This specification does not define a delivery mechanism by itself. 558 In addition to confidentiality and integrity (discussed above), 559 implementers and profile specifications MUST consider the 560 consequences of delivery mechanisms that are not secure and/or not 561 assured. For example, while a SET may be end-to-end secured using 562 JWE, that alone will not guarantee that the correct subscribing party 563 knows they should have received a particular SET. 565 3.3. Sequencing 567 As defined in this specification, there is no defined way to order 568 multiple SETs in a sequence. Depending on the type and nature of SET 569 event, order may or may not matter. For example, in provisioning, 570 event order is critical -- an object could not be modified before it 571 was created. In other SET types, such as a token revocation, the 572 order of SETs for revoked tokens does not matter. If however, the 573 event was described as a log-in or logged-out status for a user 574 subject, then order becomes important. 576 Extension specifications and implementers SHOULD take caution when 577 using timestamps such as "iat" to define order. Distributed systems 578 will have some amount of clock-skew and thus time by itself will not 579 guarantee order. 581 Specifications profiling SET SHOULD define a mechanism for detecting 582 order or sequence of events. For example, the "txn" claim could 583 contain an ordered value (e.g., a counter) that the publisher 584 defines. 586 3.4. Timing Issues 588 When SETs are delivered asynchronously and/or out-of-band with 589 respect to the original action that incurred the security event, it 590 is important to consider that a SET might be delivered to a 591 Subscriber in advance or well behind the process that caused the 592 event. For example, a user having been required to logout and then 593 log back in again, may cause a logout SET to be issued that may 594 arrive at the same time as the user-agent accesses a web site having 595 just logged-in. If timing is not handled properly, the effect would 596 be to erroneously treat the new user session as logged out. 597 Profiling specifications SHOULD be careful to anticipate timing and 598 subject selection information. For example, it might be more 599 appropriate to cancel a "session" rather than a "user". 600 Alternatively, the specification could use timestamps that allows new 601 sessions to be started immediately after a stated logout event time. 603 3.5. Distinguishing SETs from Access Tokens 605 Because [RFC7519] states that "all claims that are not understood by 606 implementations MUST be ignored.", there is a consideration that a 607 SET token might be confused as an access or authorization token in 608 the case where a SET is mistakenly or intentionally intercepted and 609 presented as an access token. To avoid this, it is recommended that 610 implementers consider one or more of the following: 612 o Avoid use of the JWT claim "exp" within the envelope. 614 o Where possible, use a separate "aud" claim value to distinguish 615 between the SET subscriber and the audience of an access token. 616 For example, a Logout while intended for the same relying party 617 could use a different audience to distinguish between normal 618 access and logout notification. 620 o Modify access validation systems to check for the presence of the 621 "events" claim as a means to detect security event tokens. This 622 is particularly useful if the same endpoint may receive both types 623 of tokens. 625 o Consider avoiding use of the "sub" claim at the top level. 627 4. Privacy Considerations 629 If a SET needs to be retained for audit purposes, JWS MAY be used to 630 provide verification of its authenticity. 632 Event Publishers SHOULD attempt to specialize feeds so that the 633 content is targeted to the specific business and protocol needs of 634 subscribers. 636 When sharing personally identifiable information or information that 637 is otherwise considered confidential to affected users, the 638 publishers and subscribers MUST have the appropriate legal agreements 639 and user consent in place. 641 The propagation of subject identifiers can be perceived as personally 642 identifiable information. Where possible, publishers and subscribers 643 should devise approaches that prevent propagation -- for example, the 644 passing of a hash value that requires the subscriber to already know 645 the subject. 647 5. IANA Considerations 649 5.1. JSON Web Token Claims Registration 651 This specification registers the "events" and "txn" claims in the 652 IANA "JSON Web Token Claims" registry [IANA.JWT.Claims] established 653 by [RFC7519]. 655 5.1.1. Registry Contents 657 o Claim Name: "events" 658 o Claim Description: Security Event Object 659 o Change Controller: IESG 660 o Specification Document(s): Section 2 of [[ this specification ]] 662 o Claim Name: "txn" 663 o Claim Description: Transaction Identifier 664 o Change Controller: IESG 665 o Specification Document(s): Section 2 of [[ this specification ]] 667 6. References 668 6.1. Normative References 670 [IANA.JWT.Claims] 671 IANA, "JSON Web Token Claims", 672 . 674 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 675 Requirement Levels", BCP 14, RFC 2119, 676 DOI 10.17487/RFC2119, March 1997, 677 . 679 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 680 Resource Identifier (URI): Generic Syntax", STD 66, 681 RFC 3986, DOI 10.17487/RFC3986, January 2005, 682 . 684 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 685 (TLS) Protocol Version 1.2", RFC 5246, 686 DOI 10.17487/RFC5246, August 2008, 687 . 689 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 690 Verification of Domain-Based Application Service Identity 691 within Internet Public Key Infrastructure Using X.509 692 (PKIX) Certificates in the Context of Transport Layer 693 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 694 2011, . 696 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 697 RFC 6749, DOI 10.17487/RFC6749, October 2012, 698 . 700 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 701 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 702 . 704 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 705 "Recommendations for Secure Use of Transport Layer 706 Security (TLS) and Datagram Transport Layer Security 707 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 708 2015, . 710 [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", 711 RFC 7617, DOI 10.17487/RFC7617, September 2015, 712 . 714 6.2. Informative References 716 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 717 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 718 August 2013, . 720 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 721 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 722 2015, . 724 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 725 RFC 7516, DOI 10.17487/RFC7516, May 2015, 726 . 728 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 729 DOI 10.17487/RFC7517, May 2015, 730 . 732 [RFC7644] Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E., 733 and C. Mortimore, "System for Cross-domain Identity 734 Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, 735 September 2015, . 737 Appendix A. Acknowledgments 739 The editors would like to thank the participants in the IETF id-event 740 mailing list and related working groups for their support of this 741 specification. 743 Appendix B. Change Log 745 Draft 01 - PH - Renamed eventUris to events 747 Draft 00 - PH - First Draft 749 Draft 01 - PH - Fixed some alignment issues with JWT. Remove event 750 type attribute. 752 Draft 02 - PH - Renamed to Security Events, removed questions, 753 clarified examples and intro text, and added security and privacy 754 section. 756 Draft 03 - PH 758 General edit corrections from Sarah Squire 759 Changed "event" term to "SET" 760 Corrected author organization for William Denniss to Google 761 Changed definition of SET to be 2 parts, an envelope and 1 or more 762 payloads. 763 Clarified that the intent is to express a single event with 764 optional extensions only. 766 - mbj - Registered "events" claim, and proof-reading corrections. 768 Draft 04 - PH - 770 o Re-added the "sub" claim with clarifications that any SET type may 771 use it. 772 o Added additional clarification on the use of envelope vs. payload 773 attributes 774 o Added security consideration for event timing. 775 o Switched use of "attribute" to "claim" for consistency. 776 o Revised examples to put "sub" claim back in the top level. 777 o Added clarification that SETs typically do not use "exp". 778 o Added security consideration for distinguishing Access Tokens and 779 SETs. 781 Draft 05 - PH - Fixed find/replace error that resulted in claim being 782 spelled claimc 784 Draft 06 - PH - 786 o Corrected typos 787 o New txn claim 788 o New security considerations Sequencing and Timing Issues 790 Draft 07 - 792 o PH - Moved payload objects to be values of event URI attributes, 793 per discussion. 794 o mbj - Applied terminology consistency and grammar cleanups. 796 Authors' Addresses 798 Phil Hunt (editor) 799 Oracle Corporation 801 Email: phil.hunt@yahoo.com 803 William Denniss 804 Google 806 Email: wdenniss@google.com 807 Morteza Ansari 808 Cisco 810 Email: morteza.ansari@cisco.com 812 Michael B. Jones 813 Microsoft 815 Email: mbj@microsoft.com 816 URI: http://self-issued.info/