Subject Identifiers for Security Event TokensAmazonrichanna@amazon.comCoinbasemarius.scurtescu@coinbase.com
Security
Security Events Working GroupInternet-DraftSecurity 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 object such as a JSON Web Token or Security Event Token, and a registry for defining and allocating names for these claim sets.As described in section 1.2 of , 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.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 .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 . 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 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 .The Account Subject Identifier Type describes a user account at a service provider, identified with an acct URI as defined in . 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: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 . 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 . 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: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.The Phone Number Subject Identifier Type describes a principal identified with a telephone number. Subject Identifiers of this type MUST contain a phone_number claim whose value is a string containing the full telephone number of the subject, including international dialing prefix, formatted according to E.164. The phone_number claim is REQUIRED and MUST NOT be null or empty. The Phone Number Subject Identifier Type is identified by the name phone-number.Below is a non-normative example Subject Identifier for the Email 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 . These claims MUST follow the formats of the iss claim and sub claim defined by , 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: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 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.alias Subject Identifiers MUST NOT be nested; i.e., the identifiers claim of an alias Subject Identifier MUST NOT contain a Subject Identifier of type aliases.Below is a non-normative example Subject Identifier for the Aliases Subject Identifier Type:This document defines the sub_id JWT Claim, in accordance with Section 4.2 of . 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 sub_id claims are present in a JWT, they MUST identify the same principal.Below is are non-normative examples of JWTs containing the sub_id claim: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 claim MAY be different. For example, an OpenID Connect client may construct such a JWT when issuing a JWT back to its OpenID Connect Identity Provider, in order to communicate information about the services’ shared subject principal using an identifier the Identity Provider is known to understand. Similarly, the JWT’s sub claim and the Subject Identifier’s sub claim MAY be different. For example, this may be used by an OpenID Connect client to communicate the subject principal’s local identifier at the client back to its Identity Provider.Below are non-normative examples of a JWT where the iss claims are the same, and a JWT where they are different.The act of presenting two or more identifiers for a single principal together (e.g., within an aliases Subject Identifier, or via the sub and sub_id JWT claims) may communicate more information about the principal than was intended. For example, the entity to which the identifiers are presented, now knows that both identifiers relate to the same principal, and may be able to correlate additional data based on that. When transmitting Subject Identifiers, the transmitter SHOULD take care that they are only transmitting multiple identifiers together when it is known that the recipient already knows that the identifiers are related (e.g., because they were previously sent to the recipient as claims in an OpenID Connect ID Token).There are no security considerations.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 . Future assignments are to be made through the Expert Review registration policy and shall follow the template presented in .
The name of the Subject Identifier Type, as described in . 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.
A brief description of the Subject Identifier Type.
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.
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.Type Name: accountType Description: Subject identifier based on acct URI.Change Controller: IETF secevent Working GroupDefining Document(s): of this document.Type Name: emailType Description: Subject identifier based on email address.Change Controller: IETF secevent Working GroupDefining Document(s): of this document.Type Name: iss-subType Description: Subject identifier based on an issuer and subject.Change Controller: IETF secevent Working GroupDefining Document(s): of this document.Type Name: phone-numberType Description: Subject identifier based on an phone number.Change Controller: IETF secevent Working GroupDefining Document(s): of this document.Type Name: aliasesType Description: Subject identifier that groups together multiple different subject identifiers for the same subject.Change Controller: IETF secevent Working GroupDefining Document(s): of this document.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.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 Claims Registry established by .Claim Name: “sub_id”Claim Description: Subject IdentifierChange Controller: IESGSpecification Document(s): of this document.Guidelines for Writing an IANA Considerations Section in RFCsMany protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA).To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry.This is the third edition of this document; it obsoletes RFC 5226.The JavaScript Object Notation (JSON) Data Interchange FormatJavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data.This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance.JSON Web Token (JWT)JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted.Security Event Token (SET)This specification defines the Security Event Token (SET) data structure. A SET describes statements of fact from the perspective of an issuer about a subject. These statements of fact represent an event that occurred directly to or about a security subject, for example, a statement about the issuance or revocation of a token on behalf of a subject. This specification is intended to enable representing security- and identity-related events. A SET is a JSON Web Token (JWT), which can be optionally signed and/or encrypted. SETs can be distributed via protocols such as HTTP.The international public telecommunication numbering planInternational Telecommunication UnionJSON Web Token ClaimsIANAKey words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.The 'acct' URI SchemeThis document defines the 'acct' Uniform Resource Identifier (URI) scheme as a way to identify a user's account at a service provider, irrespective of the particular protocols that can be used to interact with the account.Internet Message FormatThis document specifies the Internet Message Format (IMF), a syntax for text messages that are sent between computer users, within the framework of "electronic mail" messages. This specification is a revision of Request For Comments (RFC) 2822, which itself superseded Request For Comments (RFC) 822, "Standard for the Format of ARPA Internet Text Messages", updating it to reflect current practice and incorporating incremental changes that were specified in other RFCs. [STANDARDS-TRACK]Simple Mail Transfer ProtocolThis document is a specification of the basic protocol for Internet electronic mail transport. It consolidates, updates, and clarifies several previous documents, making all or parts of most of them obsolete. It covers the SMTP extension mechanisms and best practices for the contemporary Internet, but does not provide details about particular extensions. Although SMTP was designed as a mail transport and delivery protocol, this specification also contains information that is important to its use as a "mail submission" protocol for "split-UA" (User Agent) mail reading systems and mobile environments. [STANDARDS-TRACK]JSON Web Token (JWT)JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted.OpenID Connect Core 1.0Nomura Research Institute, Ltd.Ping IdentityMicrosoftGoogleSalesforceThis 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.(This section to be removed by the RFC Editor before publication as an RFC.)Draft 00 - AB - First draftDraft 01 - AB:Added reference to RFC 5322 for format of email claim.Renamed iss_sub type to iss-sub.Renamed id_token_claims type to id-token-claims.Added text specifying the nature of the subjects described by each type.Draft 02 - AB:Corrected format of phone numbers in examples.Updated author info.Draft 03 - AB:Added account type for acct URIs.Replaced id-token-claims type with aliases type.Added email canonicalization guidance.Updated semantics for email, phone, and iss-sub types.Draft 04 - AB:Added sub_id JWT Claim definition, guidance, examples.Added text prohibiting aliases nesting.Added privacy considerations for identifier correlation.Draft 05 - AB:Renamed the phone type to phone-number and its phone claim to phone_number.