idnits 2.17.1 draft-hunt-idevent-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 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 (September 2, 2016) is 2792 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: 'RFC7159' is defined on line 664, but no explicit reference was found in the text == Unused Reference: 'RFC7517' is defined on line 700, 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 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) Summary: 4 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. Hunt, Ed. 3 Internet-Draft Oracle 4 Intended status: Standards Track W. Denniss 5 Expires: March 6, 2017 Google 6 M. Ansari 7 Cisco 8 M. Jones 9 Microsoft 10 September 2, 2016 12 Security Event Token (SET) 13 draft-hunt-idevent-token-05 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 March 6, 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 . . . . . . . . . . . . . . . . . . . 12 64 3.1. Confidentiality and Integrity . . . . . . . . . . . . . . 12 65 3.2. Timing Issues . . . . . . . . . . . . . . . . . . . . . . 13 66 3.3. Distinguishing SETs from Access Tokens . . . . . . . . . 13 67 4. Privacy Considerations . . . . . . . . . . . . . . . . . . . 14 68 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 69 5.1. JSON Web Token Claims Registration . . . . . . . . . . . 14 70 5.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 14 71 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 72 6.1. Normative References . . . . . . . . . . . . . . . . . . 14 73 6.2. Informative References . . . . . . . . . . . . . . . . . 15 74 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 16 75 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 16 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 78 1. Introduction and Overview 80 This specification defines an extensible Security Event Token (SET) 81 format which may be exchanged using protocols such as HTTP. The 82 specification builds on the JSON Web Token (JWT) format [RFC7519] in 83 order to provide a self-contained token that can be optionally signed 84 using JSON Web Signature (JWS) [RFC7515] and/or encrypted using JSON 85 Web Encryption (JWE) [RFC7516]. 87 For the purpose of this specification, an event is a statement of 88 fact by a publisher (also known as the event issuer) that the state 89 of a security subject (e.g., a web resource, token, IP address) it 90 controls or is aware of, has changed in some way (explicitly or 91 implicitly). A security subject may be permanent (e.g., a user 92 account) or temporary (e.g., a login session) in nature. A state 93 change may include direct changes of entity state, implicit changes 94 to state or other higher-level security statements such as: 96 o The creation, modification, removal of a resource. 98 o The resetting or suspension of an account. 100 o The revocation of a security token prior to its expiry. 102 o The logout of a user session. Or, 104 o A cumulative conclusion such as to indicate that a user has taken 105 over an email identifier that may have been used in the past by 106 another user. 108 Based on some agreed upon criteria for an event Feed, the publisher 109 distributes events to the appropriate subscribers. While an event 110 may be delivered via synchronous means (e.g., HTTP POST), the 111 distribution of the event often happens asynchronously to the change 112 of state which generated the security event. As an example, an 113 OAuth2 Authorization Server [RFC6749], having received a token 114 revocation request [RFC7009], may issue a token revocation event to 115 downstream web resource providers. Having been informed of a token 116 revocation, the OAuth2 web resource service provider may add the 117 token identifier to its local revocation list assuming the token has 118 not already expired. 120 A subscriber having received an event, validates and interprets the 121 event and takes its own independent action, if any. For example, 122 having been informed of a personal identifier now being associated 123 with a different security subject (i.e., is being used by someone 124 else), the subscriber may choose to ensure that the new user is not 125 granted access to resources associated with the previous user. Or it 126 may not have any relationship with the subject, and no action is 127 taken. 129 While subscribers will often take actions upon receiving one or more 130 events, events MUST NOT be assumed to be commands or requests. To do 131 so requires complex bi-directional signals and error recovery 132 mechanisms that fall outside the scope of this specification. The 133 intent of this specification is to define a way of exchanging 134 statements of fact that subscribers may interpret for their own 135 purposes. Since events are typically historical statements by a 136 publisher and are not commands, idempotency or lack thereof, does not 137 apply. 139 Unless otherwise specified, this specification uses example events 140 intended as non-normative examples showing how an event may be used. 141 It is expected that other specifications will use this specification 142 to define normative events. 144 This specification is scoped to security and identity related events. 145 While event tokens may be used for other purposes, the specification 146 only considers security and privacy concerns relevant to identity and 147 personal information. 149 1.1. Notational Conventions 151 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 152 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 153 document are to be interpreted as described in [RFC2119]. These 154 keywords are capitalized when used to unambiguously specify 155 requirements of the protocol or application features and behavior 156 that affect the inter-operability and security of implementations. 157 When these words are not capitalized, they are meant in their 158 natural-language sense. 160 For purposes of readability, examples are not URL encoded. 161 Implementers MUST percent encode URLs as described in Section 2.1 of 162 [RFC3986]. 164 Throughout this document, all figures MAY contain spaces and extra 165 line-wrapping for readability and space limitations. Similarly, some 166 URIs contained within examples have been shortened for space and 167 readability reasons. 169 1.2. Definitions 171 The following definitions are used with SETs: 173 Feed Publisher 174 The Feed Publisher creates SETs to be distributed to registered 175 subscribers. In JWT terminology, the Feed Publisher is also known 176 as the issuer ("iss"). 178 Security Event Token (SET) 179 An SET is a JWT that is to be distributed to one or more 180 registered subscribers. A SET MAY be signed or encrypted using 181 JWS and/or JWE for authentication and confidentiality reasons. 183 Feed 184 A Feed is a logical grouping of SETs or a context under which SETs 185 may be issued. A Subscriber registers with the Feed Publisher to 186 subscribe to SETs associated with a Feed. How a Feed is defined 187 or the method for subscription is out-of-scope of this 188 specification. 190 Subscriber 191 A Subscriber registers to receive SETs from a Feed Publisher using 192 a protocol such as HTTP. The method of registration and delivery 193 is out-of-scope of this specification. 195 Security Subject 196 A Security Subject is the entity to which a SET refers. A 197 Security Subject may be a principle (e.g., Section 4.1.2 198 [RFC7519]), a web resource, or other thing such as an IP address 199 that a SET might reference. 201 2. The Security Event Token (SET) 203 A SET conveys a statement (in the form of a JWT [RFC7519]) about a 204 single security event in relation to a Security Subject that may be 205 of interest to a Subscriber or set of Subscribers receiving SETs from 206 a Feed Publisher. 208 The schema and structure of a SET follows the JWT [RFC7519] 209 specification. A SET has the following structure: 211 o An outer JSON structure that acts as the SET envelope. The 212 envelope contains a set of JSON attributes, called JWT claims, 213 typically common to every SET or common to a number of different 214 Security Events within a single profiling specification or a 215 related series of specifications. Claims in the envelope SHOULD 216 be registered in the JWT Token Claims Registry Section 10.1 217 [RFC7519] or be Public Claims or Private Claims as also defined in 218 [RFC7519]. 220 o Envelope claims that are profiled and defined in this 221 specification are used to validate the SET and determine the event 222 data included. The claim "events" describes the type of SET event 223 and indicates the data that MAY be present in the SET. While a 224 SET contains a single event, it MAY have multiple extensions 225 providing additional data about the same event. The primary event 226 is the first value in the "events" array, while event extensions 227 are the 2nd, 3rd, etc. 229 o For each value of "events", a JSON attribute, whose value is a 230 JSON object, MAY be added known as an event "payload". The 231 payload object contains claims typically unique to the events URI 232 value and are not registered as JWT claims. These claims are 233 defined within their associated event specification. Event 234 extensions can be used for many purposes. Some examples include 235 but are not limited to: 237 * A categorization extension applied to multiple event types in 238 order to provide classification information (e.g. threat type 239 or level). 241 * Enhancement of an existing specifications the arise over time. 243 * Correlation extensions needed to link a potential series of 244 events. 246 * Localized contextual extensions needed between a publisher and 247 subscriber. 249 The following is a non-normative example showing a hypothetical SCIM 250 password reset SET. The example also shows an example where the 251 issuer has provided an extension ("https://example.com/scim/event/ 252 passwordResetExt") that is used to convey additional information such 253 as the current count of reset attempts: 255 { 256 "jti": "3d0c3cf797584bd193bd0fb1bd4e7d30", 257 "events":[ 258 "urn:ietf:params:scim:event:passwordReset", 259 "https://example.com/scim/event/passwordResetExt" 260 ], 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 "urn:ietf:params:scim:event:passwordReset":{ 269 "id":"44f6142df96bd6ab61e7521d9" 270 }, 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" claims, denotes the event publisher. 289 o The "sub" claims specifies the SCIM resource URI that was 290 affected. 292 o The "aud" claims specifies the intended audience for the event. 293 In practical terms, this MAY be the URI for the event Feed that a 294 client has subscribed to. 296 Additional extensions to an event may be added by adding more values 297 to the "events" claims. For each event URI value specified, there 298 MAY be a corresponding claim that has a JSON object that contains the 299 claims associated with that event (e.g., 300 "https://example.com/scim/event/passwordResetExt"). In this example, 301 the SCIM event indicates that a password has been updated and the 302 current password reset count is 5. Notice that the value for 303 "resetAttempts" is actually part of its own JSON object 304 "https://example.com/scim/event/passwordResetExt". 306 Here is another example event token, this one for a Logout Token: 308 { 309 "iss": "https://server.example.com", 310 "aud": "https://rp.example.com", 311 "jti": "3d0c3cf797584bd193bd0fb1bd4e7d30", 312 "iat": 1458668180, 313 "exp": 1458668580, 314 "sub": "248289761001", 315 "events": [ 316 "https://specs.openid.net/logout" 317 ], 318 "https://specs.openid.net/logout": { 319 "iss": "https://token.example.com", 320 "sid": "08a5019c-17e1-4977-8f42-65a12843ea02" 321 } 322 } 324 Figure 2: Example OpenID Logout Event 326 In the above example, the event has its own issuer, 327 "https://server.example.com" while the event is about the logging out 328 of a user session identified in the event extension by "jti" that was 329 issued by "https://token.example.com". 331 In the following example, a fictional medical service collects 332 consent for medical actions and notifies other parties. The 333 individual for whom consent is identified was originally 334 authenticated via OpenID Connect. In this case, the issuer of the 335 SET event is an application rather than the OpenID provider: 337 { 338 "jti": "fb4e75b5411e4e19b6c0fe87950f7749", 339 "events":[ 340 "https://openid.net/heart/consent.html" 341 ], 342 "sub": "248289761001", 343 "iat": 1458496025, 344 "iss": "https://my.examplemed.com", 345 "aud":[ 346 "https://rp.example.com" 347 ], 348 "https://openid.net/heart/consent":{ 349 "consentUri":[ 350 "https://terms.examplemed.com/labdisclosure.html#Agree" 351 ] 352 } 353 } 355 Figure 3: Example Consent Event 357 In the above example "iss" and "sub" contained within the claim 358 "https://openid.net/heart/consent", refer to the subject and issuer 359 of the original OpendID Provider. They are distinct from the top 360 level value of "iss" which always refers to the issuer of the event - 361 a medical consent service that is a relying party to the OpenID 362 Provider. 364 2.1. Core SET Claims 366 The following are claims that are based on [RFC7519] claim 367 definitions and are profiled for use in an event token: 369 jti 370 As defined by Section 4.1.7 [RFC7519] contains a unique identifier 371 for an event. The identifier SHOULD be unique within a particular 372 event Feed and MAY be used by clients to track whether a 373 particular event has already been received. This claim is 374 REQUIRED. 376 iss 377 A single valued String containing the URI of the service provider 378 publishing the SET (the issuer). This claim is REQUIRED. 380 aud 381 A multi-valued String containing the URIs representing the 382 audience of the event. Values are typically URLs of the Feeds the 383 event is associated with. When an event has multiple audiences 384 that go to the same subscriber, the publisher is not obligated to 385 deliver repeated events to the same subscriber. This claim is 386 RECOMMENDED. 388 iat 389 As defined by Section 4.1.6 [RFC7519], a value containing a 390 NumericDate, which represents when the event was issued. Unless 391 otherwise specified, the value SHOULD be interpreted by the 392 subscriber as equivalent to the actual time of the event. This 393 claim is REQUIRED. 395 nbf 396 As defined by Section 4.1.5 [RFC7519], a value containing a 397 NumericDate, which represents a future date when the event will 398 occur. This claim is OPTIONAL. 400 sub As defined by Section 4.1.2 [RFC7519], a String or URI value 401 representing the principal or the subject of the SET. This is 402 usually the entity whose "state" was changed. For example, an IP 403 Address was added to a black list. A URI representing a user 404 resource that was modified. A token identifier for a revoked 405 token. If used, the profile specification SHOULD define the 406 content and format semantics for the value. This claim is 407 OPTIONAL, as the principal for any given profile may already be 408 identified without the inclusion of a subject claim. 410 exp As defined by [RFC7519], this claim is time on which the JWT 411 MUST NOT be accepted for processing. In the context of a SET 412 however, this notion does not apply since a SET reflects something 413 that has already been processed and is historical in nature. 414 While some specifications MAY have a need for this claim, its use 415 in general cases is NOT RECOMMENDED. 417 The following is a new claim defined by this specification: 419 events 420 A multi-valued String that contains one or more URIs representing 421 the type of event being expressed and the claims that MAY be 422 available within the JWT. The first value SHALL indicate the type 423 of SET event and following values represent extensions to that 424 event. For each value present, there MAY be an associated JSON 425 sub-objects present in the SET. Each JSON sub-object is denoted 426 by an claim whose name matches a value in "events". This claim is 427 REQUIRED to have at least one value. 429 2.2. Security Event Token Construction 431 A SET is a JWT [RFC7519] that is constructed by building a JSON 432 structure that constitutes an event object and which is then used as 433 the body of a JWT. 435 While this specification uses JWT to convey a SET, implementers SHALL 436 NOT use SETs to convey authentication or authorization assertions. 438 The following is an example event token (which has been formatted for 439 readability): 441 { 442 "jti": "4d3559ec67504aaba65d40b0363faad8", 443 "iat": 1458496404, 444 "iss": "https://scim.example.com", 445 "aud":[ 446 "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754", 447 "https://scim.example.com/Feeds/5d7604516b1d08641d7676ee7" 448 ], 450 "events":[ 451 "urn:ietf:params:scim:event:create" 452 ], 453 "urn:ietf:params:scim:event:create":{ 454 "ref": "https://scim.example.com/Users/44f6142df96bd6ab61e7521d9", 455 "attributes":["id", "name", "userName", "password", "emails"], 456 "values":{ 457 "emails":[ 458 {"type":"work", "value":"jdoe@example.com"} 459 ], 460 "password":"not4u2no", 461 "userName":"jdoe", 462 "id":"44f6142df96bd6ab61e7521d9", 463 "name":{ 464 "givenName":"John", 465 "familyName":"Doe" 466 } 467 } 468 } 469 } 471 Figure 4: Example Event JSON Data 473 When transmitted, the above JSON body must be converted into a JWT as 474 per [RFC7519]. In this example, because the event contains attribute 475 values, the token MUST be encrypted per JWE (see [RFC7516]) before 476 transmission. 478 The following is an example of a SCIM Event expressed as an unsecured 479 JWT. The JWT header of: 481 {"alg":"none"} 483 Base64url encoding of the octets of the UTF-8 representation of the 484 header yields: 486 eyJhbGciOiJub25lIn0 488 The example JSON Event Data is encoded as follows: 490 eyAgCiAgImp0aSI6ICI0ZDM1NTllYzY3NTA0YWFiYTY1ZDQwYjAzNjNmYWFkOCIsCiAg 491 ImlhdCI6IDE0NTg0OTY0MDQsCiAgImlzcyI6ICJodHRwczovL3NjaW0uZXhhbXBsZS5j 492 b20iLCAgCiAgImF1ZCI6WwogICAiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tL0ZlZWRz 493 Lzk4ZDUyNDYxZmE1YmJjODc5NTkzYjc3NTQiLAogICAiaHR0cHM6Ly9zY2ltLmV4YW1w 494 bGUuY29tL0ZlZWRzLzVkNzYwNDUxNmIxZDA4NjQxZDc2NzZlZTciCiAgXSwgIAogIAog 495 ICJldmVudHMiOlsKICAgICJ1cm46aWV0ZjpwYXJhbXM6c2NpbTpldmVudDpjcmVhdGUi 496 CiAgXSwKICAidXJuOmlldGY6cGFyYW1zOnNjaW06ZXZlbnQ6Y3JlYXRlIjp7CiAgICAi 497 cmVmIjogImh0dHBzOi8vc2NpbS5leGFtcGxlLmNvbS9Vc2Vycy80NGY2MTQyZGY5NmJk 498 NmFiNjFlNzUyMWQ5IiwKICAgICJhdHRyaWJ1dGVzIjpbImlkIiwibmFtZSIsInVzZXJO 499 YW1lIiwicGFzc3dvcmQiLCJlbWFpbHMiXSwKICAgICJ2YWx1ZXMiOnsKICAgICAgImVt 500 YWlscyI6WwogICAgICAgeyJ0eXBlIjoid29yayIsInZhbHVlIjoiamRvZUBleGFtcGxl 501 LmNvbSJ9CiAgICAgIF0sCiAgICAgICJwYXNzd29yZCI6Im5vdDR1Mm5vIiwKICAgICAg 502 InVzZXJOYW1lIjoiamRvZSIsCiAgICAgICJpZCI6IjQ0ZjYxNDJkZjk2YmQ2YWI2MWU3 503 NTIxZDkiLAogICAgICAibmFtZSI6ewogICAgICAgICJnaXZlbk5hbWUiOiJKb2huIiwK 504 ICAgICAgICAiZmFtaWx5TmFtZSI6IkRvZSIKICAgICAgfQogICAgfSAgCiAgfQp9 505 The encoded JWS signature is the empty string. Concatenating the 506 parts yields: 508 eyJhbGciOiJub25lIn0 509 . 510 eyAgCiAgImp0aSI6ICI0ZDM1NTllYzY3NTA0YWFiYTY1ZDQwYjAzNjNmYWFkOCIsCiAg 511 ImlhdCI6IDE0NTg0OTY0MDQsCiAgImlzcyI6ICJodHRwczovL3NjaW0uZXhhbXBsZS5j 512 b20iLCAgCiAgImF1ZCI6WwogICAiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tL0ZlZWRz 513 Lzk4ZDUyNDYxZmE1YmJjODc5NTkzYjc3NTQiLAogICAiaHR0cHM6Ly9zY2ltLmV4YW1w 514 bGUuY29tL0ZlZWRzLzVkNzYwNDUxNmIxZDA4NjQxZDc2NzZlZTciCiAgXSwgIAogIAog 515 ICJldmVudHMiOlsKICAgICJ1cm46aWV0ZjpwYXJhbXM6c2NpbTpldmVudDpjcmVhdGUi 516 CiAgXSwKICAidXJuOmlldGY6cGFyYW1zOnNjaW06ZXZlbnQ6Y3JlYXRlIjp7CiAgICAi 517 cmVmIjogImh0dHBzOi8vc2NpbS5leGFtcGxlLmNvbS9Vc2Vycy80NGY2MTQyZGY5NmJk 518 NmFiNjFlNzUyMWQ5IiwKICAgICJhdHRyaWJ1dGVzIjpbImlkIiwibmFtZSIsInVzZXJO 519 YW1lIiwicGFzc3dvcmQiLCJlbWFpbHMiXSwKICAgICJ2YWx1ZXMiOnsKICAgICAgImVt 520 YWlscyI6WwogICAgICAgeyJ0eXBlIjoid29yayIsInZhbHVlIjoiamRvZUBleGFtcGxl 521 LmNvbSJ9CiAgICAgIF0sCiAgICAgICJwYXNzd29yZCI6Im5vdDR1Mm5vIiwKICAgICAg 522 InVzZXJOYW1lIjoiamRvZSIsCiAgICAgICJpZCI6IjQ0ZjYxNDJkZjk2YmQ2YWI2MWU3 523 NTIxZDkiLAogICAgICAibmFtZSI6ewogICAgICAgICJnaXZlbk5hbWUiOiJKb2huIiwK 524 ICAgICAgICAiZmFtaWx5TmFtZSI6IkRvZSIKICAgICAgfQogICAgfSAgCiAgfQp9 525 . 527 Figure 5: Example Unsecured 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. Timing Issues 557 When SETs are delivered asynchronously and/or out-of-band with 558 respect to the original action that incurred the security event, it 559 is important to consider that a SET might be delivered to a 560 Subscriber in advance or well behind the process that caused the 561 event. For example, a user having been required to logout and then 562 log back in again, may cause a logout SET to be issued that may 563 arrive at the same time as the user-agent accesses a web site having 564 just logged-in. If timing is not handled properly, the effect would 565 be to erroneously treat the new user session as logged out. 566 Profiling specifications SHOULD be careful to anticipate timing and 567 subject selection information. For example, it might be more 568 appropriate to cancel a "session" rather than a "user". 569 Alternatively, the specification could use timestamps that allows new 570 sessions to be started immediately after a stated logout event time. 572 3.3. Distinguishing SETs from Access Tokens 574 Because [RFC7519] states that "all claims that are not understood by 575 implementations MUST be ignored.", there is a consideration that a 576 SET token might be confused as an access or authorization token in 577 the case where a SET is mistakenly or intentionally intercepted and 578 presented as an access token. To avoid this it is recommended that 579 implementers consider one or more of the following: 581 o Avoid use of the JWT claim "exp" within the envelope. 583 o Where possible, use a separate "aud" claim value to distinguish 584 between the SET subscriber and the audience of an access token. 585 For example, a Logout while itended for the same relying party 586 could use a different audience to distinguish between normal 587 access and logout notification. 589 o Modify access validation systems to check for the presence of the 590 "events" claim as a means to detect SET event tokens. This is 591 particularly useful if the same endpoint may receive both types of 592 tokens. 594 o Consider avoiding use of the "sub" claim at the top level. 596 4. Privacy Considerations 598 If a SET needs to be retained for audit purposes, JWS MAY be used to 599 provide verification of its authenticity. 601 Event Publishers SHOULD attempt to specialize Feeds so that the 602 content is targeted to the specific business and protocol needs of 603 subscribers. 605 When sharing personally identifiable information or information that 606 is otherwise considered confidential to affected users, the 607 publishers and subscribers MUST have the appropriate legal agreements 608 and user consent in place. 610 The propagation of subject identifiers can be perceived as personally 611 identifiable information. Where possible, publishers and subscribers 612 should devise approaches that prevent propagation -- for example, the 613 passing of a hash value that requires the subscriber to already know 614 the subject. 616 5. IANA Considerations 618 5.1. JSON Web Token Claims Registration 620 This specification registers the "events" claim in the IANA "JSON Web 621 Token Claims" registry [IANA.JWT.Claims] established by [RFC7519]. 623 5.1.1. Registry Contents 625 o Claim Name: "events" 626 o Claim Description: Security Events 627 o Change Controller: IESG 628 o Specification Document(s): Section 2 of [[ this specification ]] 630 6. References 632 6.1. Normative References 634 [IANA.JWT.Claims] 635 IANA, "JSON Web Token Claims", 636 . 638 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 639 Requirement Levels", BCP 14, RFC 2119, 640 DOI 10.17487/RFC2119, March 1997, 641 . 643 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 644 Resource Identifier (URI): Generic Syntax", STD 66, 645 RFC 3986, DOI 10.17487/RFC3986, January 2005, 646 . 648 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 649 (TLS) Protocol Version 1.2", RFC 5246, 650 DOI 10.17487/RFC5246, August 2008, 651 . 653 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 654 Verification of Domain-Based Application Service Identity 655 within Internet Public Key Infrastructure Using X.509 656 (PKIX) Certificates in the Context of Transport Layer 657 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 658 2011, . 660 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 661 RFC 6749, DOI 10.17487/RFC6749, October 2012, 662 . 664 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 665 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 666 2014, . 668 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 669 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 670 . 672 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 673 "Recommendations for Secure Use of Transport Layer 674 Security (TLS) and Datagram Transport Layer Security 675 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 676 2015, . 678 [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", 679 RFC 7617, DOI 10.17487/RFC7617, September 2015, 680 . 682 6.2. Informative References 684 [idevent-scim] 685 Oracle Corporation, "SCIM Event Extensions (work in 686 progress)", . 688 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 689 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 690 August 2013, . 692 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 693 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 694 2015, . 696 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 697 RFC 7516, DOI 10.17487/RFC7516, May 2015, 698 . 700 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 701 DOI 10.17487/RFC7517, May 2015, 702 . 704 [RFC7644] Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E., 705 and C. Mortimore, "System for Cross-domain Identity 706 Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, 707 September 2015, . 709 Appendix A. Acknowledgments 711 The editors would like to thank the participants in the IETF id-event 712 mailing list and related working groups for their support of this 713 specification. 715 Appendix B. Change Log 717 Draft 01 - PH - Renamed eventUris to events 719 Draft 00 - PH - First Draft 721 Draft 01 - PH - Fixed some alignment issues with JWT. Remove event 722 type attribute. 724 Draft 02 - PH - Renamed to Security Events, Removed questions, 725 clarified examples and intro text, and added security and privacy 726 section. 728 Draft 03 - PH 730 General edit corrections from Sarah Squire 731 Changed "event" term to "SET" 732 Corrected author organization for William Denniss to Google 733 Changed definition of SET to be 2 parts, an envelope and 1 or more 734 payloads. 735 Clarified that the intent is to express a single event with 736 optional extensions only. 738 - mbj - Registered "events" claim, and proofreading corrections. 740 Draft 04 - PH - 742 o Re-added the "sub" claim with clarifications that any SET type may 743 use it. 744 o Added additional clarification on the use of envelope vs. paylaod 745 attributes 746 o Added security consideration for event timing. 747 o Switched use of "attribute" to "claim" for consistency. 748 o Revised examples to put "sub" claim back in the top level. 749 o Added clarification that SETs typically do not use "exp". 750 o Added security consideration for distinguishing Access Tokens and 751 SETs. 753 Draft 05 - PH - Fixed find/replace error that resulted in claim being 754 spelled claimc 756 Authors' Addresses 758 Phil Hunt (editor) 759 Oracle Corporation 761 Email: phil.hunt@yahoo.com 763 William Denniss 764 Google 766 Email: wdenniss@google.com 768 Morteza Ansari 769 Cisco 771 Email: morteza.ansari@cisco.com 773 Michael B. Jones 774 Microsoft 776 Email: mbj@microsoft.com 777 URI: http://self-issued.info/