idnits 2.17.1 draft-ietf-secevent-token-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 26, 2017) is 2367 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC7617' is defined on line 845, but no explicit reference was found in the text == Unused Reference: 'RFC7009' is defined on line 876, but no explicit reference was found in the text == Unused Reference: 'RFC7517' is defined on line 888, but no explicit reference was found in the text ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) == Outdated reference: A later version (-01) exists of draft-sheffer-oauth-jwt-bcp-00 Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Security Events Working Group P. Hunt, Ed. 3 Internet-Draft Oracle 4 Intended status: Standards Track W. Denniss 5 Expires: April 29, 2018 Google 6 M. Ansari 7 Cisco 8 M. Jones 9 Microsoft 10 October 26, 2017 12 Security Event Token (SET) 13 draft-ietf-secevent-token-03 15 Abstract 17 This specification defines the Security Event Token, which may be 18 distributed via a protocol such as HTTP. The Security Event Token 19 (SET) specification profiles the JSON Web Token (JWT), which can be 20 optionally signed and/or encrypted. A SET describes a statement of 21 fact from the perspective of an issuer that it intends to share with 22 one or more receivers. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on April 29, 2018. 41 Copyright Notice 43 Copyright (c) 2017 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 2 59 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 60 1.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 61 2. The Security Event Token (SET) . . . . . . . . . . . . . . . 5 62 2.1. Core SET Claims . . . . . . . . . . . . . . . . . . . . . 8 63 2.2. Explicit Typing of SETs . . . . . . . . . . . . . . . . . 10 64 2.3. Security Event Token Construction . . . . . . . . . . . . 10 65 3. Requirements for SET Profiles . . . . . . . . . . . . . . . . 12 66 4. Security Considerations . . . . . . . . . . . . . . . . . . . 13 67 4.1. Confidentiality and Integrity . . . . . . . . . . . . . . 13 68 4.2. Delivery . . . . . . . . . . . . . . . . . . . . . . . . 13 69 4.3. Sequencing . . . . . . . . . . . . . . . . . . . . . . . 13 70 4.4. Timing Issues . . . . . . . . . . . . . . . . . . . . . . 14 71 4.5. Distinguishing SETs from ID Tokens . . . . . . . . . . . 14 72 4.6. Distinguishing SETs from Access Tokens . . . . . . . . . 15 73 4.7. Distinguishing SETs from other kinds of JWTs . . . . . . 15 74 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 16 75 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 76 6.1. JSON Web Token Claims Registration . . . . . . . . . . . 17 77 6.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 78 6.2. Media Type Registration . . . . . . . . . . . . . . . . . 17 79 6.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 80 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 81 7.1. Normative References . . . . . . . . . . . . . . . . . . 18 82 7.2. Informative References . . . . . . . . . . . . . . . . . 19 83 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 20 84 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 20 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 87 1. Introduction and Overview 89 This specification defines an extensible Security Event Token (SET) 90 format which may be exchanged using protocols such as HTTP. The 91 specification builds on the JSON Web Token (JWT) format [RFC7519] in 92 order to provide a self-contained token that can be optionally signed 93 using JSON Web Signature (JWS) [RFC7515] and/or encrypted using JSON 94 Web Encryption (JWE) [RFC7516]. 96 This specification profiles the use of JWT for the purpose of issuing 97 security event tokens (SETs). This specification defines a base 98 format upon which profiling specifications define actual events and 99 their meanings. Unless otherwise specified, this specification uses 100 non-normative example events intended to demonstrate how events may 101 be constructed. 103 This specification is scoped to security and identity related events. 104 While security event tokens may be used for other purposes, the 105 specification only considers security and privacy concerns relevant 106 to identity and personal information. 108 Security Events are not commands issued between parties. A security 109 event is a statement of fact from the perspective of an issuer about 110 the state of a security subject (e.g., a web resource, token, IP 111 address, the issuer itself) that the issuer controls or is aware of, 112 that has changed in some way (explicitly or implicitly). A security 113 subject MAY be permanent (e.g., a user account) or temporary (e.g., 114 an HTTP session) in nature. A state change could describe a direct 115 change of entity state, an implicit change of state or other higher- 116 level security statements such as: 118 o The creation, modification, removal of a resource. 120 o The resetting or suspension of an account. 122 o The revocation of a security token prior to its expiry. 124 o The logout of a user session. Or, 126 o A cumulative conclusion such as to indicate that a user has taken 127 over an email identifier that may have been used in the past by 128 another user. 130 While subject state changes are often triggered by a user-agent or 131 security-subsystem, the issuance and transmission of an event often 132 occurs asynchronously and in a back-channel to the action which 133 caused the change that generated the security event. Subsequently, 134 an Event Receiver, having received a SET, validates and interprets 135 the received SET and takes its own independent actions, if any. For 136 example, having been informed of a personal identifier being 137 associated with a different security subject (e.g., an email address 138 is being used by someone else), the Event Receiver may choose to 139 ensure that the new user is not granted access to resources 140 associated with the previous user. Or, the Event Receiver may not 141 have any relationship with the subject, and no action is taken. 143 While Event Receivers will often take actions upon receiving SETs, 144 security events cannot be assumed to be commands or requests. The 145 intent of this specification is to define a way of exchanging 146 statements of fact that Event Receivers may interpret for their own 147 purposes. As such, SETs have no capability for error signaling other 148 to ensure the validation of a received SET. 150 1.1. Notational Conventions 152 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 153 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 154 "OPTIONAL" in this document are to be interpreted as described in 155 [RFC2119]. These keywords are capitalized when used to unambiguously 156 specify requirements of the protocol or application features and 157 behavior that affect the inter-operability and security of 158 implementations. When these words are not capitalized, they are 159 meant in their natural-language sense. 161 For purposes of readability, examples are not URL encoded. 162 Implementers MUST percent encode URLs as described in Section 2.1 of 163 [RFC3986]. 165 Throughout this document, all figures MAY contain spaces and extra 166 line-wrapping for readability and space limitations. Similarly, some 167 URIs contained within examples have been shortened for space and 168 readability reasons. 170 1.2. Definitions 172 The following definitions are used with SETs: 174 Security Event Token (SET) 175 A SET is a JWT [RFC7519] that is distributed to one or more 176 registered Event Receivers. 178 Event Transmitter 179 A service provider that delivers SETs to other providers known as 180 Event Receivers. 182 Event Receiver 183 An Event Receiver is an entity that receives SETs through some 184 distribution method. An Event Receiver is the same entity 185 referred as "recipient" or "receiver" in and related 186 specifications. [RFC7519] 188 Subject 189 A SET describes an event or state change that has occurred about a 190 Subject. A Subject may be a principal (e.g., Section 4.1.2 192 [RFC7519]), a web resource, an entity such as an IP address, or 193 the issuer itself that a SET might reference. 195 Profiling Specification A specification that uses the SET Token 196 specification to define one or more event types and the associated 197 claims included. 199 2. The Security Event Token (SET) 201 A SET is a data structure (in the form of a JWT [RFC7519]) 202 representing one or more related security events about a Subject. 204 The schema and structure of a SET follows the JWT [RFC7519] 205 specification. A SET has the following structure: 207 o An outer JSON object that acts as the SET "envelope". The 208 envelope contains a set of name/value pairs called the JWT Claims 209 Set, typically common to every SET or common to a number of 210 different Events within a single Profiling Specification or a 211 related series of specifications. Claims in the envelope (the 212 outer JSON structure) SHOULD be registered in the JWT Token Claims 213 Registry [IANA.JWT.Claims] or be Public Claims or Private Claims 214 as also defined in [RFC7519]. 216 o Envelope claims that are profiled and defined in this 217 specification are used to validate a SET and declare the contents 218 of the event data included in the SET. The claim "events" 219 identifies the event types expressed that are related to the 220 Security Subject and MAY also include event-specific data. 222 o Each JSON member of the "events" object is a name and value pair. 223 The JSON attribute name is a URI String value that expresses an 224 event type, and the corresponding value is a JSON object known as 225 the event "payload". The payload JSON object contains claims 226 typically unique to the event's URI type value and are not 227 registered as JWT claims. These claims are defined by their 228 associated Profiling Specification. An event with no payload 229 claims SHALL be represented as the empty JSON object ("{}"). In 230 many cases, one event URI expresses the primary event URI, while 231 other events might be considered extensions that MAY be used to do 232 things such as: 234 * A categorization event type to provide classification 235 information (e.g., threat type or level). 237 * An enhancement of an existing specifications the arise over 238 time. 240 * An extension needed to link a potential series of events. 242 * Localized specific purpose event URI used between a particular 243 Event Transmitter and Receiver. 245 The following is a non-normative example showing the JWT Claims Set 246 for a hypothetical SCIM password reset SET. This example shows an 247 additional events value ("https://example.com/scim/event/ 248 passwordResetExt") used to convey additional information -- in this 249 case, the current count of reset attempts: 251 { 252 "jti": "3d0c3cf797584bd193bd0fb1bd4e7d30", 253 "iat": 1458496025, 254 "iss": "https://scim.example.com", 255 "aud": [ 256 "https://jhub.example.com/Feeds/98d52461fa5bbc879593b7754", 257 "https://jhub.example.com/Feeds/5d7604516b1d08641d7676ee7" 258 ], 259 "sub": "https://scim.example.com/Users/44f6142df96bd6ab61e7521d9", 260 "events": { 261 "urn:ietf:params:scim:event:passwordReset": 262 { "id":"44f6142df96bd6ab61e7521d9"}, 263 "https://example.com/scim/event/passwordResetExt": 264 { "resetAttempts":5} 265 } 266 } 268 Figure 1: Example SCIM Password Reset Event 270 The event in the figure above expresses hypothetical password reset 271 event for SCIM [RFC7644]. The JWT consists of: 273 o An "events" claim specifying the hypothetical SCIM URN 274 ("urn:ietf:params:scim:event:passwordReset") for a password reset, 275 and a local schema, "https://example.com/scim/event/ 276 passwordResetExt", that is used to provide additional event 277 information such as the current count of resets. 279 o An "iss" claim, denoting the Event Transmitter. 281 o The "sub" claim specifies the SCIM resource URI that was affected. 283 o The "aud" claim specifies the intended audiences for the event. 284 The syntax of the "aud" claim is defined in Section 4.1.3 285 [RFC7519]. 287 In this example, the SCIM event indicates that a password has been 288 updated and the current password reset count is 5. Notice that the 289 value for "resetAttempts" is actually part of its own JSON object 290 associated with its own event URI attribute. 292 Here is another example JWT Claims Set for a security event token, 293 this one for a Logout Token: 295 { 296 "iss": "https://server.example.com", 297 "sub": "248289761001", 298 "aud": "s6BhdRkqt3", 299 "iat": 1471566154, 300 "jti": "bWJq", 301 "sid": "08a5019c-17e1-4977-8f42-65a12843ea02", 302 "events": { 303 "http://schemas.openid.net/event/backchannel-logout": {} 304 } 305 } 307 Figure 2: Example OpenID Back-Channel Logout Event 309 Note that the above SET has an empty JSON object and uses the JWT 310 registered claims "sub" and "sid" to identify the subject that was 311 logged-out. 313 In the following example JWT Claims Set, a fictional medical service 314 collects consent for medical actions and notifies other parties. The 315 individual for whom consent is identified was originally 316 authenticated via OpenID Connect. In this case, the issuer of the 317 security event is an application rather than the OpenID provider: 319 { 320 "jti": "fb4e75b5411e4e19b6c0fe87950f7749", 321 "iat": 1458496025, 322 "iss": "https://my.examplemed.com", 323 "aud": [ 324 "https://rp.example.com" 325 ], 326 "events": { 327 "https://openid.net/heart/specs/consent.html":{ 328 "iss":"https://connect.example.com", 329 "sub": "248289761001", 330 "consentUri":[ 331 "https://terms.examplemed.com/labdisclosure.html#Agree" 332 ] 333 } 334 } 335 } 337 Figure 3: Example Consent Event 339 In the above example, the attribute "iss" contained within the 340 payload for the event "https://openid.net/heart/specs/consent.html" 341 refers to the issuer of the Security Subject ("sub") rather than the 342 event issuer "https://my.examplemed.com". They are distinct from the 343 top level value of "iss", which always refers to the issuer of the 344 event - a medical consent service that is a relying party to the 345 OpenID Provider. 347 2.1. Core SET Claims 349 The following are claims that are based on [RFC7519] claim 350 definitions and are profiled for use in an event token: 352 jti 353 As defined by Section 4.1.7 [RFC7519] contains a unique identifier 354 for an event. The identifier SHOULD be unique within a particular 355 event feed and MAY be used by clients to track whether a 356 particular event has already been received. This claim is 357 REQUIRED. 359 iss 360 A single valued String containing the URI of the service provider 361 publishing the SET (the issuer). This claim is REQUIRED. Note 362 that when a SET is expressing an event about a Security Subject 363 for which the SET issuer is not the issuer of the Security 364 Subject, the conflict SHALL be resolved by including the Security 365 Subject "iss" value within the event "payload" (see "events" 366 claim). 368 aud 369 The syntax of the claim is as defined in Section 4.1.3 [RFC7519]. 370 This claim contains one or more audience identifiers for the SET. 371 This claim is RECOMMENDED. 373 iat 374 As defined by Section 4.1.6 [RFC7519], a value containing a 375 NumericDate, which represents when the event was issued. Unless 376 otherwise specified, the value SHOULD be interpreted as equivalent 377 to the actual time of the event. This claim is REQUIRED. 379 toe A number whose value is a Numeric Data ( see Section 2 380 [RFC7519]). The value is the date and time in which the event is 381 believed to have occurred in the past or will occur in the future. 382 This claim is RECOMMENDED. Note that some profiles may choose to 383 omit "toe" and convey event time information with the "iat"claim 384 or another claim. 386 sub As defined by Section 4.1.2 [RFC7519], a String or URI value 387 representing the principal or the subject of the SET. This is 388 usually the entity whose "state" was changed. For example, an IP 389 Address was added to a black list. A URI representing a user 390 resource that was modified. A token identifier for a revoked 391 token. If used, the Profiling Specification SHOULD define the 392 content and format semantics for the value. This claim is 393 OPTIONAL, as the principal for any given profile may already be 394 identified without the inclusion of a subject claim. Note that 395 some SET profiles MAY choose to convey event subject information 396 in the event payload (either using the "sub" member name or 397 another name), particularly if the subject information is relative 398 to issuer information that is also conveyed in the event payload, 399 which may be the case for some identity SET profiles. 401 exp As defined by [RFC7519], this claim is time on which the JWT 402 MUST NOT be accepted for processing. In the context of a SET 403 however, this notion does not apply since a SET reflects something 404 that has already been processed and is historical in nature. 405 While some specifications MAY have a need for this claim, its use 406 in general cases is NOT RECOMMENDED. 408 The following are new claims defined by this specification: 410 events 411 The semantics of this claim is to define a set of event statements 412 that each MAY add additional claims to fully describe a single 413 logical event that has occurred (e.g. a state change to a 414 subject). Multiple event statements of the same type SHALL NOT be 415 accepted. The "events" claim SHOULD NOT be used to express 416 multiple logical events. 418 The value of "events" is a JSON object whose members are a set of 419 JSON name/value pairs whose names are URIs representing the event 420 statements being expressed. Event URI values SHOULD be stable 421 values (e.g. a permanent URL for an event specification). For 422 each name present, the corresponding value SHALL be a JSON object. 423 The JSON object MAY be an empty object ("{}"), or it MAY be a JSON 424 object containing data as described by the Profiling 425 Specification. 427 txn 428 An OPTIONAL String value that represents a unique transaction 429 identifier. In cases where multiple SETs are issued based on 430 different event URIs, the transaction identifier MAY be used to 431 correlate SETs to the same originating event or stateful change. 433 2.2. Explicit Typing of SETs 435 This specification registers the "application/secevent+jwt" media 436 type, which can be used to indicate that the content is a SET. SETs 437 MAY include this media type in the "typ" header parameter of the JWT 438 representing the SET to explicitly declare that the JWT is a SET. 439 This MUST be included if the SET could be used in an application 440 context in which it could be confused with other kinds of JWTs. 442 Per the definition of "typ" in Section 4.1.9 of [RFC7515], it is 443 RECOMMENDED that the "application/" prefix be omitted. Therefore, 444 the "typ" value used SHOULD be "secevent+jwt". 446 2.3. Security Event Token Construction 448 A SET is a JWT [RFC7519] that is constructed by building a JSON 449 structure that constitutes an event object which is then used as the 450 body of a JWT. 452 While this specification uses JWT to convey a SET, implementers SHALL 453 NOT use SETs to convey authentication or authorization assertions. 455 The following is an example JWT Claims Set for a security event token 456 (which has been formatted for readability): 458 { 459 "jti": "4d3559ec67504aaba65d40b0363faad8", 460 "iat": 1458496404, 461 "iss": "https://scim.example.com", 462 "aud": [ 463 "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754", 464 "https://scim.example.com/Feeds/5d7604516b1d08641d7676ee7" 465 ], 467 "events": { 468 "urn:ietf:params:scim:event:create": { 469 "ref": 470 "https://scim.example.com/Users/44f6142df96bd6ab61e7521d9", 471 "attributes":["id", "name", "userName", "password", "emails"] 472 } 473 } 474 } 476 Figure 4: Example Event Claims 478 When transmitted, the above JSON body must be converted into a JWT as 479 per [RFC7519]. 481 The following is an example of a SCIM Event expressed as an unsecured 482 JWT. The JOSE Header is: 484 {"typ":"secevent+jwt","alg":"none"} 486 Base64url encoding of the octets of the UTF-8 representation of the 487 JOSE Header yields: 489 eyJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJub25lIn0 491 The example JWT Claims Set is encoded as follows: 493 eyJqdGkiOiI0ZDM1NTllYzY3NTA0YWFiYTY1ZDQwYjAzNjNmYWFkOCIsImlhdCI6MTQ1 494 ODQ5NjQwNCwiaXNzIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tIiwiYXVkIjpbImh0 495 dHBzOi8vc2NpbS5leGFtcGxlLmNvbS9GZWVkcy85OGQ1MjQ2MWZhNWJiYzg3OTU5M2I3 496 NzU0IiwiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tL0ZlZWRzLzVkNzYwNDUxNmIxZDA4 497 NjQxZDc2NzZlZTciXSwiZXZlbnRzIjp7InVybjppZXRmOnBhcmFtczpzY2ltOmV2ZW50 498 OmNyZWF0ZSI6eyJyZWYiOiJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcnMvNDRm 499 NjE0MmRmOTZiZDZhYjYxZTc1MjFkOSIsImF0dHJpYnV0ZXMiOlsiaWQiLCJuYW1lIiwi 500 dXNlck5hbWUiLCJwYXNzd29yZCIsImVtYWlscyJdfX19 501 The encoded JWS signature is the empty string. Concatenating the 502 parts yields: 504 eyJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJub25lIn0. 505 eyJqdGkiOiI0ZDM1NTllYzY3NTA0YWFiYTY1ZDQwYjAzNjNmYWFkOCIsImlhdCI6MTQ1 506 ODQ5NjQwNCwiaXNzIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tIiwiYXVkIjpbImh0 507 dHBzOi8vc2NpbS5leGFtcGxlLmNvbS9GZWVkcy85OGQ1MjQ2MWZhNWJiYzg3OTU5M2I3 508 NzU0IiwiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tL0ZlZWRzLzVkNzYwNDUxNmIxZDA4 509 NjQxZDc2NzZlZTciXSwiZXZlbnRzIjp7InVybjppZXRmOnBhcmFtczpzY2ltOmV2ZW50 510 OmNyZWF0ZSI6eyJyZWYiOiJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcnMvNDRm 511 NjE0MmRmOTZiZDZhYjYxZTc1MjFkOSIsImF0dHJpYnV0ZXMiOlsiaWQiLCJuYW1lIiwi 512 dXNlck5hbWUiLCJwYXNzd29yZCIsImVtYWlscyJdfX19. 514 Figure 5: Example Unsecured Security Event Token 516 For the purpose of a simpler example in Figure 5, an unsecured token 517 was shown. When SETs are not signed or encrypted, the Event Receiver 518 MUST employ other mechanisms such as TLS and HTTP to provide 519 integrity, confidentiality, and issuer validation, as needed by the 520 application. 522 When validation (i.e. auditing), or additional transmission security 523 is required, JWS signing and/or JWE encryption MAY be used. To 524 create and or validate a signed and/or encrypted SET, follow the 525 instructions in Section 7 of [RFC7519]. 527 3. Requirements for SET Profiles 529 Profiling Specifications for SETs define the syntax and semantics of 530 SETs conforming to that SET profile and rules for validating those 531 SETs. The syntax defined by profiling specifications includes what 532 claims and event payload values are used by SETs utilizing the 533 profile. 535 Defining the semantics of the SET contents for SETs utilizing the 536 profile is equally important. Possibly most important is defining 537 the procedures used to validate the SET issuer and to obtain the keys 538 controlled by the issuer that were used for cryptographic operations 539 used in the JWT representing the SET. For instance, some profiles 540 may define an algorithm for retrieving the SET issuer's keys that 541 uses the "iss" claim value as its input. Likewise, if the profile 542 allows (or requires) that the JWT be unsecured, the means by which 543 the integrity of the JWT is ensured MUST be specified. 545 Profiling Specifications MUST define how the event Subject is 546 identified in the SET, as well as how to differentiate between the 547 event Subject's Issuer and the SET Issuer, if applicable. It is NOT 548 RECOMMENDED for Profiling Specifications to use the "sub" claim in 549 cases in which the Subject is not globally unique and has a different 550 Issuer from the SET itself. 552 Profiling Specifications MUST clearly specify the steps that a 553 recipient of a SET utilizing that profile MUST perform to validate 554 that the SET is both syntactically and semantically valid. 556 4. Security Considerations 558 4.1. Confidentiality and Integrity 560 SETs may often contain sensitive information. Therefore, methods for 561 distribution of events SHOULD require the use of a transport-layer 562 security mechanism when distributing events. Parties MUST support 563 TLS 1.2 [RFC5246] and MAY support additional transport-layer 564 mechanisms meeting its security requirements. When using TLS, the 565 client MUST perform a TLS/SSL server certificate check, per 566 [RFC6125]. Implementation security considerations for TLS can be 567 found in "Recommendations for Secure Use of TLS and DTLS" [RFC7525]. 569 Security Events distributed through third-parties or that carry 570 personally identifiable information, SHOULD be encrypted using JWE 571 [RFC7516] or secured for confidentiality by other means. 573 Unless integrity of the JWT is ensured by other means, it MUST be 574 signed using JWS [RFC7515] so that individual events can be 575 authenticated and validated by the Event Receiver. 577 4.2. Delivery 579 This specification does not define a delivery mechanism by itself. 580 In addition to confidentiality and integrity (discussed above), 581 implementers and Profiling Specifications MUST consider the 582 consequences of delivery mechanisms that are not secure and/or not 583 assured. For example, while a SET may be end-to-end secured using 584 JWE encrypted SETs, without TLS there is no assurance that the 585 correct endpoint received the SET and that it could be successfully 586 processed. 588 4.3. Sequencing 590 As defined in this specification, there is no defined way to order 591 multiple SETs in a sequence. Depending on the type and nature of SET 592 event, order may or may not matter. For example, in provisioning, 593 event order is critical -- an object could not be modified before it 594 was created. In other SET types, such as a token revocation, the 595 order of SETs for revoked tokens does not matter. If however, the 596 event was described as a log-in or logged-out status for a user 597 subject, then order becomes important. 599 Profiling Specifications and implementers SHOULD take caution when 600 using timestamps such as "iat" to define order. Distributed systems 601 will have some amount of clock-skew and thus time by itself will not 602 guarantee order. 604 Specifications profiling SET SHOULD define a mechanism for detecting 605 order or sequence of events. For example, the "txn" claim could 606 contain an ordered value (e.g., a counter) that the issuer defines. 608 4.4. Timing Issues 610 When SETs are delivered asynchronously and/or out-of-band with 611 respect to the original action that incurred the security event, it 612 is important to consider that a SET might be delivered to an Event 613 Receiver in advance or well behind the process that caused the event. 614 For example, a user having been required to logout and then log back 615 in again, may cause a logout SET to be issued that may arrive at the 616 same time as the user-agent accesses a web site having just logged- 617 in. If timing is not handled properly, the effect would be to 618 erroneously treat the new user session as logged out. Profiling 619 Specifications SHOULD be careful to anticipate timing and subject 620 selection information. For example, it might be more appropriate to 621 cancel a "session" rather than a "user". Alternatively, the 622 specification could use timestamps that allows new sessions to be 623 started immediately after a stated logout event time. 625 4.5. Distinguishing SETs from ID Tokens 627 Because [RFC7519] states that "all claims that are not understood by 628 implementations MUST be ignored", there is a consideration that a SET 629 token might be confused with ID Token [OpenID.Core] if a SET is 630 mistakenly or intentionally used in a context requiring an ID Token. 631 If a SET could otherwise be interpreted as a valid ID Token (because 632 it includes the required claims for an ID Token and valid issuer and 633 audience claim values for an ID Token) then that SET profile MUST 634 require that the "exp" claim not be present in the SET. Because 635 "exp" is a required claim in ID Tokens, valid ID Token 636 implementations will reject such a SET if presented as if it were an 637 ID Token. 639 Excluding "exp" from SETs that could otherwise be confused with ID 640 Tokens is actually defense in depth. In any OpenID Connect contexts 641 in which an attacker could attempt to substitute a SET for an ID 642 Token, the SET would actually already be rejected as an ID Token 643 because it would not contain the correct "nonce" claim value for the 644 ID Token to be accepted in contexts for which substitution is 645 possible. 647 Note that the use of explicit typing, as described in Section 2.2, 648 will not achieve disambiguation between ID Tokens and SETs, as the ID 649 Token validation rules do not use the "typ" header parameter value. 651 4.6. Distinguishing SETs from Access Tokens 653 OAuth 2.0 [RFC6749] defines access tokens as being opaque. 654 Nonetheless, some implementations implement access tokens as JWTs. 655 Because the structure of these JWTs is implementation-specific, 656 ensuring that a SET cannot be confused with such an access token is 657 therefore likewise, in general, implementation specific. 658 Nonetheless, it is recommended that SET profiles employ the following 659 strategies to prevent possible substitutions of SETs for access 660 tokens in contexts in which that might be possible: 662 o Prohibit use of the "exp" claim, as is done to prevent ID Token 663 confusion. 665 o Where possible, use a separate "aud" claim value to distinguish 666 between the Event Receiver and the protected resource that is the 667 audience of an access token. 669 o Modify access token validation systems to check for the presence 670 of the "events" claim as a means to detect security event tokens. 671 This is particularly useful if the same endpoint may receive both 672 types of tokens. 674 o Employ explicit typing, as described in Section 2.2, and modify 675 access token validation systems to use the "typ" header parameter 676 value. 678 4.7. Distinguishing SETs from other kinds of JWTs 680 JWTs are now being used in application areas beyond the identity 681 applications in which they first appeared. For instance, the Session 682 Initiation Protocol (SIP) Via Header Field [RFC8055] and Personal 683 Assertion Token (PASSporT) [I-D.ietf-stir-passport] specifications 684 both define JWT profiles that use mostly or completely different sets 685 of claims than are used by ID Tokens. If it would otherwise be 686 possible for an attacker to substitute a SET for one of these (or 687 other) kinds of JWTs, then the SET profile must be defined in such a 688 way that any substituted SET will result in its rejection when 689 validated as the intended kind of JWT. 691 The most direct way to prevent confusion is to employ explicit 692 typing, as described in Section 2.2, and modify applicable token 693 validation systems to use the "typ" header parameter value. This 694 approach can be employed for new systems but may not be applicable to 695 existing systems. 697 Another way to ensure that a SET is not confused with another kind of 698 JWT is to have the JWT validation logic reject JWTs containing an 699 "events" claim unless the JWT is intended to be a SET. This approach 700 can be employed for new systems but may not be applicable to existing 701 systems. 703 For many use cases, the simplest way to prevent substitution is 704 requiring that the SET not include claims that are required for the 705 kind of JWT that might be the target of an attack. For example, for 706 [RFC8055], the "sip_callid" claim could be omitted and for 707 [I-D.ietf-stir-passport], the "orig" claim could be omitted. 709 In many contexts, simple measures such as these will accomplish the 710 task, should confusion otherwise even be possible. Note that this 711 topic is being explored in a more general fashion in JSON Web Token 712 Best Current Practices [I-D.sheffer-oauth-jwt-bcp]. The proposed 713 best practices in that draft may also be applicable for particular 714 SET profiles and use cases. 716 5. Privacy Considerations 718 If a SET needs to be retained for audit purposes, JWS MAY be used to 719 provide verification of its authenticity. 721 Event Transmitters SHOULD attempt to specialize feeds so that the 722 content is targeted to the specific business and protocol needs of an 723 Event Receiver. 725 When sharing personally identifiable information or information that 726 is otherwise considered confidential to affected users, Event 727 Transmitters and Receivers MUST have the appropriate legal agreements 728 and user consent or terms of service in place. 730 The propagation of subject identifiers can be perceived as personally 731 identifiable information. Where possible, Event Transmitters and 732 Receivers SHOULD devise approaches that prevent propagation -- for 733 example, the passing of a hash value that requires the Event Receiver 734 to know the subject. 736 6. IANA Considerations 738 6.1. JSON Web Token Claims Registration 740 This specification registers the "events", "toe", and "txn" claims in 741 the IANA "JSON Web Token Claims" registry [IANA.JWT.Claims] 742 established by [RFC7519]. 744 6.1.1. Registry Contents 746 o Claim Name: "events" 747 o Claim Description: Security Event URI 748 o Change Controller: IESG 749 o Specification Document(s): Section 2.1 of [[ this specification ]] 751 o Claim Name: "toe" 752 o Claim Description: Time Of Event 753 o Change Controller: IESG 754 o Specification Document(s): Section 2.1 of [[ this specification ]] 756 o Claim Name: "txn" 757 o Claim Description: Transaction Identifier 758 o Change Controller: IESG 759 o Specification Document(s): Section 2.1 of [[ this specification ]] 761 6.2. Media Type Registration 763 6.2.1. Registry Contents 765 This section registers the "application/secevent+jwt" media type 766 [RFC2046] in the "Media Types" registry [IANA.MediaTypes] in the 767 manner described in [RFC6838], which can be used to indicate that the 768 content is a SET. 770 o Type name: application 771 o Subtype name: secevent+jwt 772 o Required parameters: n/a 773 o Optional parameters: n/a 774 o Encoding considerations: 8bit; A SET is a JWT; JWT values are 775 encoded as a series of base64url-encoded values (some of which may 776 be the empty string) separated by period ('.') characters. 777 o Security considerations: See the Security Considerations section 778 of [[ this specification ]] 779 o Interoperability considerations: n/a 780 o Published specification: Section 2.2 of [[ this specification ]] 781 o Applications that use this media type: TBD 782 o Fragment identifier considerations: n/a 783 o Additional information: 785 Magic number(s): n/a 786 File extension(s): n/a 787 Macintosh file type code(s): n/a 789 o Person & email address to contact for further information: 790 Michael B. Jones, mbj@microsoft.com 791 o Intended usage: COMMON 792 o Restrictions on usage: none 793 o Author: Michael B. Jones, mbj@microsoft.com 794 o Change controller: IESG 795 o Provisional registration? No 797 7. References 799 7.1. Normative References 801 [IANA.JWT.Claims] 802 IANA, "JSON Web Token Claims", 803 . 805 [IANA.MediaTypes] 806 IANA, "Media Types", 807 . 809 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 810 Requirement Levels", BCP 14, RFC 2119, 811 DOI 10.17487/RFC2119, March 1997, 812 . 814 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 815 Resource Identifier (URI): Generic Syntax", STD 66, 816 RFC 3986, DOI 10.17487/RFC3986, January 2005, 817 . 819 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 820 (TLS) Protocol Version 1.2", RFC 5246, 821 DOI 10.17487/RFC5246, August 2008, 822 . 824 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 825 Verification of Domain-Based Application Service Identity 826 within Internet Public Key Infrastructure Using X.509 827 (PKIX) Certificates in the Context of Transport Layer 828 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 829 2011, . 831 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 832 RFC 6749, DOI 10.17487/RFC6749, October 2012, 833 . 835 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 836 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 837 . 839 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 840 "Recommendations for Secure Use of Transport Layer 841 Security (TLS) and Datagram Transport Layer Security 842 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 843 2015, . 845 [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", 846 RFC 7617, DOI 10.17487/RFC7617, September 2015, 847 . 849 7.2. Informative References 851 [I-D.ietf-stir-passport] 852 Wendt, C. and J. Peterson, "Personal Assertion Token 853 (PASSporT)", draft-ietf-stir-passport-11 (work in 854 progress), February 2017. 856 [I-D.sheffer-oauth-jwt-bcp] 857 Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best 858 Current Practices", draft-sheffer-oauth-jwt-bcp-00 (work 859 in progress), June 2017. 861 [OpenID.Core] 862 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 863 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 864 . 866 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 867 Extensions (MIME) Part Two: Media Types", RFC 2046, 868 DOI 10.17487/RFC2046, November 1996, 869 . 871 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 872 Specifications and Registration Procedures", BCP 13, 873 RFC 6838, DOI 10.17487/RFC6838, January 2013, 874 . 876 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 877 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 878 August 2013, . 880 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 881 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 882 2015, . 884 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 885 RFC 7516, DOI 10.17487/RFC7516, May 2015, 886 . 888 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 889 DOI 10.17487/RFC7517, May 2015, 890 . 892 [RFC7644] Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E., 893 and C. Mortimore, "System for Cross-domain Identity 894 Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, 895 September 2015, . 897 [RFC8055] Holmberg, C. and Y. Jiang, "Session Initiation Protocol 898 (SIP) Via Header Field Parameter to Indicate Received 899 Realm", RFC 8055, DOI 10.17487/RFC8055, January 2017, 900 . 902 [saml-core-2.0] 903 Internet2, "Assertions and Protocols for the OASIS 904 Security Assertion Markup Language (SAML) V2.0", March 905 2005. 907 Appendix A. Acknowledgments 909 The editors would like to thank the members of the IETF SCIM working 910 group, which began discussions of provisioning events starting with 911 draft-hunt-scim-notify-00 in 2015. 913 The editors would like to thank the participants in the IETF id-event 914 mailing list and related working groups for their support of this 915 specification. 917 Appendix B. Change Log 919 From the original draft-hunt-idevent-token: 921 Draft 01 - PH - Renamed eventUris to events 923 Draft 00 - PH - First Draft 925 Draft 01 - PH - Fixed some alignment issues with JWT. Remove event 926 type attribute. 928 Draft 02 - PH - Renamed to Security Events, removed questions, 929 clarified examples and intro text, and added security and privacy 930 section. 932 Draft 03 - PH 934 General edit corrections from Sarah Squire 936 Changed "event" term to "SET" 938 Corrected author organization for William Denniss to Google 940 Changed definition of SET to be 2 parts, an envelope and 1 or more 941 payloads. 943 Clarified that the intent is to express a single event with 944 optional extensions only. 946 - mbj - Registered "events" claim, and proof-reading corrections. 948 Draft 04 - PH - 950 o Re-added the "sub" claim with clarifications that any SET type may 951 use it. 953 o Added additional clarification on the use of envelope vs. payload 954 attributes 956 o Added security consideration for event timing. 958 o Switched use of "attribute" to "claim" for consistency. 960 o Revised examples to put "sub" claim back in the top level. 962 o Added clarification that SETs typically do not use "exp". 964 o Added security consideration for distinguishing Access Tokens and 965 SETs. 967 Draft 05 - PH - Fixed find/replace error that resulted in claim being 968 spelled claimc 970 Draft 06 - PH - 972 o Corrected typos 974 o New txn claim 975 o New security considerations Sequencing and Timing Issues 977 Draft 07 - 979 o PH - Moved payload objects to be values of event URI attributes, 980 per discussion. 982 o mbj - Applied terminology consistency and grammar cleanups. 984 Draft 08 - PH - 986 o Added clarification to status of examples 988 o Changed from primary vs. extension to state that multiple events 989 may be expressed, some of which may or may not be considered 990 extensions of others (which is for the subscriber or profiling 991 specifications to determine). 993 o Other editorial changes suggested by Yaron 994 From draft-ietf-secevent-token: 996 Draft 00 - PH - First WG Draft based on draft-hunt-idevent-token 998 Draft 01 - PH - Changes as follows: 1000 o Changed terminology away from pub-sub to transmitter/receiver 1001 based on WG feedback 1003 o Cleaned up/removed some text about extensions (now only used as 1004 example) 1006 o Clarify purpose of spec vs. future profiling specs that define 1007 actual events 1009 Draft 02 - Changes are as follows: 1011 o mbj - Added the Requirements for SET Profiles section. 1013 o mbj - Expanded the Security Considerations section to describe how 1014 to prevent confusion of SETs with ID Tokens, access tokens, and 1015 other kinds of JWTs. 1017 o mbj - Registered the "application/secevent+jwt" media type and 1018 defined how to use it for explicit typing of SETs. 1020 o mbj - Clarified the misleading statement that used to say that a 1021 SET conveys a single security event. 1023 o mbj - Added a note explicitly acknowledging that some SET profiles 1024 may choose to convey event subject information in the event 1025 payload. 1027 o PH - Corrected encoded claim example on page 10. 1029 o mbj - Applied grammar corrections. 1031 Draft 03 - Changes As Follows: 1033 o pjh - Corrected old "subscriber" to "Event Receiver". Added 1034 clarification in definition that Event Receiver is the same as JWT 1035 recipient. 1037 o pjh - Added definition for "toe" (and IANA registration). 1039 o pjh - Removed "nbf" claim. 1041 o pjh - Figure 3, moved "sub" to the events payload next to "iss". 1043 o pjh - Clarified the use of "nonce" in contexts where susbstitution 1044 is possible. 1046 o mbj - Addressed WGLC comments by Nat Sakimura. 1048 o mbj - Addressed WGLC comments by Annabelle Bachman. 1050 o mbj - Addressed WGLC comments by Marius Scurtescu. 1052 Authors' Addresses 1054 Phil Hunt (editor) 1055 Oracle Corporation 1057 Email: phil.hunt@yahoo.com 1059 William Denniss 1060 Google 1062 Email: wdenniss@google.com 1064 Morteza Ansari 1065 Cisco 1067 Email: morteza.ansari@cisco.com 1068 Michael B. Jones 1069 Microsoft 1071 Email: mbj@microsoft.com 1072 URI: http://self-issued.info/