idnits 2.17.1 draft-ietf-secevent-subject-identifiers-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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([JSON], [JWT], [SET]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 11, 2019) is 1873 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'E164' ** Obsolete normative reference: RFC 7159 (ref. 'JSON') (Obsoleted by RFC 8259) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Security Events Working Group A. Backman, Ed. 3 Internet-Draft Amazon 4 Intended status: Standards Track M. Scurtescu 5 Expires: September 12, 2019 Coinbase 6 March 11, 2019 8 Subject Identifiers for Security Event Tokens 9 draft-ietf-secevent-subject-identifiers-03 11 Abstract 13 Security events communicated within Security Event Tokens may support 14 a variety of identifiers to identify the subject and/or other 15 principals related to the event. This specification formalizes the 16 notion of subject identifiers as named sets of well-defined claims 17 describing the subject, a mechanism for representing subject 18 identifiers within a [JSON] object such as a JSON Web Token [JWT] or 19 Security Event Token [SET], and a registry for defining and 20 allocating names for these claim sets. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on September 12, 2019. 39 Copyright Notice 41 Copyright (c) 2019 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 58 3. Subject Identifiers . . . . . . . . . . . . . . . . . . . . . 3 59 3.1. Account Subject Identifier Type . . . . . . . . . . . . . 3 60 3.2. Email Subject Identifier Type . . . . . . . . . . . . . . 4 61 3.2.1. Email Canonicalization . . . . . . . . . . . . . . . 4 62 3.3. Phone Number Subject Identifier Type . . . . . . . . . . 5 63 3.4. Issuer and Subject Subject Identifier Type . . . . . . . 5 64 3.5. Aliases Subject Identifier Type . . . . . . . . . . . . . 5 65 4. Privacy Considerations . . . . . . . . . . . . . . . . . . . 6 66 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 67 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 68 6.1. Security Event Subject Identifier Types Registry . . . . 7 69 6.1.1. Registration Template . . . . . . . . . . . . . . . . 7 70 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 7 71 6.1.3. Guidance for Expert Reviewers . . . . . . . . . . . . 9 72 7. Normative References . . . . . . . . . . . . . . . . . . . . 9 73 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 10 74 Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 77 1. Introduction 79 As described in section 1.2 of [SET], the subject of a security event 80 may take a variety of forms, including but not limited to a JWT 81 principal, an IP address, a URL, etc. Furthermore, even in the case 82 where the subject of an event is more narrowly scoped, there may be 83 multiple ways by which a given subject may be identified. For 84 example, an account may be identified by an opaque identifier, an 85 email address, a phone number, a JWT "iss" claim and "sub" claim, 86 etc., depending on the nature and needs of the transmitter and 87 receiver. Even within the context of a given transmitter and 88 receiver relationship, it may be appropriate to identify different 89 accounts in different ways, for example if some accounts only have 90 email addresses associated with them while others only have phone 91 numbers. Therefore it can be necessary to indicate within a SET the 92 mechanism by which the subject of the security event is being 93 identified. 95 2. Notational Conventions 97 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 98 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 99 document are to be interpreted as described in [RFC2119]. 101 3. Subject Identifiers 103 A Subject Identifier Type is a light-weight schema that describes a 104 set of claims that identifies a subject. Every Subject Identifier 105 Type MUST have a unique name registered in the IANA "Security Event 106 Subject Identifier Types" registry established by Section 6.1. A 107 Subject Identifier Type MAY describe more claims than are strictly 108 necessary to identify a subject, and MAY describe conditions under 109 which those claims are required, optional, or prohibited. 111 A Subject Identifier is a [JSON] object containing a "subject_type" 112 claim whose value is the name of a Subject Identifier Type, and a set 113 of additional "payload claims" which are to be interpreted according 114 to the rules defined by that Subject Identifier Type. Payload claim 115 values MUST match the format specified for the claim by the Subject 116 Identifier Type. A Subject Identifier MUST NOT contain any payload 117 claims prohibited or not described by its Subject Identifier Type, 118 and MUST contain all payload claims required by its Subject 119 Identifier Type. 121 The following Subject Identifier Types are registered in the IANA 122 "Security Event Subject Identifier Types" registry established by 123 Section 6.1. 125 3.1. Account Subject Identifier Type 127 The Account Subject Identifier Type describes a user account at a 128 service provider, identified with an "acct" URI as defined in 129 [RFC7565]. Subject Identifiers of this type MUST contain a "uri" 130 claim whose value is the "acct" URI for the subject. The "uri" claim 131 is REQUIRED and MUST NOT be null or empty. The Account Subject 132 Identifier Type is identified by the name "account". 134 Below is a non-normative example Subject Identifier for the Account 135 Subject Identifier Type: 137 { 138 "subject_type": "account", 139 "uri": "acct:example.user@service.example.com", 140 } 142 Figure 1: Example: Subject Identifier for the Account Subject 143 Identifier Type. 145 3.2. Email Subject Identifier Type 147 The Email Subject Identifier Type describes a principal identified 148 with an email address. Subject Identifiers of this type MUST contain 149 an "email" claim whose value is a string containing the email address 150 of the subject, formatted as an "addr-spec" as defined in 151 Section 3.4.1 of [RFC5322]. The "email" claim is REQUIRED and MUST 152 NOT be null or empty. The value of the "email" claim SHOULD identify 153 a mailbox to which email may be delivered, in accordance with 154 [RFC5321]. The Email Subject Identifier Type is identified by the 155 name "email". 157 Below is a non-normative example Subject Identifier for the Email 158 Subject Identifier Type: 160 { 161 "subject_type": "email", 162 "email": "user@example.com", 163 } 165 Figure 2: Example: Subject Identifier for the Email Subject 166 Identifier Type. 168 3.2.1. Email Canonicalization 170 Many email providers will treat multiple email addresses as 171 equivalent. For example, some providers treat email addresses as 172 case-insensitive, and consider "user@example.com", 173 "User@example.com", and "USER@example.com" as the same email address. 174 This has led users to view these strings as equivalent, driving 175 service providers to implement proprietary email canonicalization 176 algorithms to ensure that email addresses entered by users resolve to 177 the same canonical string. When receiving an Email Subject 178 Identifier, the recipient SHOULD use their implementation's 179 canonicalization algorithm to resolve the email address to the same 180 subject identifier string used in their system. 182 3.3. Phone Number Subject Identifier Type 184 The Phone Number Subject Identifier Type describes a principal 185 identified with a telephone number. Subject Identifiers of this type 186 MUST contain a "phone" claim whose value is a string containing the 187 full telephone number of the subject, including international dialing 188 prefix, formatted according to E.164 [E164]. The "phone" claim is 189 REQUIRED and MUST NOT be null or empty. The Phone Number Subject 190 Identifier Type is identified by the name "phone". 192 Below is a non-normative example Subject Identifier for the Email 193 Subject Identifier Type: 195 { 196 "subject_type": "phone", 197 "phone": "+12065550100", 198 } 200 Figure 3: Example: Subject Identifier for the Phone Number Subject 201 Identifier Type. 203 3.4. Issuer and Subject Subject Identifier Type 205 The Issuer and Subject Subject Identifier Type describes a principal 206 identified with a pair of "iss" and "sub" claims, as defined by 207 [JWT]. These claims MUST follow the formats of the "iss" claim and 208 "sub" claim defined by [JWT], respectively. Both the "iss" claim and 209 the "sub" claim are REQUIRED and MUST NOT be null or empty. The 210 Issuer and Subject Subject Identifier Type is identified by the name 211 "iss-sub". 213 Below is a non-normative example Subject Identifier for the Issuer 214 and Subject Subject Identifier Type: 216 { 217 "subject_type": "iss-sub", 218 "iss": "http://issuer.example.com/", 219 "sub": "145234573", 220 } 222 Figure 4: Example: Subject Identifier for the Issuer and Subject 223 Subject Identifier Type. 225 3.5. Aliases Subject Identifier Type 227 The Aliases Subject Identifier Type describes a subject that is 228 identified with a list of different Subject Identifiers. It is 229 intended for use when a variety of identifiers have been shared with 230 the party that will be interpreting the Subject Identifier, and it is 231 unknown which of those identifiers they will recognize or support. 232 Subject Identifiers of this type MUST contain an "identifiers" claim 233 whose value is a JSON array containing one or more Subject 234 Identifiers. Each Subject Identifier in the array MUST identify the 235 same entity. The "identifiers" claim is REQUIRED and MUST NOT be 236 null or empty. It MAY contain multiple instances of the same Subject 237 Identifier Type (e.g., multiple Email Subject Identifiers), but 238 SHOULD NOT contain exact duplicates. This type is identified by the 239 name "aliases". 241 Below is a non-normative example Subject Identifier for the Aliases 242 Subject Identifier Type: 244 { 245 "subject_type": "aliases", 246 "identifiers": [ 247 { 248 "subject_type": "email", 249 "email": "user@example.com", 250 }, 251 { 252 "subject_type": "phone", 253 "phone": "+12065550100", 254 }, 255 { 256 "subject_type": "email", 257 "email": "user+qualifier@example.com", 258 } 259 ], 260 } 262 Figure 5: Example: Subject Identifier for the Aliases Subject 263 Identifier Type. 265 4. Privacy Considerations 267 There are no privacy considerations. 269 5. Security Considerations 271 There are no security considerations. 273 6. IANA Considerations 274 6.1. Security Event Subject Identifier Types Registry 276 This document defines Subject Identifier Types, for which IANA is 277 asked to create and maintain a new registry titled "Security Event 278 Subject Identifier Types". Initial values for the Security Event 279 Subject Identifier Types registry are given in Section 3. Future 280 assignments are to be made through the Expert Review registration 281 policy [BCP26] and shall follow the template presented in 282 Section 6.1.1. 284 6.1.1. Registration Template 286 Type Name 287 The name of the Subject Identifier Type, as described in 288 Section 3. The name MUST be an ASCII string consisting only of 289 lower-case characters ("a" - "z"), digits ("0" - "9"), and hyphens 290 ("-"), and SHOULD NOT exceed 20 characters in length. 292 Type Description 293 A brief description of the Subject Identifier Type. 295 Change Controller 296 For types defined in documents published by the OpenID Foundation 297 or its working groups, list "OpenID Foundation RISC Working 298 Group". For all other types, list the name of the party 299 responsible for the registration. Contact information such as 300 mailing address, email address, or phone number may also be 301 provided. 303 Defining Document(s) 304 A reference to the document or documents that define the Subject 305 Identifier Type. The definition MUST specify the name, format, 306 and meaning of each claim that may occur within a Subject 307 Identifier of the defined type, as well as whether each claim is 308 optional or required, or the circumstances under which the claim 309 is optional or required. URIs that can be used to retrieve copies 310 of each document SHOULD be included. 312 6.1.2. Initial Registry Contents 314 6.1.2.1. Account Subject Identifier Type 316 o Type Name: "account" 318 o Type Description: Subject identifier based on "acct" URI. 320 o Change Controller: IETF secevent Working Group 321 o Defining Document(s): Section 3 of this document. 323 6.1.2.2. Email Subject Identifier Type 325 o Type Name: "email" 327 o Type Description: Subject identifier based on email address. 329 o Change Controller: IETF secevent Working Group 331 o Defining Document(s): Section 3 of this document. 333 6.1.2.3. Issuer and Subject Subject Identifier Type 335 o Type Name: "iss-sub" 337 o Type Description: Subject identifier based on an issuer and 338 subject. 340 o Change Controller: IETF secevent Working Group 342 o Defining Document(s): Section 3 of this document. 344 6.1.2.4. Phone Number Subject Identifier Type 346 o Type Name: "phone" 348 o Type Description: Subject identifier based on an phone number. 350 o Change Controller: IETF secevent Working Group 352 o Defining Document(s): Section 3 of this document. 354 6.1.2.5. Aliases Subject Identifier Type 356 o Type Name: "aliases" 358 o Type Description: Subject identifier that groups together multiple 359 different subject identifiers for the same subject. 361 o Change Controller: IETF secevent Working Group 363 o Defining Document(s): Section 3 of this document. 365 6.1.3. Guidance for Expert Reviewers 367 The Expert Reviewer is expected to review the documentation 368 referenced in a registration request to verify its completeness. The 369 Expert Reviewer must base their decision to accept or reject the 370 request on a fair and impartial assessment of the request. If the 371 Expert Reviewer has a conflict of interest, such as being an author 372 of a defining document referenced by the request, they must recuse 373 themselves from the approval process for that request. In the case 374 where a request is rejected, the Expert Reviewer should provide the 375 requesting party with a written statement expressing the reason for 376 rejection, and be prepared to cite any sources of information that 377 went into that decision. 379 Subject Identifier Types need not be generally applicable and may be 380 highly specific to a particular domain; it is expected that types may 381 be registered for niche or industry-specific use cases. The Expert 382 Reviewer should focus on whether the type is thoroughly documented, 383 and whether its registration will promote or harm interoperability. 384 In most cases, the Expert Reviewer should not approve a request if 385 the registration would contribute to confusion, or amount to a 386 synonym for an existing type. 388 7. Normative References 390 [BCP26] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 391 Writing an IANA Considerations Section in RFCs", BCP 26, 392 RFC 8126, DOI 10.17487/RFC8126, June 2017, 393 . 395 [E164] International Telecommunication Union, "The international 396 public telecommunication numbering plan", 2010, 397 . 399 [JSON] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 400 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 401 2014, . 403 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 404 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 405 . 407 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 408 Requirement Levels", BCP 14, RFC 2119, 409 DOI 10.17487/RFC2119, March 1997, 410 . 412 [RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, 413 DOI 10.17487/RFC5321, October 2008, 414 . 416 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 417 DOI 10.17487/RFC5322, October 2008, 418 . 420 [RFC7565] Saint-Andre, P., "The 'acct' URI Scheme", RFC 7565, 421 DOI 10.17487/RFC7565, May 2015, 422 . 424 [SET] Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari, 425 "Security Event Token (SET)", RFC 8417, 426 DOI 10.17487/RFC8417, July 2018, 427 . 429 Acknowledgements 431 This document is based on work developed within the OpenID RISC 432 Working Group. The authors would like to thank the members of this 433 group for their hard work and contributions. 435 Change Log 437 (This section to be removed by the RFC Editor before publication as 438 an RFC.) 440 Draft 00 - AB - First draft 442 Draft 01 - AB: 444 o Added reference to RFC 5322 for format of "email" claim. 446 o Renamed "iss_sub" type to "iss-sub". 448 o Renamed "id_token_claims" type to "id-token-claims". 450 o Added text specifying the nature of the subjects described by each 451 type. 453 Draft 02 - AB: 455 o Corrected format of phone numbers in examples. 457 o Updated author info. 459 Draft 03 - AB: 461 o Added "account" type for "acct" URIs. 463 o Replaced "id-token-claims" type with "aliases" type. 465 o Added email canonicalization guidance. 467 o Updated semantics for "email", "phone", and "iss-sub" types. 469 Authors' Addresses 471 Annabelle Backman (editor) 472 Amazon 474 Email: richanna@amazon.com 476 Marius Scurtescu 477 Coinbase 479 Email: marius.scurtescu@coinbase.com