draft-ietf-secevent-subject-identifiers-05.txt   draft-ietf-secevent-subject-identifiers-06.txt 
Security Events Working Group A. Backman, Ed. Security Events Working Group A. Backman, Ed.
Internet-Draft Amazon Internet-Draft Amazon
Intended status: Standards Track M. Scurtescu Intended status: Standards Track M. Scurtescu
Expires: January 25, 2020 Coinbase Expires: March 8, 2021 Coinbase
July 24, 2019 September 04, 2020
Subject Identifiers for Security Event Tokens Subject Identifiers for Security Event Tokens
draft-ietf-secevent-subject-identifiers-05 draft-ietf-secevent-subject-identifiers-06
Abstract Abstract
Security events communicated within Security Event Tokens may support Security events communicated within Security Event Tokens may support
a variety of identifiers to identify the subject and/or other a variety of identifiers to identify the subject and/or other
principals related to the event. This specification formalizes the principals related to the event. This specification formalizes the
notion of subject identifiers as named sets of well-defined claims notion of subject identifiers as named sets of well-defined claims
describing the subject, a mechanism for representing subject describing the subject, a mechanism for representing subject
identifiers within a [JSON] object such as a JSON Web Token [JWT] or identifiers within a JSON object such as a JSON Web Token (JWT) or
Security Event Token [SET], and a registry for defining and Security Event Token (SET), and a registry for defining and
allocating names for these claim sets. allocating names for these claim sets.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 25, 2020. This Internet-Draft will expire on March 8, 2021.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 4
3. Subject Identifiers . . . . . . . . . . . . . . . . . . . . . 3 2.1. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Account Subject Identifier Type . . . . . . . . . . . . . 3 3. Subject Identifiers . . . . . . . . . . . . . . . . . . . . . 4
3.2. Email Subject Identifier Type . . . . . . . . . . . . . . 4 3.1. Subject Identifier Types versus Principal Types . . . . . 5
3.2.1. Email Canonicalization . . . . . . . . . . . . . . . 4 3.2. Subject Identifier Type Definitions . . . . . . . . . . . 5
3.3. Phone Number Subject Identifier Type . . . . . . . . . . 5 3.2.1. Account Subject Identifier Type . . . . . . . . . . . 6
3.4. Issuer and Subject Subject Identifier Type . . . . . . . 5 3.2.2. Email Subject Identifier Type . . . . . . . . . . . . 6
3.5. Aliases Subject Identifier Type . . . . . . . . . . . . . 6 3.2.3. Phone Number Subject Identifier Type . . . . . . . . 7
4. Subject Identifiers in JWTs . . . . . . . . . . . . . . . . . 7 3.2.4. Issuer and Subject Subject Identifier Type . . . . . 7
4.1. "sub_id" Claim . . . . . . . . . . . . . . . . . . . . . 7 3.2.5. Aliases Subject Identifier Type . . . . . . . . . . . 8
4.2. "sub_id" and "iss-sub" Subject Identifiers . . . . . . . 8 4. Subject Identifiers in JWTs . . . . . . . . . . . . . . . . . 9
5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 9 4.1. "sub_id" Claim . . . . . . . . . . . . . . . . . . . . . 9
5.1. Identifier Correlation . . . . . . . . . . . . . . . . . 9 4.2. "sub_id" and "iss_sub" Subject Identifiers . . . . . . . 11
6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 12
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 5.1. Identifier Correlation . . . . . . . . . . . . . . . . . 12
7.1. Security Event Subject Identifier Types Registry . . . . 10 6. Security Considerations . . . . . . . . . . . . . . . . . . . 12
7.1.1. Registration Template . . . . . . . . . . . . . . . . 10 6.1. Confidentiality and Integrity . . . . . . . . . . . . . . 12
7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 11 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
7.1.3. Guidance for Expert Reviewers . . . . . . . . . . . . 12 7.1. Security Event Subject Identifier Types Registry . . . . 13
7.2. JSON Web Token Claims Registration . . . . . . . . . . . 12 7.1.1. Registry Location . . . . . . . . . . . . . . . . . . 13
7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 12 7.1.2. Registration Template . . . . . . . . . . . . . . . . 13
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 7.1.3. Initial Registry Contents . . . . . . . . . . . . . . 14
8.1. Normative References . . . . . . . . . . . . . . . . . . 13 7.1.4. Guidance for Expert Reviewers . . . . . . . . . . . . 15
8.2. Informative References . . . . . . . . . . . . . . . . . 14 7.2. JSON Web Token Claims Registration . . . . . . . . . . . 16
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 14 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 16
Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 8.1. Normative References . . . . . . . . . . . . . . . . . . 16
8.2. Informative References . . . . . . . . . . . . . . . . . 17
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 17
Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19
1. Introduction 1. Introduction
As described in section 1.2 of [SET], the subject of a security event As described in Section 1.2 of SET [RFC8417], the subject of a
may take a variety of forms, including but not limited to a JWT security event may take a variety of forms, including but not limited
principal, an IP address, a URL, etc. Furthermore, even in the case to a JWT [RFC7519] principal, an IP address, a URL, etc.
where the subject of an event is more narrowly scoped, there may be Furthermore, even in the case where the subject of an event is more
multiple ways by which a given subject may be identified. For narrowly scoped, there may be multiple ways by which a given subject
example, an account may be identified by an opaque identifier, an may be identified. For example, an account may be identified by an
email address, a phone number, a JWT "iss" claim and "sub" claim, opaque identifier, an email address, a phone number, a JWT "iss"
etc., depending on the nature and needs of the transmitter and claim and "sub" claim, etc., depending on the nature and needs of the
receiver. Even within the context of a given transmitter and transmitter and receiver. Even within the context of a given
receiver relationship, it may be appropriate to identify different transmitter and receiver relationship, it may be appropriate to
accounts in different ways, for example if some accounts only have identify different accounts in different ways, for example if some
email addresses associated with them while others only have phone accounts only have email addresses associated with them while others
numbers. Therefore it can be necessary to indicate within a SET the only have phone numbers. Therefore it can be necessary to indicate
mechanism by which the subject of the security event is being within a SET the mechanism by which the subject of the security event
identified. is being identified.
To address this problem, this specification defines Subject
Identifiers - JSON [RFC7159] objects containing information
identifying a subject - and Subject Identifier Types - named sets of
rules describing how to encode different kinds of subject identifying
information (e.g., an email address, or an issuer and subject pair)
as a Subject Identifier.
Below is a non-normative example of a Subject Identifier that
identifies a subject by email address, using the Email Subject
Identifier Type.
{
"subject_type": "email",
"email": "user@example.com",
}
Figure 1: Example: Subject Identifier using the Email Subject
Identifier Type
Subject Identifiers are intended to be a general purpose mechanism
for identifying principals within JSON objects. Below is a non-
normative example of a JWT that uses a Subject Identifier in the
"sub_id" claim (defined in this specification) to identify its
subject.
{
"iss": "issuer.example.com",
"sub_id": {
"subject_type": "phone_number",
"phone_number": "+12065550100",
},
}
Figure 2: Example: JWT using a Subject Identifier with the sub_id
claim
Below is a non-normative example of a SET containing a hypothetical
security event describing the interception of a message, using
Subject Identifiers to identify the sender, intended recipient, and
interceptor.
{
"iss": "issuer.example.com",
"iat": 1508184845,
"aud": "aud.example.com",
"events": {
"https://secevent.example.com/events/message-interception": {
"from": {
"subject_type": "email",
"email": "alice@example.com",
},
"to": {
"subject_type": "email",
"email": "bob@example.com",
},
"interceptor": {
"subject_type": "email",
"email": "eve@example.com",
},
},
},
}
Figure 3: Example: SET with an event payload containing multiple
Subject Identifiers
2. Notational Conventions 2. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
2.1. Definitions
This specification utilizes terminology defined in [RFC7159],
[RFC7519], and [RFC8417].
3. Subject Identifiers 3. Subject Identifiers
A Subject Identifier Type is a light-weight schema that describes a A Subject Identifier is a JSON [RFC7159] object whose contents may be
set of claims that identifies a subject. Every Subject Identifier used to identify a principal within some context. A Subject
Type MUST have a unique name registered in the IANA "Security Event Identifier Type is a named definition of a set of information that
Subject Identifier Types" registry established by Section 7.1. A may be used to identify a principal, and the rules for encoding that
Subject Identifier Type MAY describe more claims than are strictly information as a Subject Identifier. A Subject Identifier MUST
conform to a specific Subject Identifier Type, and MUST contain a
"subject_type" member whose value is the name of that Subject
Identifier Type.
Every Subject Identifier Type MUST have a unique name registered in
the IANA "Security Event Subject Identifier Types" registry
established by Section 7.1, or a Collision-Resistant Name as defined
in [RFC7519]. Subject Identifier Types that are expected to be used
broadly by a variety of parties SHOULD be registered in the "Security
Event Subject Identifier Types" registry.
A Subject Identifier Type MAY describe more members than are strictly
necessary to identify a subject, and MAY describe conditions under necessary to identify a subject, and MAY describe conditions under
which those claims are required, optional, or prohibited. which those members are required, optional, or prohibited.
A Subject Identifier is a [JSON] object containing a "subject_type" Aside from the "subject_type" member whose definition is given above,
claim whose value is the name of a Subject Identifier Type, and a set every member within a Subject Identifier MUST match the format
of additional "payload claims" which are to be interpreted according specified for that member by the Subject Identifier's Subject
to the rules defined by that Subject Identifier Type. Payload claim Identifier Type. A Subject Identifier MUST NOT contain any members
values MUST match the format specified for the claim by the Subject prohibited or not described by its Subject Identifier Type, and MUST
Identifier Type. A Subject Identifier MUST NOT contain any payload contain all members required by its Subject Identifier Type.
claims prohibited or not described by its Subject Identifier Type,
and MUST contain all payload claims required by its Subject 3.1. Subject Identifier Types versus Principal Types
Identifier Type.
A Subject Identifier Type describes a way to identify a principal,
but does not explicitly indicate the type of that principal (e.g.,
user, group, network connection, baseball team, astronomic object).
Consequently Subject Identifiers remove ambiguity around how a
principal is being identified, and how to parse an identifying
structure, but they do not remove ambiguity around how to resolve
that identifier to a principal. For example, consider a directory
management API that allows callers to identify users and groups
through both immutable unique identifiers and mutable email
addresses. Such an API could use Subject Identifiers to disambiguate
between which of these two types of identifiers is in use. However,
the service would have to determine whether the principal is a user
or group via some other means, such as by querying a database or by
inferring the type from the API contract.
3.2. Subject Identifier Type Definitions
The following Subject Identifier Types are registered in the IANA The following Subject Identifier Types are registered in the IANA
"Security Event Subject Identifier Types" registry established by "Security Event Subject Identifier Types" registry established by
Section 7.1. Section 7.1.
3.1. Account Subject Identifier Type 3.2.1. Account Subject Identifier Type
The Account Subject Identifier Type describes a user account at a The Account Subject Identifier Type identifies a principal using an
service provider, identified with an "acct" URI as defined in account at a service provider, identified with an "acct" URI as
[RFC7565]. Subject Identifiers of this type MUST contain a "uri" defined in [RFC7565]. Subject Identifiers of this type MUST contain
claim whose value is the "acct" URI for the subject. The "uri" claim a "uri" member whose value is the "acct" URI for the subject. The
is REQUIRED and MUST NOT be null or empty. The Account Subject "uri" member is REQUIRED and MUST NOT be null or empty. The Account
Identifier Type is identified by the name "account". Subject Identifier Type is identified by the name "account".
Below is a non-normative example Subject Identifier for the Account Below is a non-normative example Subject Identifier for the Account
Subject Identifier Type: Subject Identifier Type:
{ {
"subject_type": "account", "subject_type": "account",
"uri": "acct:example.user@service.example.com", "uri": "acct:example.user@service.example.com",
} }
Figure 1: Example: Subject Identifier for the Account Subject Figure 4: Example: Subject Identifier for the Account Subject
Identifier Type. Identifier Type
3.2. Email Subject Identifier Type 3.2.2. Email Subject Identifier Type
The Email Subject Identifier Type describes a principal identified The Email Subject Identifier Type identifies a principal using an
with an email address. Subject Identifiers of this type MUST contain email address. Subject Identifiers of this type MUST contain an
an "email" claim whose value is a string containing the email address "email" member whose value is a string containing the email address
of the subject, formatted as an "addr-spec" as defined in of the principal, formatted as an "addr-spec" as defined in
Section 3.4.1 of [RFC5322]. The "email" claim is REQUIRED and MUST Section 3.4.1 of [RFC5322]. The "email" member is REQUIRED and MUST
NOT be null or empty. The value of the "email" claim SHOULD identify NOT be null or empty. The value of the "email" member SHOULD
a mailbox to which email may be delivered, in accordance with identify a mailbox to which email may be delivered, in accordance
[RFC5321]. The Email Subject Identifier Type is identified by the with [RFC5321]. The Email Subject Identifier Type is identified by
name "email". the name "email".
Below is a non-normative example Subject Identifier for the Email Below is a non-normative example Subject Identifier for the Email
Subject Identifier Type: Subject Identifier Type:
{ {
"subject_type": "email", "subject_type": "email",
"email": "user@example.com", "email": "user@example.com",
} }
Figure 2: Example: Subject Identifier for the Email Subject Figure 5: Example: Subject Identifier for the Email Subject
Identifier Type. Identifier Type
3.2.1. Email Canonicalization 3.2.2.1. Email Canonicalization
Many email providers will treat multiple email addresses as Many email providers will treat multiple email addresses as
equivalent. For example, some providers treat email addresses as equivalent. While the domain portion of an [RFC5322] email address
case-insensitive, and consider "user@example.com", is consistently treated as case-insensitive per [RFC1034], some
providers treat the local part of the email address as case-
insensitive as well, and consider "user@example.com",
"User@example.com", and "USER@example.com" as the same email address. "User@example.com", and "USER@example.com" as the same email address.
This has led users to view these strings as equivalent, driving This has led users to view these strings as equivalent, driving
service providers to implement proprietary email canonicalization service providers to implement proprietary email canonicalization
algorithms to ensure that email addresses entered by users resolve to algorithms to ensure that email addresses entered by users resolve to
the same canonical string. When receiving an Email Subject the same canonical string. When receiving an Email Subject
Identifier, the recipient SHOULD use their implementation's Identifier, the recipient SHOULD use their implementation's
canonicalization algorithm to resolve the email address to the same canonicalization algorithm to resolve the email address to the same
subject identifier string used in their system. string used in their system.
3.3. Phone Number Subject Identifier Type 3.2.3. Phone Number Subject Identifier Type
The Phone Number Subject Identifier Type describes a principal The Phone Number Subject Identifier Type identifies a principal using
identified with a telephone number. Subject Identifiers of this type a telephone number. Subject Identifiers of this type MUST contain a
MUST contain a "phone_number" claim whose value is a string "phone_number" member whose value is a string containing the full
containing the full telephone number of the subject, including telephone number of the principal, including international dialing
international dialing prefix, formatted according to E.164 [E164]. prefix, formatted according to E.164 [E164]. The "phone_number"
The "phone_number" claim is REQUIRED and MUST NOT be null or empty. member is REQUIRED and MUST NOT be null or empty. The Phone Number
The Phone Number Subject Identifier Type is identified by the name Subject Identifier Type is identified by the name "phone_number".
"phone-number".
Below is a non-normative example Subject Identifier for the Email Below is a non-normative example Subject Identifier for the Email
Subject Identifier Type: Subject Identifier Type:
{ {
"subject_type": "phone-number", "subject_type": "phone_number",
"phone_number": "+12065550100", "phone_number": "+12065550100",
} }
Figure 3: Example: Subject Identifier for the Phone Number Subject Figure 6: Example: Subject Identifier for the Phone Number Subject
Identifier Type. Identifier Type.
3.4. Issuer and Subject Subject Identifier Type 3.2.4. Issuer and Subject Subject Identifier Type
The Issuer and Subject Subject Identifier Type describes a principal The Issuer and Subject Subject Identifier Type identifies a principal
identified with a pair of "iss" and "sub" claims, as defined by using a pair of "iss" and "sub" members, analagous to how subjects
[JWT]. These claims MUST follow the formats of the "iss" claim and are identified using the "iss" and "sub" claims in OpenID Connect
"sub" claim defined by [JWT], respectively. Both the "iss" claim and [OpenID.Core] ID Tokens. These members MUST follow the formats of
the "sub" claim are REQUIRED and MUST NOT be null or empty. The the "iss" member and "sub" member defined by [RFC7519], respectively.
Issuer and Subject Subject Identifier Type is identified by the name Both the "iss" member and the "sub" member are REQUIRED and MUST NOT
"iss-sub". 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 Below is a non-normative example Subject Identifier for the Issuer
and Subject Subject Identifier Type: and Subject Subject Identifier Type:
{ {
"subject_type": "iss-sub", "subject_type": "iss_sub",
"iss": "http://issuer.example.com/", "iss": "http://issuer.example.com/",
"sub": "145234573", "sub": "145234573",
} }
Figure 4: Example: Subject Identifier for the Issuer and Subject Figure 7: Example: Subject Identifier for the Issuer and Subject
Subject Identifier Type. Subject Identifier Type
3.5. Aliases Subject Identifier Type 3.2.5. Aliases Subject Identifier Type
The Aliases Subject Identifier Type describes a subject that is The Aliases Subject Identifier Type describes a subject that is
identified with a list of different Subject Identifiers. It is identified with a list of different Subject Identifiers. It is
intended for use when a variety of identifiers have been shared with intended for use when a variety of identifiers have been shared with
the party that will be interpreting the Subject Identifier, and it is the party that will be interpreting the Subject Identifier, and it is
unknown which of those identifiers they will recognize or support. unknown which of those identifiers they will recognize or support.
Subject Identifiers of this type MUST contain an "identifiers" claim Subject Identifiers of this type MUST contain an "identifiers" member
whose value is a JSON array containing one or more Subject whose value is a JSON array containing one or more Subject
Identifiers. Each Subject Identifier in the array MUST identify the Identifiers. Each Subject Identifier in the array MUST identify the
same entity. The "identifiers" claim is REQUIRED and MUST NOT be same entity. The "identifiers" member is REQUIRED and MUST NOT be
null or empty. It MAY contain multiple instances of the same Subject null or empty. It MAY contain multiple instances of the same Subject
Identifier Type (e.g., multiple Email Subject Identifiers), but Identifier Type (e.g., multiple Email Subject Identifiers), but
SHOULD NOT contain exact duplicates. This type is identified by the SHOULD NOT contain exact duplicates. This type is identified by the
name "aliases". name "aliases".
"alias" Subject Identifiers MUST NOT be nested; i.e., the "alias" Subject Identifiers MUST NOT be nested; i.e., the
"identifiers" claim of an "alias" Subject Identifier MUST NOT contain "identifiers" member of an "alias" Subject Identifier MUST NOT
a Subject Identifier of type "aliases". contain a Subject Identifier of type "aliases".
Below is a non-normative example Subject Identifier for the Aliases Below is a non-normative example Subject Identifier for the Aliases
Subject Identifier Type: Subject Identifier Type:
{ {
"subject_type": "aliases", "subject_type": "aliases",
"identifiers": [ "identifiers": [
{ {
"subject_type": "email", "subject_type": "email",
"email": "user@example.com", "email": "user@example.com",
}, },
{ {
"subject_type": "phone-number", "subject_type": "phone_number",
"phone_number": "+12065550100", "phone_number": "+12065550100",
}, },
{ {
"subject_type": "email", "subject_type": "email",
"email": "user+qualifier@example.com", "email": "user+qualifier@example.com",
} }
], ],
} }
Figure 5: Example: Subject Identifier for the Aliases Subject Figure 8: Example: Subject Identifier for the Aliases Subject
Identifier Type. Identifier Type
4. Subject Identifiers in JWTs 4. Subject Identifiers in JWTs
4.1. "sub_id" Claim 4.1. "sub_id" Claim
This document defines the "sub_id" JWT Claim, in accordance with The "sub" JWT Claim is defined in Section 4.1.2 of [RFC7519] as
Section 4.2 of [RFC7519]. When present, the value of this claim MUST containing a string value, and therefore cannot contain a Subject
be a Subject Identifier that identifies the principal that is the Identifier (which is a JSON object) as its value. This document
subject of the JWT. The "sub_id" claim MAY be included in a JWT, defines the "sub_id" JWT Claim, in accordance with Section 4.2 of
[RFC7519], as a common claim that identifies the subject of the JWT
using a Subject Identifier. When present, the value of this claim
MUST be a Subject Identifier that identifies the principal that is
the subject of the JWT. The "sub_id" claim MAY be included in a JWT,
whether or not the "sub" claim is present. When both the "sub" and whether or not the "sub" claim is present. When both the "sub" and
"sub_id" claims are present in a JWT, they MUST identify the same "sub_id" claims are present in a JWT, they MUST identify the same
principal. principal.
Below is are non-normative examples of JWTs containing the "sub_id" When processing a JWT with both "sub" and "sub_id" claims,
implementations MUST NOT rely on both claims to determine the
subject. An implementation MAY attempt to determine the subject from
one claim and fall back to using the other if it determines it does
not understand the format of the first claim. For example, an
implementation may attempt to use "sub_id", and fall back to using
"sub" upon finding that "sub_id" contains a Subject Identifier whose
type is not recognized by the implementation.
Below are non-normative examples of JWTs containing the "sub_id"
claim: claim:
{ {
"iss": "issuer.example.com", "iss": "issuer.example.com",
"sub_id": { "sub_id": {
"subject_type": "email", "subject_type": "email",
"email": "user@example.com", "email": "user@example.com",
}, },
} }
Figure 6: Example: JWT containing a `sub_id` claim and no `sub` Figure 9: Example: JWT containing a `sub_id` claim and no `sub` claim
claim.
{ {
"iss": "issuer.example.com", "iss": "issuer.example.com",
"sub": "user@example.com", "sub": "user@example.com",
"sub_id": { "sub_id": {
"subject_type": "email", "subject_type": "email",
"email": "user@example.com", "email": "user@example.com",
}, },
} }
Figure 7: Example: JWT where both the `sub` and `sub_id` claims Figure 10: Example: JWT where both the `sub` and `sub_id` claims
identify the subject using the same identifier. identify the subject using the same identifier
{ {
"iss": "issuer.example.com", "iss": "issuer.example.com",
"sub": "user@example.com", "sub": "user@example.com",
"sub_id": { "sub_id": {
"subject_type": "email", "subject_type": "email",
"email": "elizabeth@example.com", "email": "elizabeth@example.com",
}, },
} }
Figure 8: Example: JWT where both the `sub` and `sub_id` claims Figure 11: Example: JWT where both the `sub` and `sub_id` claims
identify the subject using different values of the same identifier identify the subject using different values of the same identifier
type. type
{ {
"iss": "issuer.example.com", "iss": "issuer.example.com",
"sub": "user@example.com", "sub": "user@example.com",
"sub_id": { "sub_id": {
"subject_type": "account", "subject_type": "account",
"uri": "acct:example.user@service.example.com", "uri": "acct:example.user@service.example.com",
}, },
} }
Figure 9: Example: JWT where the `sub` and `sub_id` claims identify Figure 12: Example: JWT where the `sub` and `sub_id` claims identify
the subject via different types of identifiers. the subject via different types of identifiers
4.2. "sub_id" and "iss-sub" Subject Identifiers 4.2. "sub_id" and "iss_sub" Subject Identifiers
The "sub_id" claim MAY contain an "iss-sub" Subject Identifier. In The "sub_id" claim MAY contain an "iss_sub" Subject Identifier. In
this case, the JWT's "iss" claim and the Subject Identifier's "iss" this case, the JWT's "iss" claim and the Subject Identifier's "iss"
claim MAY be different. For example, an OpenID Connect [OIDC] client member MAY be different. For example, an OpenID Connect
may construct such a JWT when issuing a JWT back to its OpenID [OpenID.Core] client may construct such a JWT when issuing a JWT back
Connect Identity Provider, in order to communicate information about to its OpenID Connect Identity Provider, in order to communicate
the services' shared subject principal using an identifier the information about the services' shared subject principal using an
Identity Provider is known to understand. Similarly, the JWT's "sub" identifier the Identity Provider is known to understand. Similarly,
claim and the Subject Identifier's "sub" claim MAY be different. For the JWT's "sub" claim and the Subject Identifier's "sub" member MAY
example, this may be used by an OpenID Connect client to communicate be different. For example, this may be used by an OpenID Connect
the subject principal's local identifier at the client back to its client to communicate the subject principal's local identifier at the
Identity Provider. client back to its Identity Provider.
Below are non-normative examples of a JWT where the "iss" claims are Below are non-normative examples of a JWT where the "iss" claim and
the same, and a JWT where they are different. "iss" member within the "sub_id" claim are the same, and a JWT where
they are different.
{ {
"iss": "issuer.example.com", "iss": "issuer.example.com",
"sub_id": { "sub_id": {
"subject_type": "iss-sub", "subject_type": "iss_sub",
"iss": "issuer.example.com", "iss": "issuer.example.com",
"sub": "example_user", "sub": "example_user",
}, },
} }
Figure 10: Example: JWT with a `iss-sub` Subject Identifier where JWT Figure 13: Example: JWT with a `iss_sub` Subject Identifier where JWT
issuer and subject issuer are the same. issuer and subject issuer are the same
{ {
"iss": "client.example.com", "iss": "client.example.com",
"sub_id": { "sub_id": {
"subject_type": "iss-sub", "subject_type": "iss_sub",
"iss": "issuer.example.com", "iss": "issuer.example.com",
"sub": "example_user", "sub": "example_user",
}, },
} }
Figure 11: Example: JWT with an `iss-sub` Subject Identifier where Figure 14: Example: JWT with an `iss_sub` Subject Identifier where
the JWT issuer and subject issuer are different. the JWT issuer and subject issuer are different
{ {
"iss": "client.example.com", "iss": "client.example.com",
"sub": "client_user", "sub": "client_user",
"sub_id": { "sub_id": {
"subject_type": "iss-sub", "subject_type": "iss_sub",
"iss": "issuer.example.com", "iss": "issuer.example.com",
"sub": "example_user", "sub": "example_user",
}, },
} }
Figure 12: Example: JWT with an `iss-sub` Subject Identifier where Figure 15: Example: JWT with an `iss_sub` Subject Identifier where
the JWT `iss` and `sub` claims differ from the Subject Identifier's the JWT `iss` and `sub` claims differ from the Subject Identifier's
`iss` and `sub` claims. `iss` and `sub` members
5. Privacy Considerations 5. Privacy Considerations
5.1. Identifier Correlation 5.1. Identifier Correlation
The act of presenting two or more identifiers for a single principal The act of presenting two or more identifiers for a single principal
together (e.g., within an "aliases" Subject Identifier, or via the together (e.g., within an "aliases" Subject Identifier, or via the
"sub" and "sub_id" JWT claims) may communicate more information about "sub" and "sub_id" JWT claims) may communicate more information about
the principal than was intended. For example, the entity to which the principal than was intended. For example, the entity to which
the identifiers are presented, now knows that both identifiers relate the identifiers are presented, now knows that both identifiers relate
to the same principal, and may be able to correlate additional data to the same principal, and may be able to correlate additional data
based on that. When transmitting Subject Identifiers, the based on that. When transmitting Subject Identifiers, the
transmitter SHOULD take care that they are only transmitting multiple transmitter SHOULD take care that they are only transmitting multiple
identifiers together when it is known that the recipient already identifiers together when it is known that the recipient already
knows that the identifiers are related (e.g., because they were knows that the identifiers are related (e.g., because they were
previously sent to the recipient as claims in an OpenID Connect ID previously sent to the recipient as claims in an OpenID Connect ID
Token). Token), or when correlation is essential to the use case.
The considerations described in Section 6 of [RFC8417] also apply
when Subject Identifiers are used within SETs. The considerations
described in Section 12 of [RFC7519] also apply when Subject
Identifiers are used within JWTs.
6. Security Considerations 6. Security Considerations
There are no security considerations. 6.1. Confidentiality and Integrity
This specification does not define any mechanism for ensuring the
confidentiality or integrityi of a Subject Identifier. Where such
properties are required, implementations MUST use mechanisms provided
by the containing format (e.g., integrity protecting SETs or JWTs
using JWS [RFC7515]), or at the transport layer or other layer in the
application stack (e.g., using TLS [RFC8446]).
Further considerations regarding confidentiality and integrity of
SETs can be found in Section 5.1 of [RFC8417].
7. IANA Considerations 7. IANA Considerations
7.1. Security Event Subject Identifier Types Registry 7.1. Security Event Subject Identifier Types Registry
This document defines Subject Identifier Types, for which IANA is This document defines Subject Identifier Types, for which IANA is
asked to create and maintain a new registry titled "Security Event asked to create and maintain a new registry titled "Security Event
Subject Identifier Types". Initial values for the Security Event Subject Identifier Types". Initial values for the Security Event
Subject Identifier Types registry are given in Section 3. Future Subject Identifier Types registry are given in Section 3. Future
assignments are to be made through the Expert Review registration assignments are to be made through the Expert Review registration
policy [BCP26] and shall follow the template presented in policy [BCP26] and shall follow the template presented in
Section 7.1.1. Section 7.1.2.
7.1.1. Registration Template It is suggested that multiple Designated Experts be appointed who are
able to represent the perspectives of different applications using
this specification, in order to enable broadly informed review of
registration decisions. In cases where a registration decision could
be perceived as creating a conflict of interest for a particular
Expert, that Expert should defer to the judgment of the other
Experts.
7.1.1. Registry Location
(This section to be removed by the RFC Editor before publication as
an RFC.)
The authors recommend that the Subject Identifier Types registry be
located at "https://www.iana.org/assignments/secevent/".
7.1.2. Registration Template
Type Name Type Name
The name of the Subject Identifier Type, as described in The name of the Subject Identifier Type, as described in
Section 3. The name MUST be an ASCII string consisting only of Section 3. The name MUST be an ASCII string consisting only of
lower-case characters ("a" - "z"), digits ("0" - "9"), and hyphens lower-case characters ("a" - "z"), digits ("0" - "9"), underscores
("-"), and SHOULD NOT exceed 20 characters in length. ("_"), and hyphens ("-"), and SHOULD NOT exceed 20 characters in
length.
Type Description Type Description
A brief description of the Subject Identifier Type. A brief description of the Subject Identifier Type.
Change Controller Change Controller
For types defined in documents published by the OpenID Foundation For types defined in documents published by the IETF or its
or its working groups, list "OpenID Foundation RISC Working working groups, list "IETF". For all other types, list the name
Group". For all other types, list the name of the party of the party responsible for the registration. Contact
responsible for the registration. Contact information such as information such as mailing address, email address, or phone
mailing address, email address, or phone number may also be number may also be provided.
provided.
Defining Document(s) Defining Document(s)
A reference to the document or documents that define the Subject A reference to the document or documents that define the Subject
Identifier Type. The definition MUST specify the name, format, Identifier Type. The definition MUST specify the name, format,
and meaning of each claim that may occur within a Subject and meaning of each member that may occur within a Subject
Identifier of the defined type, as well as whether each claim is Identifier of the defined type, as well as whether each member is
optional or required, or the circumstances under which the claim optional, required, prohibited, or the circumstances under which
is optional or required. URIs that can be used to retrieve copies the member may be optional, required, or prohibited. URIs that
of each document SHOULD be included. can be used to retrieve copies of each document SHOULD be
included.
7.1.2. Initial Registry Contents 7.1.3. Initial Registry Contents
7.1.2.1. Account Subject Identifier Type 7.1.3.1. Account Subject Identifier Type
o Type Name: "account" o Type Name: "account"
o Type Description: Subject identifier based on "acct" URI. o Type Description: Subject identifier based on "acct" URI.
o Change Controller: IETF secevent Working Group o Change Controller: IETF
o Defining Document(s): Section 3 of this document. o Defining Document(s): Section 3 of this document.
7.1.2.2. Email Subject Identifier Type 7.1.3.2. Email Subject Identifier Type
o Type Name: "email" o Type Name: "email"
o Type Description: Subject identifier based on email address. o Type Description: Subject identifier based on email address.
o Change Controller: IETF secevent Working Group o Change Controller: IETF
o Defining Document(s): Section 3 of this document. o Defining Document(s): Section 3 of this document.
7.1.2.3. Issuer and Subject Subject Identifier Type 7.1.3.3. Issuer and Subject Subject Identifier Type
o Type Name: "iss-sub" o Type Name: "iss_sub"
o Type Description: Subject identifier based on an issuer and o Type Description: Subject identifier based on an issuer and
subject. subject.
o Change Controller: IETF secevent Working Group o Change Controller: IETF
o Defining Document(s): Section 3 of this document. o Defining Document(s): Section 3 of this document.
7.1.2.4. Phone Number Subject Identifier Type 7.1.3.4. Phone Number Subject Identifier Type
o Type Name: "phone-number" o Type Name: "phone_number"
o Type Description: Subject identifier based on an phone number. o Type Description: Subject identifier based on an phone number.
o Change Controller: IETF secevent Working Group o Change Controller: IETF
o Defining Document(s): Section 3 of this document. o Defining Document(s): Section 3 of this document.
7.1.2.5. Aliases Subject Identifier Type 7.1.3.5. Aliases Subject Identifier Type
o Type Name: "aliases" o Type Name: "aliases"
o Type Description: Subject identifier that groups together multiple o Type Description: Subject identifier that groups together multiple
different subject identifiers for the same subject. different subject identifiers for the same subject.
o Change Controller: IETF secevent Working Group o Change Controller: IETF
o Defining Document(s): Section 3 of this document. o Defining Document(s): Section 3 of this document.
7.1.3. Guidance for Expert Reviewers 7.1.4. Guidance for Expert Reviewers
The Expert Reviewer is expected to review the documentation The Expert Reviewer is expected to review the documentation
referenced in a registration request to verify its completeness. The referenced in a registration request to verify its completeness. The
Expert Reviewer must base their decision to accept or reject the Expert Reviewer must base their decision to accept or reject the
request on a fair and impartial assessment of the request. If 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 Expert Reviewer has a conflict of interest, such as being an author
of a defining document referenced by the request, they must recuse of a defining document referenced by the request, they must recuse
themselves from the approval process for that request. In the case themselves from the approval process for that request. In the case
where a request is rejected, the Expert Reviewer should provide the where a request is rejected, the Expert Reviewer should provide the
requesting party with a written statement expressing the reason for requesting party with a written statement expressing the reason for
skipping to change at page 12, line 43 skipping to change at page 16, line 9
Reviewer should focus on whether the type is thoroughly documented, Reviewer should focus on whether the type is thoroughly documented,
and whether its registration will promote or harm interoperability. and whether its registration will promote or harm interoperability.
In most cases, the Expert Reviewer should not approve a request if In most cases, the Expert Reviewer should not approve a request if
the registration would contribute to confusion, or amount to a the registration would contribute to confusion, or amount to a
synonym for an existing type. synonym for an existing type.
7.2. JSON Web Token Claims Registration 7.2. JSON Web Token Claims Registration
This document defines the "sub_id" JWT Claim, which IANA is asked to This document defines the "sub_id" JWT Claim, which IANA is asked to
register in the "JSON Web Token Claims" registry IANA JSON Web Token register in the "JSON Web Token Claims" registry IANA JSON Web Token
Claims Registry [IANA.JWT.Claims] established by [SET]. Claims Registry [IANA.JWT.Claims] established by [RFC7519].
7.2.1. Registry Contents 7.2.1. Registry Contents
o Claim Name: "sub_id" o Claim Name: "sub_id"
o Claim Description: Subject Identifier o Claim Description: Subject Identifier
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.1 of this document. o Specification Document(s): Section 4.1 of this document.
8. References 8. References
8.1. Normative References 8.1. Normative References
[BCP26] Cotton, M., Leiba, B., and T. Narten, "Guidelines for [BCP26] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26, Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017, RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>. <https://www.rfc-editor.org/info/rfc8126>.
skipping to change at page 13, line 23 skipping to change at page 16, line 38
<https://www.rfc-editor.org/info/rfc8126>. <https://www.rfc-editor.org/info/rfc8126>.
[E164] International Telecommunication Union, "The international [E164] International Telecommunication Union, "The international
public telecommunication numbering plan", 2010, public telecommunication numbering plan", 2010,
<http://www.itu.int/rec/T-REC-E.164-201011-I/en>. <http://www.itu.int/rec/T-REC-E.164-201011-I/en>.
[IANA.JWT.Claims] [IANA.JWT.Claims]
IANA, "JSON Web Token Claims", n.d., IANA, "JSON Web Token Claims", n.d.,
<http://www.iana.org/assignments/jwt>. <http://www.iana.org/assignments/jwt>.
[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 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, [RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321,
DOI 10.17487/RFC5321, October 2008, DOI 10.17487/RFC5321, October 2008,
<https://www.rfc-editor.org/info/rfc5321>. <https://www.rfc-editor.org/info/rfc5321>.
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
DOI 10.17487/RFC5322, October 2008, DOI 10.17487/RFC5322, October 2008,
<https://www.rfc-editor.org/info/rfc5322>. <https://www.rfc-editor.org/info/rfc5322>.
[RFC7159] 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>.
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
<https://www.rfc-editor.org/info/rfc7519>. <https://www.rfc-editor.org/info/rfc7519>.
[RFC7565] Saint-Andre, P., "The 'acct' URI Scheme", RFC 7565, [RFC7565] Saint-Andre, P., "The 'acct' URI Scheme", RFC 7565,
DOI 10.17487/RFC7565, May 2015, DOI 10.17487/RFC7565, May 2015,
<https://www.rfc-editor.org/info/rfc7565>. <https://www.rfc-editor.org/info/rfc7565>.
[SET] Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari, [RFC8417] Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari,
"Security Event Token (SET)", RFC 8417, "Security Event Token (SET)", RFC 8417,
DOI 10.17487/RFC8417, July 2018, DOI 10.17487/RFC8417, July 2018,
<https://www.rfc-editor.org/info/rfc8417>. <https://www.rfc-editor.org/info/rfc8417>.
8.2. Informative References 8.2. Informative References
[OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and [OpenID.Core]
Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and
C. Mortimore, "OpenID Connect Core 1.0", November 2014, C. Mortimore, "OpenID Connect Core 1.0", November 2014,
<http://openid.net/specs/openid-connect-core-1_0.html>. <http://openid.net/specs/openid-connect-core-1_0.html>.
[RFC1034] Mockapetris, P., "Domain names - concepts and facilities",
STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987,
<https://www.rfc-editor.org/info/rfc1034>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
2015, <https://www.rfc-editor.org/info/rfc7515>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>.
Acknowledgements Acknowledgements
This document is based on work developed within the OpenID RISC The authors would like to thank the members of the IETF Security
Working Group. The authors would like to thank the members of this Events working group, as well as those of the OpenID Shared Signals
group for their hard work and contributions. and Events Working Group, whose work provided the original basis for
this document.
Change Log Change Log
(This section to be removed by the RFC Editor before publication as (This section to be removed by the RFC Editor before publication as
an RFC.) an RFC.)
Draft 00 - AB - First draft Draft 00 - AB - First draft
Draft 01 - AB: Draft 01 - AB:
o Added reference to RFC 5322 for format of "email" claim. o Added reference to RFC 5322 for format of "email" claim.
o Renamed "iss_sub" type to "iss-sub". o Renamed "iss_sub" type to "iss-sub".
o Renamed "id_token_claims" type to "id-token-claims". o Renamed "id_token_claims" type to "id-token-claims".
skipping to change at page 15, line 20 skipping to change at page 18, line 46
o Added text prohibiting "aliases" nesting. o Added text prohibiting "aliases" nesting.
o Added privacy considerations for identifier correlation. o Added privacy considerations for identifier correlation.
Draft 05 - AB: Draft 05 - AB:
o Renamed the "phone" type to "phone-number" and its "phone" claim o Renamed the "phone" type to "phone-number" and its "phone" claim
to "phone_number". to "phone_number".
Draft 06 - AB:
o Replaced usage of the word "claim" to describe members of a
Subject Identifier with the word "member", in accordance with
terminology in RFC7159.
o Renamed the "phone-number" type to "phone_number" and "iss-sub" to
"iss_sub".
o Added normative requirements limiting the use of both "sub" and
"sub_id" claims together when processing a JWT.
o Clarified that identifier correlation may be acceptable when it is
a core part of the use case.
o Replaced references to OIDF with IETF in IANA Considerations.
o Recommended the appointment of multiple Designated Experts, and a
location for the Subject Identifier Types registry.
o Added "_" to list of allowed characters in the Type Name for
Subject Identifier Types.
o Clarified that Subject Identifiers don't provide confidentiality
or integrity protection.
o Added references to SET, JWT privacy and security considerations.
o Added section describing the difference between subject identifier
type and principal type that hopefully clarifies things and
doesn't just muddy the water further.
Authors' Addresses Authors' Addresses
Annabelle Backman (editor) Annabelle Backman (editor)
Amazon Amazon
Email: richanna@amazon.com Email: richanna@amazon.com
Marius Scurtescu Marius Scurtescu
Coinbase Coinbase
 End of changes. 83 change blocks. 
200 lines changed or deleted 392 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/