idnits 2.17.1 draft-ietf-secevent-subject-identifiers-02.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 (October 23, 2018) is 2011 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' -- Possible downref: Non-RFC (?) normative reference: ref. 'IDTOKEN' ** Obsolete normative reference: RFC 7159 (ref. 'JSON') (Obsoleted by RFC 8259) -- Duplicate reference: RFC7519, mentioned in 'RFC7519', was also mentioned in 'JWT'. Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 4 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: April 26, 2019 Coinbase 6 October 23, 2018 8 Subject Identifiers for Security Event Tokens 9 draft-ietf-secevent-subject-identifiers-02 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 April 26, 2019. 39 Copyright Notice 41 Copyright (c) 2018 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. Email Subject Identifier Type . . . . . . . . . . . . . . 3 60 3.2. Phone Number Subject Identifier Type . . . . . . . . . . 4 61 3.3. Issuer and Subject Subject Identifier Type . . . . . . . 4 62 3.4. ID Token Claims Subject Identifier Type . . . . . . . . . 5 63 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 64 4.1. Security Event Subject Identifier Types Registry . . . . 6 65 4.1.1. Registration Template . . . . . . . . . . . . . . . . 6 66 4.1.2. Initial Registry Contents . . . . . . . . . . . . . . 7 67 4.1.3. Guidance for Expert Reviewers . . . . . . . . . . . . 8 68 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 8 69 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 70 7. Normative References . . . . . . . . . . . . . . . . . . . . 8 71 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 9 72 Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 73 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 75 1. Introduction 77 As described in section 1.2 of [SET], the subject of a security event 78 may take a variety of forms, including but not limited to a JWT 79 principal, an IP address, a URL, etc. Furthermore, even in the case 80 where the subject of an event is more narrowly scoped, there may be 81 multiple ways by which a given subject may be identified. For 82 example, an account may be identified by an opaque identifier, an 83 email address, a phone number, a JWT "iss" claim and "sub" claim, 84 etc., depending on the nature and needs of the transmitter and 85 receiver. Even within the context of a given transmitter and 86 receiver relationship, it may be appropriate to identify different 87 accounts in different ways, for example if some accounts only have 88 email addresses associated with them while others only have phone 89 numbers. Therefore it can be necessary to indicate within a SET the 90 mechanism by which the subject of the security event is being 91 identified. 93 2. Notational Conventions 95 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 96 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 97 document are to be interpreted as described in [RFC2119]. 99 3. Subject Identifiers 101 A Subject Identifier Type is a light-weight schema that describes a 102 set of claims that identifies a subject. Every Subject Identifier 103 Type MUST have a unique name registered in the IANA "Security Event 104 Subject Identifier Types" registry established by Section 4.1. A 105 Subject Identifier Type MAY describe more claims than are strictly 106 necessary to uniquely identify a subject, and MAY describe conditions 107 under which those claims are required, optional, or prohibited. 109 A Subject Identifier is a [JSON] object containing a "subject_type" 110 claim whose value is the unique name of a Subject Identifier Type, 111 and a set of additional "payload claims" which are to be interpreted 112 according to the rules defined by that Subject Identifier Type. 113 Payload claim values MUST match the format specified for the claim by 114 the Subject Identifier Type. A Subject Identifier MUST NOT contain 115 any payload claims prohibited or not described by its Subject 116 Identifier Type, and MUST contain all payload claims required by its 117 Subject Identifier Type. 119 The following Subject Identifier Types are registered in the IANA 120 "Security Event Subject Identifier Types" registry established by 121 Section 4.1. 123 3.1. Email Subject Identifier Type 125 The Email Subject Identifier Type describes a subject that is a user 126 account associated with an email address. Subject Identifiers of 127 this type MUST contain an "email" claim whose value is a string 128 containing the email address of the subject, formatted as an "addr- 129 spec" as defined in Section 3.4.1 of [RFC5322]. The "email" claim is 130 REQUIRED and MUST NOT be null or empty. The Email Subject Identifier 131 Type is identified by the name "email". 133 Below is a non-normative example Subject Identifier for the Email 134 Subject Identifier Type: 136 { 137 "subject_type": "email", 138 "email": "user@example.com", 139 } 141 Figure 1: Example: Subject Identifier for the Email Subject 142 Identifier Type. 144 3.2. Phone Number Subject Identifier Type 146 The Phone Number Subject Identifier Type describes a subject that is 147 a user account associated with a telephone number. Subject 148 Identifiers of this type MUST contain a "phone" claim whose value is 149 a string containing the full telephone number of the subject, 150 including international dialing prefix, formatted according to E.164 151 [E164]. The "phone" claim is REQUIRED and MUST NOT be null or empty. 152 The Phone Number Subject Identifier Type is identified by the name 153 "phone". 155 Below is a non-normative example Subject Identifier for the Email 156 Subject Identifier Type: 158 { 159 "subject_type": "phone", 160 "phone": "+12065550100", 161 } 163 Figure 2: Example: Subject Identifier for the Phone Number Subject 164 Identifier Type. 166 3.3. Issuer and Subject Subject Identifier Type 168 The Issuer and Subject Subject Identifier Type describes a subject 169 that is an account identified by a pair of "iss" and "sub" claims, as 170 defined by [JWT]. These claims MUST follow the formats of the "iss" 171 claim and "sub" claim defined by [JWT], respectively. Both the "iss" 172 claim and the "sub" claim are REQUIRED and MUST NOT be null or empty. 173 The Issuer and Subject Subject Identifier Type is identified by the 174 name "iss-sub". 176 Below is a non-normative example Subject Identifier for the Issuer 177 and Subject Subject Identifier Type: 179 { 180 "subject_type": "iss-sub", 181 "iss": "http://issuer.example.com/", 182 "sub": "145234573", 183 } 185 Figure 3: Example: Subject Identifier for the Issuer and Subject 186 Subject Identifier Type. 188 3.4. ID Token Claims Subject Identifier Type 190 The ID Token Claims Subject Identifier Type describes a subject that 191 was the subject of a previously issued ID Token [IDTOKEN]. It is 192 intended for use when a variety of identifiers have been shared with 193 the party that will be interpreting the Subject Identifier, and it is 194 unknown which of those identifiers they require. This type is 195 identified by the name "id-token-claims". 197 Subject Identifiers of this type MUST contain at least one of the 198 following claims: 200 email 201 An "email" claim, as defined in [IDTOKEN]. If present, the value 202 of this claim MUST NOT be null or empty. 204 phone_number 205 A "phone_number" claim, as defined in [IDTOKEN]. If present, the 206 value of this claim MUST NOT be null or empty. 208 sub 209 A "sub" claim, as defined in [RFC7519]. If present, the value of 210 this claim MUST NOT be null or empty. 212 iss 213 An "iss" claim, as defined in [RFC7519]. This claim is OPTIONAL, 214 unless a "sub" claim in present, in which case it is REQUIRED. If 215 present, its value MUST NOT be null or empty. 217 At least one of "email", "phone_number", or "sub" MUST be present. 219 Below is a non-normative example Subject Identifier for the ID Token 220 Claims Subject Identifier Type: 222 { 223 "subject_type": "id-token-claims", 224 "iss": "http://issuer.example.com/", 225 "sub": "145234573", 226 "email": "user@example.com", 227 } 229 Figure 4: Example: Subject Identifier for the ID Token Claims Subject 230 Identifier Type. 232 4. IANA Considerations 234 4.1. Security Event Subject Identifier Types Registry 236 This document defines Subject Identifier Types, for which IANA is 237 asked to create and maintain a new registry titled "Security Event 238 Subject Identifier Types". Initial values for the Security Event 239 Subject Identifier Types registry are given in Section 3. Future 240 assignments are to be made through the Expert Review registration 241 policy [BCP26] and shall follow the template presented in 242 Section 4.1.1. 244 4.1.1. Registration Template 246 Type Name 247 The name of the Subject Identifier Type, as described in 248 Section 3. The name MUST be an ASCII string consisting only of 249 lower-case characters ("a" - "z"), digits ("0" - "9"), and hyphens 250 ("-"), and SHOULD NOT exceed 20 characters in length. 252 Type Description 253 A brief description of the Subject Identifier Type. 255 Change Controller 256 For types defined in documents published by the OpenID Foundation 257 or its working groups, list "OpenID Foundation RISC Working 258 Group". For all other types, list the name of the party 259 responsible for the registration. Contact information such as 260 mailing address, email address, or phone number may also be 261 provided. 263 Defining Document(s) 264 A reference to the document or documents that define the Subject 265 Identifier Type. The definition MUST specify the name, format, 266 and meaning of each claim that may occur within a Subject 267 Identifier of the defined type, as well as whether each claim is 268 optional or required, or the circumstances under which the claim 269 is optional or required. URIs that can be used to retrieve copies 270 of each document SHOULD be included. 272 4.1.2. Initial Registry Contents 274 4.1.2.1. Email Subject Identifier Type 276 o Type Name: "email" 278 o Type Description: Subject identifier based on email address. 280 o Change Controller: IETF secevent Working Group 282 o Defining Document(s): Section 3 of this document. 284 4.1.2.2. ID Token Claims Subject Identifier Type 286 o Type Name: "id-token-claims" 288 o Type Description: Subject identifier based on OpenID Connect ID 289 Token claims. 291 o Change Controller: IETF secevent Working Group 293 o Defining Document(s): Section 3 of this document. 295 4.1.2.3. Issuer and Subject Subject Identifier Type 297 o Type Name: "iss-sub" 299 o Type Description: Subject identifier based on an issuer and 300 subject. 302 o Change Controller: IETF secevent Working Group 304 o Defining Document(s): Section 3 of this document. 306 4.1.2.4. Phone Number Subject Identifier Type 308 o Type Name: "phone" 310 o Type Description: Subject identifier based on an phone number. 312 o Change Controller: IETF secevent Working Group 314 o Defining Document(s): Section 3 of this document. 316 4.1.3. Guidance for Expert Reviewers 318 The Expert Reviewer is expected to review the documentation 319 referenced in a registration request to verify its completeness. The 320 Expert Reviewer must base their decision to accept or reject the 321 request on a fair and impartial assessment of the request. If the 322 Expert Reviewer has a conflict of interest, such as being an author 323 of a defining document referenced by the request, they must recuse 324 themselves from the approval process for that request. In the case 325 where a request is rejected, the Expert Reviewer should provide the 326 requesting party with a written statement expressing the reason for 327 rejection, and be prepared to cite any sources of information that 328 went into that decision. 330 Subject Identifier Types need not be generally applicable and may be 331 highly specific to a particular domain; it is expected that types may 332 be registered for niche or industry-specific use cases. The Expert 333 Reviewer should focus on whether the type is thoroughly documented, 334 and whether its registration will promote or harm interoperability. 335 In most cases, the Expert Reviewer should not approve a request if 336 the registration would contribute to confusion, or amount to a 337 synonym for an existing type. 339 5. Privacy Considerations 341 There are no privacy considerations. 343 6. Security Considerations 345 There are no security considerations. 347 7. Normative References 349 [BCP26] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 350 Writing an IANA Considerations Section in RFCs", BCP 26, 351 RFC 8126, DOI 10.17487/RFC8126, June 2017, 352 . 354 [E164] International Telecommunication Union, "The international 355 public telecommunication numbering plan", 2010, 356 . 358 [IDTOKEN] Sakamura, N., Bradley, J., Jones, M., de Medeiros, B., and 359 C. Mortimore, "OpenID Connect Core 1.0 - ID Token", April 360 2017, . 363 [JSON] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 364 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 365 2014, . 367 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 368 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 369 . 371 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 372 Requirement Levels", BCP 14, RFC 2119, 373 DOI 10.17487/RFC2119, March 1997, 374 . 376 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 377 DOI 10.17487/RFC5322, October 2008, 378 . 380 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 381 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 382 . 384 [SET] Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari, 385 "Security Event Token (SET)", RFC 8417, 386 DOI 10.17487/RFC8417, July 2018, 387 . 389 Acknowledgements 391 This document is based on work developed within the OpenID RISC 392 Working Group. The authors would like to thank the members of this 393 group for their hard work and contributions. 395 Change Log 397 (This section to be removed by the RFC Editor before publication as 398 an RFC.) 400 Draft 00 - AB - First draft 402 Draft 01 - AB: * Added reference to RFC 5322 for format of "email" 403 claim. * Renamed "iss_sub" type to "iss-sub". * Renamed 404 "id_token_claims" type to "id-token-claims". * Added text specifying 405 the nature of the subjects described by each type. 407 Draft 02 - AB: * Corrected format of phone numbers in examples. * 408 Updated author info. 410 Authors' Addresses 412 Annabelle Backman (editor) 413 Amazon 415 Email: richanna@amazon.com 417 Marius Scurtescu 418 Coinbase 420 Email: marius.scurtescu@coinbase.com