[Docs] [txt|pdf|xml|html] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: (draft-backman-secevent-subject-identifiers) 00 01 02 03 04 05

Security Events Working Group                            A. Backman, Ed.
Internet-Draft                                                    Amazon
Intended status: Standards Track                            M. Scurtescu
Expires: September 12, 2019                                     Coinbase
                                                          March 11, 2019


             Subject Identifiers for Security Event Tokens
               draft-ietf-secevent-subject-identifiers-03

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 September 12, 2019.

Copyright Notice

   Copyright (c) 2019 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 September 12, 2019               [Page 1]


Internet-Draft        secevent-subject-identifiers            March 2019


   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.  Account Subject Identifier Type . . . . . . . . . . . . .   3
     3.2.  Email Subject Identifier Type . . . . . . . . . . . . . .   4
       3.2.1.  Email Canonicalization  . . . . . . . . . . . . . . .   4
     3.3.  Phone Number Subject Identifier Type  . . . . . . . . . .   5
     3.4.  Issuer and Subject Subject Identifier Type  . . . . . . .   5
     3.5.  Aliases Subject Identifier Type . . . . . . . . . . . . .   5
   4.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .   6
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .   6
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   6
     6.1.  Security Event Subject Identifier Types Registry  . . . .   7
       6.1.1.  Registration Template . . . . . . . . . . . . . . . .   7
       6.1.2.  Initial Registry Contents . . . . . . . . . . . . . .   7
       6.1.3.  Guidance for Expert Reviewers . . . . . . . . . . . .   9
   7.  Normative References  . . . . . . . . . . . . . . . . . . . .   9
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  10
   Change Log  . . . . . . . . . . . . . . . . . . . . . . . . . . .  10
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  11

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 September 12, 2019               [Page 2]


Internet-Draft        secevent-subject-identifiers            March 2019


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 6.1.  A
   Subject Identifier Type MAY describe more claims than are strictly
   necessary to 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 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 6.1.

3.1.  Account Subject Identifier Type

   The Account Subject Identifier Type describes a user account at a
   service provider, identified with an "acct" URI as defined in
   [RFC7565].  Subject Identifiers of this type MUST contain a "uri"
   claim whose value is the "acct" URI for the subject.  The "uri" claim
   is REQUIRED and MUST NOT be null or empty.  The Account Subject
   Identifier Type is identified by the name "account".

   Below is a non-normative example Subject Identifier for the Account
   Subject Identifier Type:










Backman & Scurtescu    Expires September 12, 2019               [Page 3]


Internet-Draft        secevent-subject-identifiers            March 2019


   {
     "subject_type": "account",
     "uri": "acct:example.user@service.example.com",
   }

       Figure 1: Example: Subject Identifier for the Account Subject
                             Identifier Type.

3.2.  Email Subject Identifier Type

   The Email Subject Identifier Type describes a principal identified
   with an email address.  Subject Identifiers of this type MUST contain
   an "email" claim whose value is a string containing the email address
   of the subject, formatted as an "addr-spec" as defined in
   Section 3.4.1 of [RFC5322].  The "email" claim is REQUIRED and MUST
   NOT be null or empty.  The value of the "email" claim SHOULD identify
   a mailbox to which email may be delivered, in accordance with
   [RFC5321].  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 2: Example: Subject Identifier for the Email Subject
                             Identifier Type.

3.2.1.  Email Canonicalization

   Many email providers will treat multiple email addresses as
   equivalent.  For example, some providers treat email addresses as
   case-insensitive, and consider "user@example.com",
   "User@example.com", and "USER@example.com" as the same email address.
   This has led users to view these strings as equivalent, driving
   service providers to implement proprietary email canonicalization
   algorithms to ensure that email addresses entered by users resolve to
   the same canonical string.  When receiving an Email Subject
   Identifier, the recipient SHOULD use their implementation's
   canonicalization algorithm to resolve the email address to the same
   subject identifier string used in their system.







Backman & Scurtescu    Expires September 12, 2019               [Page 4]


Internet-Draft        secevent-subject-identifiers            March 2019


3.3.  Phone Number Subject Identifier Type

   The Phone Number Subject Identifier Type describes a principal
   identified with a 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 is
   REQUIRED and 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": "+12065550100",
   }

    Figure 3: Example: Subject Identifier for the Phone Number Subject
                             Identifier Type.

3.4.  Issuer and Subject Subject Identifier Type

   The Issuer and Subject Subject Identifier Type describes a principal
   identified with a pair of "iss" and "sub" claims, as defined by
   [JWT].  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 are REQUIRED and 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 4: Example: Subject Identifier for the Issuer and Subject
                         Subject Identifier Type.

3.5.  Aliases Subject Identifier Type

   The Aliases Subject Identifier Type describes a subject that is
   identified with a list of different Subject Identifiers.  It is
   intended for use when a variety of identifiers have been shared with



Backman & Scurtescu    Expires September 12, 2019               [Page 5]


Internet-Draft        secevent-subject-identifiers            March 2019


   the party that will be interpreting the Subject Identifier, and it is
   unknown which of those identifiers they will recognize or support.
   Subject Identifiers of this type MUST contain an "identifiers" claim
   whose value is a JSON array containing one or more Subject
   Identifiers.  Each Subject Identifier in the array MUST identify the
   same entity.  The "identifiers" claim is REQUIRED and MUST NOT be
   null or empty.  It MAY contain multiple instances of the same Subject
   Identifier Type (e.g., multiple Email Subject Identifiers), but
   SHOULD NOT contain exact duplicates.  This type is identified by the
   name "aliases".

   Below is a non-normative example Subject Identifier for the Aliases
   Subject Identifier Type:

   {
     "subject_type": "aliases",
     "identifiers": [
       {
         "subject_type": "email",
         "email": "user@example.com",
       },
       {
         "subject_type": "phone",
         "phone": "+12065550100",
       },
       {
         "subject_type": "email",
         "email": "user+qualifier@example.com",
       }
     ],
   }

       Figure 5: Example: Subject Identifier for the Aliases Subject
                             Identifier Type.

4.  Privacy Considerations

   There are no privacy considerations.

5.  Security Considerations

   There are no security considerations.

6.  IANA Considerations







Backman & Scurtescu    Expires September 12, 2019               [Page 6]


Internet-Draft        secevent-subject-identifiers            March 2019


6.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 6.1.1.

6.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.

6.1.2.  Initial Registry Contents

6.1.2.1.  Account Subject Identifier Type

   o  Type Name: "account"

   o  Type Description: Subject identifier based on "acct" URI.

   o  Change Controller: IETF secevent Working Group




Backman & Scurtescu    Expires September 12, 2019               [Page 7]


Internet-Draft        secevent-subject-identifiers            March 2019


   o  Defining Document(s): Section 3 of this document.

6.1.2.2.  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.

6.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.

6.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.

6.1.2.5.  Aliases Subject Identifier Type

   o  Type Name: "aliases"

   o  Type Description: Subject identifier that groups together multiple
      different subject identifiers for the same subject.

   o  Change Controller: IETF secevent Working Group

   o  Defining Document(s): Section 3 of this document.








Backman & Scurtescu    Expires September 12, 2019               [Page 8]


Internet-Draft        secevent-subject-identifiers            March 2019


6.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.

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,
              <https://www.rfc-editor.org/info/rfc8126>.

   [E164]     International Telecommunication Union, "The international
              public telecommunication numbering plan", 2010,
              <http://www.itu.int/rec/T-REC-E.164-201011-I/en>.

   [JSON]     Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
              2014, <https://www.rfc-editor.org/info/rfc7159>.

   [JWT]      Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
              (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
              <https://www.rfc-editor.org/info/rfc7519>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.





Backman & Scurtescu    Expires September 12, 2019               [Page 9]


Internet-Draft        secevent-subject-identifiers            March 2019


   [RFC5321]  Klensin, J., "Simple Mail Transfer Protocol", RFC 5321,
              DOI 10.17487/RFC5321, October 2008,
              <https://www.rfc-editor.org/info/rfc5321>.

   [RFC5322]  Resnick, P., Ed., "Internet Message Format", RFC 5322,
              DOI 10.17487/RFC5322, October 2008,
              <https://www.rfc-editor.org/info/rfc5322>.

   [RFC7565]  Saint-Andre, P., "The 'acct' URI Scheme", RFC 7565,
              DOI 10.17487/RFC7565, May 2015,
              <https://www.rfc-editor.org/info/rfc7565>.

   [SET]      Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari,
              "Security Event Token (SET)", RFC 8417,
              DOI 10.17487/RFC8417, July 2018,
              <https://www.rfc-editor.org/info/rfc8417>.

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

   Draft 01 - AB:

   o  Added reference to RFC 5322 for format of "email" claim.

   o  Renamed "iss_sub" type to "iss-sub".

   o  Renamed "id_token_claims" type to "id-token-claims".

   o  Added text specifying the nature of the subjects described by each
      type.

   Draft 02 - AB:

   o  Corrected format of phone numbers in examples.

   o  Updated author info.

   Draft 03 - AB:



Backman & Scurtescu    Expires September 12, 2019              [Page 10]


Internet-Draft        secevent-subject-identifiers            March 2019


   o  Added "account" type for "acct" URIs.

   o  Replaced "id-token-claims" type with "aliases" type.

   o  Added email canonicalization guidance.

   o  Updated semantics for "email", "phone", and "iss-sub" types.

Authors' Addresses

   Annabelle Backman (editor)
   Amazon

   Email: richanna@amazon.com


   Marius Scurtescu
   Coinbase

   Email: marius.scurtescu@coinbase.com































Backman & Scurtescu    Expires September 12, 2019              [Page 11]


Html markup produced by rfcmarkup 1.129d, available from https://tools.ietf.org/tools/rfcmarkup/