RFC 9493

Subject Identifiers for Security Event Tokens

📅 published December 2023, from ietf

RFC 9493: Subject Identifiers for Security Event Tokens 🦋

Okay bestie, this one is RFC 9493, and it's giving identity-sorting energy 💅 It's an Internet Standards Track document, so it's an official, real-deal spec for the Internet, not just vibes. It was published in December 2023 with ISSN 2070-1721. The editor is A. Backman (Ed.) from Amazon, and it was co-written by M. Scurtescu from Coinbase and P. Jain from Fastly 🫶 The header doesn't list anything it obsoletes or updates, so it's standing on its own ✨

Abstract

Okay, so Security Event Tokens (SETs) can carry a bunch of different identifiers to say who a security event is about 👀 This spec turns that idea into a real thing called Subject Identifiers. They're structured info that describes a subject, and each one follows a named format that defines how it gets encoded as a JSON object 🧚 It also sets up a registry where those format names get defined and allocated, plus the JWT sub_id Claim.

Status of This Memo

This is an Internet Standards Track document.

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community, it got public review, and the Internet Engineering Steering Group (IESG) approved it for publication 🌈 If you want more on Internet Standards, check out Section 2 of RFC 7841.

For the current status, any errata, and how to give feedback, go to https://www.rfc-editor.org/info/rfc9493.

Copyright Notice

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they stand on the publication date. Please actually read these, because they spell out your rights and restrictions for this document 📜 Also, any Code Components pulled out of this document have to include the Revised BSD License text, as described in Section 4.e of the Trust Legal Provisions. They come with no warranty, per the Revised BSD License.

   1.  Introduction
   2.  Notational Conventions
     2.1.  Definitions
   3.  Subject Identifiers
     3.1.  Identifier Formats versus Principal Types
     3.2.  Identifier Format Definitions
       3.2.1.  Account Identifier Format
       3.2.2.  Email Identifier Format
       3.2.3.  Issuer and Subject Identifier Format
       3.2.4.  Opaque Identifier Format
       3.2.5.  Phone Number Identifier Format
       3.2.6.  Decentralized Identifier (DID) Format
       3.2.7.  Uniform Resource Identifier (URI) Format
       3.2.8.  Aliases Identifier Format
   4.  Subject Identifiers in JWTs
     4.1.  JWT "sub_id" Claim
     4.2.  JWT "sub_id" Claim and "iss_sub" Subject Identifier
   5.  Considerations for Specifications that Define Identifier
           Formats
   6.  Privacy Considerations
     6.1.  Identifier Correlation
   7.  Security Considerations
   8.  IANA Considerations
     8.1.  Security Event Identifier Formats Registry
       8.1.1.  Registration Template
       8.1.2.  Initial Registry Contents
       8.1.3.  Guidance for Expert Reviewers
     8.2.  JSON Web Token Claims Registration
       8.2.1.  Registry Contents
   9.  References
     9.1.  Normative References
     9.2.  Informative References
   Acknowledgements
   Authors' Addresses

1. Introduction 🌸

So, as Section 1.2 of [RFC8417] ("Security Event Token (SET)") explains, the subjects of security events can look all kinds of ways. They might be a JWT [RFC7519] principal, an IP address, a URL, and more 😭 Different kinds of subjects need to be identified in different ways. A user might be an email address, a phone number, or an account number. Even when you know what kind of subject you've got, there can be several ways to identify it. An account could be an opaque identifier, an email address, a phone number, a JWT "iss" Claim and "sub" Claim, and so on, depending on what the transmitter and receiver need. Even between one transmitter and receiver, you might identify different accounts differently. Say some accounts only have email addresses and others only have phone numbers 🙈 So it can be necessary to say, inside a SET, how the subject is being identified.

To deal with this, the spec defines Subject Identifiers as JSON [RFC8259] objects that hold info identifying a subject. It also defines Identifier Formats, which are named sets of rules for encoding different kinds of subject-identifying info (like an email address, or an issuer and subject pair) as a Subject Identifier 💖

Here's a non-normative example of a Subject Identifier that identifies a subject by email address, using the Email Identifier Format:

{
  "format": "email",
  "email": "user@example.com"
}

Figure 1: Example: Subject Identifier Using the Email Identifier Format

Subject Identifiers are meant to be a general-purpose mechanism for identifying subjects inside JSON objects. Using them isn't limited to SETs ✨ Here's a non-normative example of a JWT that uses a Subject Identifier in the JWT "sub_id" Claim (defined in this specification) to identify the JWT Subject:

{
  "iss": "issuer.example.com",
  "sub_id": {
    "format": "phone_number",
    "phone_number": "+12065550100"
  }
}

Figure 2: Example: JWT Using a Subject Identifier with the JWT "sub_id" Claim

And using Subject Identifiers isn't limited to identifying JWT Subjects either 🦋 They're meant as a general-purpose way to express identifying info in an unambiguous manner. Here's a non-normative example of a SET describing a hypothetical security event, the interception of a message. It uses Subject Identifiers to identify the sender, the intended recipient, and the interceptor (the eve of the story, lol 🙈):

{
  "iss": "issuer.example.com",
  "iat": 1508184845,
  "aud": "aud.example.com",
  "events": {
    "https://secevent.example.com/events/message-interception": {
      "from": {
        "format": "email",
        "email": "alice@example.com"
      },
      "to": {
        "format": "email",
        "email": "bob@example.com"
      },
      "interceptor": {
        "format": "email",
        "email": "eve@example.com"
      }
    }
  }
}

Figure 3: Example: SET with an Event Payload Containing Multiple Subject Identifiers

2. Notational Conventions 💅

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are the ones that mean something in this doc. They're interpreted as described in BCP 14 [RFC2119] [RFC8174], but only when they show up in all capitals, exactly as shown here 🔥

2.1. Definitions

This spec uses terminology defined in [RFC8259] and [RFC8417] ✨

Within this spec, "Subject" and "subject" both refer generically to anything being identified through one or more pieces of info. "JWT Subject" refers specifically to the subject of a JWT, meaning the subject the JWT makes claims about 🧚

3. Subject Identifiers 🎀

A Subject Identifier is a JSON object [RFC8259] whose contents can be used to identify a subject within some context. An Identifier Format is a named definition of a set of info that can be used to identify a subject, plus the rules for encoding that info as a Subject Identifier. Those rules define the syntax and semantics of Subject Identifiers 👑 A Subject Identifier MUST conform to one specific Identifier Format, and it MUST contain a "format" member whose value is the name of that Identifier Format.

Every Identifier Format MUST have a unique name, either registered in the IANA "Security Event Identifier Formats" registry (set up in Section 8.1) or a Collision-Resistant Name as defined in [RFC7519]. Identifier Formats that lots of different parties are expected to use SHOULD be registered in the "Security Event Identifier Formats" registry 🌈

An Identifier Format MAY describe more members than are strictly needed to identify a subject. It MAY also describe conditions under which those members are required, optional, or prohibited. The "format" member is reserved for use as this spec describes, so Identifier Formats MUST NOT declare any rules about the "format" member 💀

Every member within a Subject Identifier MUST match the rules that this spec, or the Subject Identifier's Identifier Format, sets for that member. A Subject Identifier MUST NOT contain any members that are prohibited or not described by its Identifier Format, and it MUST contain all members its Identifier Format requires 🫶

3.1. Identifier Formats versus Principal Types

Identifier Formats define how to encode identifying info for a subject. Unlike Principal Types, they don't define the type or nature of the subject itself 🦋 For example, the Email Identifier Format says the value of the "email" member is an email address. But a subject in a security event identified by an Email Subject Identifier could be an end user who controls that address, the mailbox itself, or anything else the transmitter and receiver both understand to be associated with that address. So Subject Identifiers clear up any ambiguity about how a subject is identified and how to parse the identifying structure. They do NOT clear up ambiguity about how to resolve that identifier to a subject, though 😭

Here's a sample: think of a directory management API that lets callers identify users and groups by both opaque unique identifiers and email addresses. That API could use Subject Identifiers to tell which of those two identifier types is in use. But it would still have to figure out whether the subject is a user or a group some other way, like by querying a database, reading other parameters in the request, or inferring the type from the API contract 🧠

3.2. Identifier Format Definitions 🌸

The following Identifier Formats are registered in the IANA "Security Event Identifier Formats" registry set up in Section 8.1.

Since the Subject Identifier Format carries semantic info, applications SHOULD choose the most specific possible format for the identifier in question 💖 For example, an email address can be conveyed using a "mailto:" URI and the URI Identifier Format. But since the value is known to be an email address, the application should prefer the Email Identifier Format instead 🍓

3.2.1. Account Identifier Format ✨

okay so the Account Identifier Format identifies a subject through an account at a service provider, and that account is named with an "acct" URI from [RFC7565] 🦋. An account is the arrangement a user has with a service: it's how they get access and how they get a unique identity there 💅. Subject Identifiers in this format MUST contain a "uri" member whose value is the "acct" URI for the subject. The "uri" member is REQUIRED and MUST NOT be null or empty 🫶. The format is labelled by a value of "account" in the "format" member.

Here's a non-normative example, just so you can see the shape 🎀:

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

Figure 4: Example: Subject Identifier for the Account Identifier Format

3.2.2. Email Identifier Format 💌

the Email Identifier Format identifies a subject with an email address 📧. Subject Identifiers in this format MUST contain an "email" member whose value is a string holding the subject's email address, written as an "addr-spec" as defined in Section 3.4.1 of [RFC5322]. The "email" member is REQUIRED and MUST NOT be null or empty. The value of the "email" member MUST identify a mailbox that email can be delivered to, following [RFC5321]. This format is named "email" 🌸.

Here's a non-normative example:

{
  "format": "email",
  "email": "user@example.com"
}

Figure 5: Example: Subject Identifier in the Email Identifier Format

3.2.2.1. Email Canonicalization 🙈

okay this part is so relatable. Lots of email providers treat multiple addresses as the same one 😭. The domain part of an email address [RFC5322] is always case-insensitive per [RFC1034], but most providers also treat the local part as case-insensitive and consider "user@example.com", "User@example.com", and "USER@example.com" to be the same address. Some providers also treat dots (".") as optional, so "user.name@example.com", "username@example.com", "u.s.e.r.name@example.com", and "u.s.e.r.n.a.m.e@example.com" might all be treated as equivalent 🍓. Users have noticed this and started seeing these strings as the same, which pushed service providers to build their own proprietary canonicalization algorithms so that whatever a user types resolves to one canonical string ✨. Email canonicalization isn't standardized, and the event recipient has no way to figure out which canonicalization method the mail provider uses 💀. So the recipient SHOULD apply its own canonicalization algorithm to incoming events, so that it reproduces the translation the local email system does 🧚.

3.2.3. Issuer and Subject Identifier Format 🌈

the Issuer and Subject Identifier Format identifies a subject with a pair of "iss" and "sub" members. It's basically the same idea as the JWT "iss" and "sub" Claims in the ID Tokens of OpenID Connect [OpenID.Core] 👑. These members MUST follow the formats of the "iss" member and the "sub" member defined by [RFC7519], respectively. Both the "iss" member and the "sub" member are REQUIRED and MUST NOT be null or empty. This format is named "iss_sub" 💜.

Here's a non-normative example:

{
  "format": "iss_sub",
  "iss": "https://issuer.example.com/",
  "sub": "145234573"
}

Figure 6: Example: Subject Identifier in the Issuer and Subject Identifier Format

3.2.4. Opaque Identifier Format 🔥

the Opaque Identifier Format is for a subject that's identified by a string with no meaning attached beyond being an identifier for that subject 🔐. Think a Universally Unique Identifier (UUID), or a hash used as a surrogate ID for a record in a database. Subject Identifiers in this format MUST contain an "id" member whose value is a JSON string holding the opaque identifier for the subject. The "id" member is REQUIRED and MUST NOT be null or empty. This format is named "opaque" 🦋.

Here's a non-normative example:

{
  "format": "opaque",
  "id": "11112222333344445555"
}

Figure 7: Example: Subject Identifier in the Opaque Identifier Format

3.2.5. Phone Number Identifier Format 📱

the Phone Number Identifier Format identifies a subject with a telephone number 🎀. Subject Identifiers in this format MUST contain a "phone_number" member whose value is a string with the subject's full telephone number, including an international dialing prefix, formatted according to E.164 [E164]. The "phone_number" member is REQUIRED and MUST NOT be null or empty. This format is named "phone_number" 🌸.

Here's a non-normative example:

{
  "format": "phone_number",
  "phone_number": "+12065550100"
}

Figure 8: Example: Subject Identifier in the Phone Number Identifier Format

3.2.6. Decentralized Identifier (DID) Format 🧚

the Decentralized Identifier (DID) Format identifies a subject using a DID URL as defined in [DID] 💫. Subject Identifiers in this format MUST contain a "url" member whose value is a DID URL for the DID Subject being identified. The value of the "url" member MUST be a valid DID URL and MAY be a bare DID. The "url" member is REQUIRED and MUST NOT be null or empty. This format is named "did" 💖.

Here are non-normative example Subject Identifiers for the Decentralized Identifier Format:

{
  "format": "did",
  "url": "did:example:123456"
}

Figure 9: Example: Subject Identifier for the Decentralized Identifier Format, Identifying a Subject with a Bare DID

{
  "format": "did",
  "url": "did:example:123456/did/url/path?versionId=1"
}

Figure 10: Example: Subject Identifier for the Decentralized Identifier Format, Identifying a Subject with a DID URL with Non-empty Path and Query Components

3.2.7. Uniform Resource Identifier (URI) Format 🌐

the Uniform Resource Identifier (URI) Format identifies a subject using a URI as defined in [RFC3986] 🔗. This format makes no assumptions or guarantees about the content, scheme, or reachability of the URI in that field, so it's very chill about what you put in there 😌. Subject Identifiers in this format MUST contain a "uri" member whose value is a URI for the subject being identified. The "uri" member is REQUIRED and MUST NOT be null or empty. This format is named "uri" ⭐.

Here are non-normative example Subject Identifiers for the URI Format:

{
  "format": "uri",
  "uri": "https://user.example.com/"
}

Figure 11: Example: Subject Identifier for the URI Format, Identifying a Subject with a Website URI

{
  "format": "uri",
  "uri": "urn:uuid:4e851e98-83c4-4743-a5da-150ecb53042f"
}

Figure 12: Example: Subject Identifier for the URI Format, Identifying a Subject with a Random URN

3.2.8. Aliases Identifier Format 👯‍♀️

the Aliases Identifier Format is for a subject identified by a list of different Subject Identifiers 🫧. It's meant for when a bunch of identifiers have been shared with whoever is reading the Subject Identifier, and nobody knows which of them that party will recognize or support. Subject Identifiers in this format MUST contain an "identifiers" member whose value is a JSON array with one or more Subject Identifiers. Each Subject Identifier in the array MUST identify the same entity. The "identifiers" member is REQUIRED and MUST NOT be null or empty. It MAY contain multiple instances of the same Identifier Format (e.g., multiple Email Subject Identifiers), but SHOULD NOT contain exact duplicates. This format is named "aliases" 🎀.

"aliases" Subject Identifiers MUST NOT be nested. In other words, the "identifiers" member of an "aliases" Subject Identifier MUST NOT contain a Subject Identifier in the Aliases Identifier Format 🙅‍♀️.

Here's a non-normative example:

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

Figure 13: Example: Subject Identifier in the Aliases Identifier Format

4. Subject Identifiers in JWTs 🧾

4.1. JWT "sub_id" Claim 🪪

okay so the JWT "sub" Claim is defined in Section 4.1.2 of [RFC7519] as holding a string value, which means it can't hold a Subject Identifier (that's a JSON object) 🙃. This document defines the JWT "sub_id" Claim, following Section 4.2 of [RFC7519], as a common claim that identifies the JWT Subject using a Subject Identifier 💜. When it's present, the value of this claim MUST be a Subject Identifier that identifies the subject of the JWT. The JWT "sub_id" Claim MAY be included in a JWT, whether or not the JWT "sub" Claim is present. When both the JWT "sub" and "sub_id" Claims are present in a JWT, they MUST identify the same subject, because a JWT has one and only one JWT Subject 👑.

When processing a JWT with both the JWT "sub" and "sub_id" Claims, implementations MUST NOT rely on both claims to determine the JWT Subject. An implementation MAY try to determine the JWT Subject from one claim and fall back to the other if it finds it doesn't understand the format of the first claim 🧠. For example, an implementation may try "sub_id" and fall back to "sub" upon finding that "sub_id" contains a Subject Identifier with a format the implementation doesn't recognize 🌈.

Here are non-normative examples of JWTs containing the JWT "sub_id" Claim:

{
  "iss": "issuer.example.com",
  "sub_id": {
    "format": "email",
    "email": "user@example.com"
  }
}

Figure 14: Example: JWT Containing a JWT "sub_id" Claim and No "sub" Claim

{
  "iss": "issuer.example.com",
  "sub": "user@example.com",
  "sub_id": {
    "format": "email",
    "email": "user@example.com"
  }
}

Figure 15: Example: JWT Where the JWT "sub" and "sub_id" Claims Identify the JWT Subject Using the Same Identifier

{
  "iss": "issuer.example.com",
  "sub": "liz@example.com",
  "sub_id": {
    "format": "email",
    "email": "elizabeth@example.com"
  }
}

Figure 16: Example: JWT Where the JWT "sub" and "sub_id" Claims Identify the JWT Subject Using Different Values of the Same Identifier Type

{
  "iss": "issuer.example.com",
  "sub": "user@example.com",
  "sub_id": {
    "format": "account",
    "uri": "acct:example.user@service.example.com"
  }
}

Figure 17: Example: JWT Where the JWT "sub" and "sub_id" Claims Identify the JWT Subject via Different Types of Identifiers

4.2. JWT "sub_id" Claim and "iss_sub" Subject Identifier

okay so the JWT "sub_id" Claim is allowed to hold an "iss_sub" Subject Identifier 💖 (it MAY, bestie, it's optional but iconic). When it does, the JWT's "iss" Claim and the Subject Identifier's "iss" member MAY be different 🦋. For example, an OpenID Connect [OpenID.Core] client might build one of these when it sends JWTs back to its OpenID Connect Identity Provider. That way it can name the JWT Subject with an identifier both sides already understand 🤝.

The same goes for "sub": the JWT's "sub" Claim and the Subject Identifier's "sub" member MAY be different 🌸. An OpenID Connect client might use this to send its Identity Provider the JWT Subject's local identifier at the client 🧚.

Below are non-normative examples 🎀. The first one has the JWT "iss" Claim and the "iss" member inside the JWT "sub_id" Claim matching, and the second one has them differing.

{
  "iss": "issuer.example.com",
  "sub_id": {
    "format": "iss_sub",
    "iss": "issuer.example.com",
    "sub": "example_user"
  }
}

Figure 18: Example: JWT with an "iss_sub" Subject Identifier Where the JWT Issuer and JWT Subject Issuer Are the Same

{
  "iss": "client.example.com",
  "sub_id": {
    "format": "iss_sub",
    "iss": "issuer.example.com",
    "sub": "example_user"
  }
}

Figure 19: Example: JWT with an "iss_sub" Subject Identifier Where the JWT Issuer and JWT Subject Issuer Are Different

{
  "iss": "client.example.com",
  "sub": "client_user",
  "sub_id": {
    "format": "iss_sub",
    "iss": "issuer.example.com",
    "sub": "example_user"
  }
}

Figure 20: Example: JWT with an "iss_sub" Subject Identifier Where the JWT "iss" and "sub" Claims Differ from the JWT Subject's "iss" and "sub" Members

5. Considerations for Specifications that Define Identifier Formats

listen 🫶, if you're writing an Identifier Format definition, you MUST NOT make assertions or declarations about the subject being identified by the Subject Identifier 🙅. Like, you can't define a format as specifically identifying human end users, no matter how tempting 💀. Those statements are outside the scope of Identifier Formats and Subject Identifiers. Expanding that scope for some formats but not others would hurt interoperability 😭, because apps that depend on the bigger scope to tell what type of subject they're dealing with wouldn't be able to use the formats that don't offer those rules.

6. Privacy Considerations

6.1. Identifier Correlation

okay this one's important 👀. Presenting two or more identifiers for a single subject together (for example, inside an "aliases" Subject Identifier or through the JWT "sub" and "sub_id" Claims) may reveal more about the subject than anyone meant to share 🙈. The entity receiving them now knows that both identifiers point to the same subject, and it may be able to correlate extra data based on that.

So when you're transmitting Subject Identifiers, the transmitter SHOULD take care to only send multiple identifiers together when the recipient is already known to understand that they're related (say, because they were previously sent as claims in an OpenID Connect ID Token), or when correlation is essential to the use case 🔐. Implementers must consider these risks, and specifications that use Subject Identifiers must provide appropriate privacy considerations of their own 🧠.

The considerations in Section 6 of [RFC8417] also apply when Subject Identifiers are used within SETs. The considerations in Section 12 of [RFC7519] also apply when Subject Identifiers are used within JWTs 💜.

7. Security Considerations

this part is SERIOUS bestie 😤. This specification does not define any mechanism for ensuring the confidentiality or integrity of a Subject Identifier. So where those properties are needed, implementations MUST use mechanisms provided by the containing format (for example, integrity protecting SETs or JWTs using JSON Web Signature (JWS) [RFC7515]) or at the transport layer or some other layer in the application stack (for example, using TLS [RFC8446]) 🛡️.

Further considerations about the confidentiality and integrity of SETs can be found in Section 5.1 of [RFC8417] 🔥.

8. IANA Considerations

8.1. Security Event Identifier Formats Registry

this document defines Identifier Formats, and IANA has created and maintains a brand new registry called "Security Event Identifier Formats" 🎀. The initial values for that registry are given in Section 3. Future assignments are to be made through the Specification Required registration policy [BCP26] and shall follow the template in Section 8.1.1 📋.

It's suggested that multiple designated experts be appointed, who can represent the perspectives of the different applications using this specification 🧑‍🔬. That way the registration decisions get broadly informed review 🌈.

8.1.1. Registration Template

Every registration needs these fields, and yes, the rules are strict 🙃:

Format Name: The name of the Identifier Format, as described in Section 3. The name MUST be an ASCII string consisting only of lowercase characters ("a" - "z"), digits ("0" - "9"), underscores ("_"), and hyphens ("-") and SHOULD NOT exceed 20 characters in length 🍓.

Format Description: A brief description of the Identifier Format ✨.

Change Controller: For formats defined in documents published by the IETF or its working groups, list "IETF". For all other formats, list the name of the party responsible for the registration. Contact information, such as a mailing address, email address, or phone number, must also be provided 📮.

Reference: A reference to the document or documents that define the Identifier Format. The reference document(s) MUST specify the name, format, and meaning of each member that may occur within a Subject Identifier of the defined format, as well as whether each member is optional, required, or conditional and the circumstances under which these optional or conditional fields would be used. URIs that can be used to retrieve copies of each document SHOULD be included 📚.

8.1.2. Initial Registry Contents

Here's the starter pack of formats, and they all point back to Section 3 🎁.

8.1.2.1. Account Identifier Format

Format Name:  account
Format Description:  Subject Identifier based on "acct" URI
Change Controller:  IETF
Reference:  Section 3 of RFC 9493

8.1.2.2. Email Identifier Format

Format Name:  email
Format Description:  Subject Identifier based on an email address
Change Controller:  IETF
Reference:  Section 3 of RFC 9493

8.1.2.3. Issuer and Subject Identifier Format

Format Name:  iss_sub
Format Description:  Subject Identifier based on an issuer and
   subject
Change Controller:  IETF
Reference:  Section 3 of RFC 9493

8.1.2.4. Opaque Identifier Format

Format Name:  opaque
Format Description:  Subject Identifier based on an opaque string
Change Controller:  IETF
Reference:  Section 3 of RFC 9493

8.1.2.5. Phone Number Identifier Format

Format Name:  phone_number
Format Description:  Subject Identifier based on a phone number
Change Controller:  IETF
Reference:  Section 3 of RFC 9493

8.1.2.6. Decentralized Identifier Format

Format Name:  did
Format Description:  Subject Identifier based on a decentralized
   identifier (DID)
Change Controller:  IETF
Reference:  Section 3 of RFC 9493

8.1.2.7. Uniform Resource Identifier Format

Format Name:  uri
Format Description:  Subject Identifier based on a Uniform Resource
   Identifier (URI)
Change Controller:  IETF
Reference:  Section 3 of RFC 9493

8.1.2.8. Aliases Identifier Format

Format Name:  aliases
Format Description:  Subject Identifier that groups together multiple
   different Subject Identifiers for the same subject
Change Controller:  IETF
Reference:  Section 3 of RFC 9493

8.1.3. Guidance for Expert Reviewers

the Expert Reviewer is expected to check that the documentation in a registration request is complete 🔍. They must base their decision to accept or reject the request on a fair and impartial assessment. If they have a conflict of interest, like being an author of a defining document referenced by the request, they must recuse themselves from approving that request 🙅‍♀️.

Identifier Formats don't need to be generally applicable 🌍. They can be super specific to a particular domain, and it's expected that niche or industry-specific formats may be registered. The Expert Reviewer should focus on whether the format is thoroughly documented and whether registering it will promote or harm interoperability 💅. In most cases, the Expert Reviewer should not approve a request if it would cause confusion or amount to a synonym for an existing format 😬.

8.2. JSON Web Token Claims Registration

this document defines the JWT "sub_id" Claim, and IANA has registered it in the "JSON Web Token Claims" registry [IANA.JWT.Claims] set up by [RFC7519] 🎉.

8.2.1. Registry Contents

Claim Name:  sub_id
Claim Description:  Subject Identifier
Change Controller:  IETF
Reference:  Section 4.1 of RFC 9493

9. References

9.1. Normative References 📚

okay bestie, these are the docs this spec leans on the hardest 💅 exactly as written:

[BCP26]    Cotton, M., Leiba, B., and T. Narten, "Guidelines for
           Writing an IANA Considerations Section in RFCs", BCP 26,
           RFC 8126, June 2017.

           <https://www.rfc-editor.org/info/bcp26>

[DID]      Sporny, M., Ed., Guy, A., Ed., Sabadello, M., Ed., Reed,
           D., Ed., Longley, D., Steele, O., and C. Allen,
           "Decentralized Identifiers (DIDs) v1.0", July 2022,
           <https://www.w3.org/TR/did-core/>.

[E164]     ITU-T, "E.164: The international public telecommunication
           numbering plan", ITU-T Recommendation E.164, November
           2010, <https://www.itu.int/rec/T-REC-E.164-201011-I/en>.

[IANA.JWT.Claims]
           IANA, "JSON Web Token Claims",
           <https://www.iana.org/assignments/jwt>.

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

[RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
           Resource Identifier (URI): Generic Syntax", STD 66,
           RFC 3986, DOI 10.17487/RFC3986, January 2005,
           <https://www.rfc-editor.org/info/rfc3986>.

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

[RFC7519]  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>.

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

[RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
           2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
           May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[RFC8259]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
           Interchange Format", STD 90, RFC 8259,
           DOI 10.17487/RFC8259, December 2017,
           <https://www.rfc-editor.org/info/rfc8259>.

[RFC8417]  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>.

9.2. Informative References 🌸

these ones are more like bonus reading, but still super useful for the full vibe ✨

[OpenID.Core]
           Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and
           C. Mortimore, "OpenID Connect Core 1.0 incorporating
           errata set 1", November 2014,
           <https://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 🫶

the authors are giving a huge shoutout to the members of the IETF Security Events Working Group 💖 and the OpenID Shared Signals and Events Working Group 💖, whose work gave this document its original foundation 🧚 they also want to thank Aaron Parecki, Denis Pinkas, Justin Richer, Mike Jones, and the other working group members who reviewed this document 👑

Authors' Addresses 🦋

Annabelle Backman (editor)
Amazon
Email: richanna@amazon.com


Marius Scurtescu
Coinbase
Email: marius.scurtescu@coinbase.com


Prachi Jain
Fastly
Email: prachi.jain1288@gmail.com

📦 where this page comes from

ietf: rfc9493 2023-12
💖 girlified by claude-haiku-5-5 on 2026-10-19: a language model's rewrite of the original, under its terms

RFC 9493

RFC 9493: Subject Identifiers for Security Event Tokens 🦋

Abstract

Status of This Memo

Copyright Notice

Table of Contents

1. Introduction 🌸

2. Notational Conventions 💅

2.1. Definitions

3. Subject Identifiers 🎀

3.1. Identifier Formats versus Principal Types

3.2. Identifier Format Definitions 🌸

3.2.1. Account Identifier Format ✨

3.2.2. Email Identifier Format 💌

3.2.2.1. Email Canonicalization 🙈

3.2.3. Issuer and Subject Identifier Format 🌈

3.2.4. Opaque Identifier Format 🔥

3.2.5. Phone Number Identifier Format 📱

3.2.6. Decentralized Identifier (DID) Format 🧚

3.2.7. Uniform Resource Identifier (URI) Format 🌐

3.2.8. Aliases Identifier Format 👯‍♀️

4. Subject Identifiers in JWTs 🧾

4.1. JWT "sub_id" Claim 🪪

4.2. JWT "sub_id" Claim and "iss_sub" Subject Identifier

5. Considerations for Specifications that Define Identifier Formats

6. Privacy Considerations

6.1. Identifier Correlation

7. Security Considerations

8. IANA Considerations

8.1. Security Event Identifier Formats Registry

8.1.1. Registration Template

8.1.2. Initial Registry Contents

8.1.2.1. Account Identifier Format

8.1.2.2. Email Identifier Format

8.1.2.3. Issuer and Subject Identifier Format

8.1.2.4. Opaque Identifier Format

8.1.2.5. Phone Number Identifier Format

8.1.2.6. Decentralized Identifier Format

8.1.2.7. Uniform Resource Identifier Format

8.1.2.8. Aliases Identifier Format

8.1.3. Guidance for Expert Reviewers

8.2. JSON Web Token Claims Registration

8.2.1. Registry Contents

9. References

9.1. Normative References 📚

9.2. Informative References 🌸

Acknowledgements 🫶

Authors' Addresses 🦋