Security Events Working Group A. Backman Internet-Draft Amazon Intended status: Standards Track M. Scurtescu Expires: January 19, 2019 Google July 18, 2018 Subject Identifiers for Security Event Tokens draft-ietf-secevent-subject-identifiers-00 Abstract Security events communicated within Security Event Tokens may support a variety of identifiers to identify the subject and/or other principals related to the event. This specification formalizes the notion of subject identifiers as named sets of well-defined claims describing the subject, a mechanism for representing subject identifiers within a [JSON] object such as a JSON Web Token [JWT] or Security Event Token [SET], and a registry for defining and allocating names for these claim sets. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on January 19, 2019. Copyright Notice Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect Backman & Scurtescu Expires January 19, 2019 [Page 1] Internet-Draft secevent-subject-identifiers July 2018 to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 3. Subject Identifiers . . . . . . . . . . . . . . . . . . . . . 3 3.1. Email Subject Identifier Type . . . . . . . . . . . . . . 3 3.2. Phone Number Subject Identifier Type . . . . . . . . . . 4 3.3. Issuer and Subject Subject Identifier Type . . . . . . . 4 3.4. ID Token Claims Subject Identifier Type . . . . . . . . . 5 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 4.1. Security Event Subject Identifier Types Registry . . . . 5 4.1.1. Registration Template . . . . . . . . . . . . . . . . 6 4.1.2. Initial Registry Contents . . . . . . . . . . . . . . 6 4.1.3. Guidance for Expert Reviewers . . . . . . . . . . . . 7 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 8 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 7. Normative References . . . . . . . . . . . . . . . . . . . . 8 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 9 Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 1. Introduction As described in section 1.2 of [SET], the subject of a security event may take a variety of forms, including but not limited to a JWT principal, an IP address, a URL, etc. Furthermore, even in the case where the subject of an event is more narrowly scoped, there may be multiple ways by which a given subject may be identified. For example, an account may be identified by an opaque identifier, an email address, a phone number, a JWT "iss" claim and "sub" claim, etc., depending on the nature and needs of the transmitter and receiver. Even within the context of a given transmitter and receiver relationship, it may be appropriate to identify different accounts in different ways, for example if some accounts only have email addresses associated with them while others only have phone numbers. Therefore it can be necessary to indicate within a SET the mechanism by which the subject of the security event is being identified. Backman & Scurtescu Expires January 19, 2019 [Page 2] Internet-Draft secevent-subject-identifiers July 2018 2. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 3. Subject Identifiers A Subject Identifier Type is a light-weight schema that describes a set of claims that identifies a subject. Every Subject Identifier Type MUST have a unique name registered in the IANA "Security Event Subject Identifier Types" registry established by Section 4.1. A Subject Identifier Type MAY describe more claims than are strictly necessary to uniquely identify a subject, and MAY describe conditions under which those claims are required, optional, or prohibited. A Subject Identifier is a [JSON] object containing a "subject_type" claim whose value is the unique name of a Subject Identifier Type, and a set of additional "payload claims" which are to be interpreted according to the rules defined by that Subject Identifier Type. Payload claim values MUST match the format specified for the claim by the Subject Identifier Type. A Subject Identifier MUST NOT contain any payload claims prohibited or not described by its Subject Identifier Type, and MUST contain all payload claims required by its Subject Identifier Type. The following Subject Identifier Types are registered in the IANA "Security Event Subject Identifier Types" registry established by Section 4.1. 3.1. Email Subject Identifier Type The Email Subject Identifier Type describes a subject by email address. Subject Identifiers of this type MUST contain an "email" claim whose value is a string containing the email address of the subject. The "email" claim MUST NOT be null or empty. The Email Subject Identifier Type is identified by the name "email". Below is a non-normative example Subject Identifier for the Email Subject Identifier Type: { "subject_type": "email", "email": "user@example.com", } Figure 1: Example: Subject Identifier for the Email Subject Identifier Type. Backman & Scurtescu Expires January 19, 2019 [Page 3] Internet-Draft secevent-subject-identifiers July 2018 3.2. Phone Number Subject Identifier Type The Phone Number Subject Identifier Type describes a subject by telephone number. Subject Identifiers of this type MUST contain a "phone" claim whose value is a string containing the full telephone number of the subject, including international dialing prefix, formatted according to E.164 [E164]. The "phone" claim MUST NOT be null or empty. The Phone Number Subject Identifier Type is identified by the name "phone". Below is a non-normative example Subject Identifier for the Email Subject Identifier Type: { "subject_type": "phone", "phone": "+1 (206) 555-0100", } Figure 2: Example: Subject Identifier for the Phone Number Subject Identifier Type. 3.3. Issuer and Subject Subject Identifier Type The Issuer and Subject Subject Identifier Type describes a subject by an issuer and a subject. Subject Identifiers of this type MUST contain an "iss" claim whose value identifies the issuer, and a "sub" claim whose value identifies the subject with respect to the issuer. These claims MUST follow the formats of the "iss" claim and "sub" claim defined by [JWT], respectively. Both the "iss" claim and the "sub" claim MUST NOT be null or empty. The Issuer and Subject Subject Identifier Type is identified by the name "iss_sub". Below is a non-normative example Subject Identifier for the Issuer and Subject Subject Identifier Type: { "subject_type": "iss_sub", "iss": "http://issuer.example.com/", "sub": "145234573", } Figure 3: Example: Subject Identifier for the Issuer and Subject Subject Identifier Type. Backman & Scurtescu Expires January 19, 2019 [Page 4] Internet-Draft secevent-subject-identifiers July 2018 3.4. ID Token Claims Subject Identifier Type The ID Token Claims Subject Identifier Type describes a subject by a subset of the claims from an ID token. Subject Identifiers of this type MUST contain at least one of the following claims: email An "email" claim, as defined in [IDTOKEN]. phone_number A "phone_number" claim, as defined in [IDTOKEN]. sub A "sub" claim, as defined in [RFC7519]. If the Subject Identifier contains a "sub" claim, it MUST also contain an "iss" claim, as defined in [RFC7519]. The ID Token Claims Subject Identifier Type is identified by the name "id_token_claims". Below is a non-normative example Subject Identifier for the ID Token Claims Subject Identifier Type: { "subject_type": "id_token_claims", "iss": "http://issuer.example.com/", "sub": "145234573", "email": "user@example.com", } Figure 4: Example: Subject Identifier for the ID Token Claims Subject Identifier Type. 4. IANA Considerations 4.1. Security Event Subject Identifier Types Registry This document defines Subject Identifier Types, for which IANA is asked to create and maintain a new registry titled "Security Event Subject Identifier Types". Initial values for the Security Event Subject Identifier Types registry are given in Section 3. Future assignments are to be made through the Expert Review registration policy [BCP26] and shall follow the template presented in Section 4.1.1. Backman & Scurtescu Expires January 19, 2019 [Page 5] Internet-Draft secevent-subject-identifiers July 2018 4.1.1. Registration Template Type Name The name of the Subject Identifier Type, as described in Section 3. The name MUST be an ASCII string consisting only of lower-case characters ("a" - "z"), digits ("0" - "9"), and hyphens ("-"), and SHOULD NOT exceed 20 characters in length. Type Description A brief description of the Subject Identifier Type. Change Controller For types defined in documents published by the OpenID Foundation or its working groups, list "OpenID Foundation RISC Working Group". For all other types, list the name of the party responsible for the registration. Contact information such as mailing address, email address, or phone number may also be provided. Defining Document(s) A reference to the document or documents that define the Subject Identifier Type. The definition MUST specify the name, format, and meaning of each claim that may occur within a Subject Identifier of the defined type, as well as whether each claim is optional or required, or the circumstances under which the claim is optional or required. URIs that can be used to retrieve copies of each document SHOULD be included. 4.1.2. Initial Registry Contents 4.1.2.1. Email Subject Identifier Type o Type Name: "email" o Type Description: Subject identifier based on email address. o Change Controller: IETF secevent Working Group o Defining Document(s): Section 3 of this document. 4.1.2.2. ID Token Claims Subject Identifier Type o Type Name: "id_token_claims" o Type Description: Subject identifier based on OpenID Connect ID Token claims. o Change Controller: IETF secevent Working Group Backman & Scurtescu Expires January 19, 2019 [Page 6] Internet-Draft secevent-subject-identifiers July 2018 o Defining Document(s): Section 3 of this document. 4.1.2.3. Issuer and Subject Subject Identifier Type o Type Name: "iss_sub" o Type Description: Subject identifier based on an issuer and subject. o Change Controller: IETF secevent Working Group o Defining Document(s): Section 3 of this document. 4.1.2.4. Phone Number Subject Identifier Type o Type Name: "phone" o Type Description: Subject identifier based on an phone number. o Change Controller: IETF secevent Working Group o Defining Document(s): Section 3 of this document. 4.1.3. Guidance for Expert Reviewers The Expert Reviewer is expected to review the documentation referenced in a registration request to verify its completeness. The Expert Reviewer must base their decision to accept or reject the request on a fair and impartial assessment of the request. If the Expert Reviewer has a conflict of interest, such as being an author of a defining document referenced by the request, they must recuse themselves from the approval process for that request. In the case where a request is rejected, the Expert Reviewer should provide the requesting party with a written statement expressing the reason for rejection, and be prepared to cite any sources of information that went into that decision. Subject Identifier Types need not be generally applicable and may be highly specific to a particular domain; it is expected that types may be registered for niche or industry-specific use cases. The Expert Reviewer should focus on whether the type is thoroughly documented, and whether its registration will promote or harm interoperability. In most cases, the Expert Reviewer should not approve a request if the registration would contribute to confusion, or amount to a synonym for an existing type. Backman & Scurtescu Expires January 19, 2019 [Page 7] Internet-Draft secevent-subject-identifiers July 2018 5. Privacy Considerations There are no privacy considerations. 6. Security Considerations There are no security considerations. 7. Normative References [BCP26] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, . [E164] International Telecommunication Union, "The international public telecommunication numbering plan", 2010, . [IDTOKEN] Sakamura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0 - ID Token", April 2017, . [JSON] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014, . [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, . [SET] Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari, "Security Event Token (SET)", RFC 8417, DOI 10.17487/RFC8417, July 2018, . Backman & Scurtescu Expires January 19, 2019 [Page 8] Internet-Draft secevent-subject-identifiers July 2018 Acknowledgements This document is based on work developed within the OpenID RISC Working Group. The authors would like to thank the members of this group for their hard work and contributions. Change Log (This section to be removed by the RFC Editor before publication as an RFC.) Draft 00 - AB - First draft Authors' Addresses Annabelle Backman Amazon Email: richanna@amazon.com Marius Scurtescu Google Email: mscurtescu@google.com Backman & Scurtescu Expires January 19, 2019 [Page 9]