Subject Identifiers for Security Event Tokens

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 25 November 2021.¶

Copyright Notice

Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶

Table of Contents

1. Introduction

As described in Section 1.2 of SET [RFC8417], subjects related to security events may take a variety of forms, including but not limited to a JWT [RFC7519] principal, an IP address, a URL, etc. Different types of subjects may need to be identified in different ways. (e.g., a host might be identified by an IP or MAC address, while a user might be identified by an email address) Furthermore, even in the case where the type of the subject is known, 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 a subject is being identified.¶

To address this problem, this specification defines Subject Identifiers - JSON [RFC7159] objects containing information identifying a subject - and Identifier Formats - 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 Identifier Format.¶

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

Subject Identifiers are intended to be a general purpose mechanism for identifying subjects within JSON objects and their usage need not be limited to SETs. 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 the JWT Subject.¶

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

Usage of Subject Identifiers also need not be limited to identifying JWT Subjects. They are intended as a general purpose means of expressing identifying information in an unambiguous manner. 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": {
        "format": "email",
        "email": "alice@example.com"
      },
      "to": {
        "format": "email",
        "email": "bob@example.com"
      },
      "interceptor": {
        "format": "email",
        "email": "eve@example.com"
      }
    }
  }
}

2. Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].¶

3. Subject Identifiers

A Subject Identifier is a JSON [RFC7159] object whose contents may be used to identify a subject within some context. An Identifier Format is a named definition of a set of information that may be used to identify a subject, and the rules for encoding that information as a Subject Identifier; they define the syntax and semantics of Subject Identifiers. A Subject Identifier MUST conform to a specific Identifier Format, and MUST contain a format member whose value is the name of that Identifier Format.¶

Every Identifier Format MUST have a unique name registered in the IANA "Security Event Identifier Formats" registry established by Section 8.1, or a Collision-Resistant Name as defined in [RFC7519]. Identifier Formats that are expected to be used broadly by a variety of parties SHOULD be registered in the "Security Event Identifier Formats" registry.¶

An Identifier Format MAY describe more members than are strictly necessary to identify a subject, and MAY describe conditions under which those members are required, optional, or prohibited. The format member is reserved for use as described in this specification; Identifier Formats MUST NOT declare any rules regarding the format member.¶

Every member within a Subject Identifier MUST match the rules specified for that member by this specification or by Subject Identifier's Identifier Format. A Subject Identifier MUST NOT contain any members prohibited or not described by its Identifier Format, and MUST contain all members required by its Identifier Format.¶

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

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

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

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

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

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

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

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

4. Subject Identifiers in JWTs

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

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

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

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

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

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

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

5. Considerations for Specifications that Define Identifier Formats

Identifier Format definitions MUST NOT make assertions or declarations regarding the subject being identified by the Subject Identifier (e.g., an Identifier Format cannot be defined as specifically identifying human end users), as such statements are outside the scope of Identifier Formats and Subject Identifiers, and expanding that scope for some Identifier Formats but not others would harm interoperability, as applications that depend on this expanded scope to disambiguate the subject type would be unable to use Identifier Formats that do not provide such rules.¶

6. Privacy Considerations

7. Security Considerations

8. IANA Considerations

Acknowledgements

The authors would like to thank the members of the IETF Security Events working group, as well as those of the OpenID Shared Signals and Events Working Group, whose work provided the original basis for this document.¶

Change Log

(This section to be removed by the RFC Editor before publication as an RFC.)¶

Draft 00 - AB - First draft¶

Draft 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.¶

Draft 06 - AB:¶

• Replaced usage of the word "claim" to describe members of a Subject Identifier with the word "member", in accordance with terminology in RFC7159.¶
• Renamed the phone-number type to phone_number and iss-sub to iss_sub.¶
• Added normative requirements limiting the use of both sub and sub_id claims together when processing a JWT.¶
• Clarified that identifier correlation may be acceptable when it is a core part of the use case.¶
• Replaced references to OIDF with IETF in IANA Considerations.¶
• Recommended the appointment of multiple Designated Experts, and a location for the Subject Identifier Types registry.¶
• Added "_" to list of allowed characters in the Type Name for Subject Identifier Types.¶
• Clarified that Subject Identifiers don't provide confidentiality or integrity protection.¶
• Added references to SET, JWT privacy and security considerations.¶
• Added section describing the difference between subject identifier type and principal type that hopefully clarifies things and doesn't just muddy the water further.¶

Draft 07 - AB:¶

• Emphasized that the spec is about identifiers, not the things they identify:¶

  • Renamed "Subject Identifier Type" to "Identifier Format".¶
  • Renamed subject_type to format.¶
  • Renamed "Security Event Subject Identifier Type Registry" to "Security Event Identifier Format Registry".¶
  • Added new section with guidance for specs defining Identifier Formats, with normative prohibition on formats that describe the subject itself, rather than the identifier.¶

• Clarified the meaning of "subject":¶

  • Defined "subject" as applying generically and "JWT Subject" as applying specifically to the subject of a JWT.¶
  • Replaced most instances of the word "principal" with "subject".¶
• Added opaque Identifier Format¶

Draft 08 - JR, AB: * Added did Identifier Format * Alphabetized identifier format definitions * Replaced "type" with "format" in places that had been missed in the -07 change. (mostly IANA Considerations) * Miscellaneous editorial fixes¶

Authors' Addresses