Guide Updated

JWT sub Claim (Subject)

The JWT sub (subject) claim identifies who the token is about: usually a user ID. Learn what to use as sub, why email and sequential integers are bad choices, and how to use sub safely after verification.

The `sub` (subject) claim identifies the principal the token is about. In authentication contexts this is almost always a user ID. It is defined in RFC 7519 §4.1.2.

Format and values

A string that is unique and stable within the context of the issuer. The combination of `iss` and `sub` is globally unique: the same `sub` from two different issuers refers to two different principals.

Validation rule

Most applications use `sub` to look up the user after verification. The correct order: verify the full token (signature, exp, iss, aud) first, then use `sub` to query your user store. Never read or trust `sub` before the signature is verified: an attacker can put anything in an unverified payload.

Common mistakes

  • Using an email address as sub. Email addresses change, can be reassigned, and create user-identity confusion when a user changes their email.
  • Using a sequential integer as sub. Sequential IDs leak how many users you have and make user enumeration trivial.
  • Reading sub before signature verification. Always verify first, then trust sub.

Code examples

Use sub after verification (Node.js)

Use sub after verification (Node.js) 
// Verify first: throws on bad signature, exp, iss, or aud
const payload = jwt.verify(token, publicKey, {
  algorithms: ["RS256"],
  issuer: "https://auth.example.com",
  audience: "https://api.example.com",
});

// Only now is sub trustworthy
const user = await db.user.findById(payload.sub);

Good vs bad sub values

Good vs bad sub values 
// Good: opaque, stable, non-guessable
"sub": "usr_01HXZ9P2QVKM3NB7FW8A4TJGDC"

// Bad: email (changes, reassignable)
"sub": "alice@example.com"

// Bad: sequential integer (enumerable)
"sub": "12345"

Frequently asked questions

  • What is the sub claim in a JWT?

    sub (subject) is an RFC 7519 registered claim that identifies the principal the token is about: almost always a user ID in authentication contexts. It should be an opaque, stable, non-guessable identifier like a database primary key or a UUID. The combination of iss and sub is globally unique.

  • Should I use email as the JWT sub claim?

    No. Email addresses change, can be reassigned to different people, and create identity confusion when a user updates their email. Use an opaque, stable identifier: a database primary key, a UUID, or a generated ID like usr_01HXZ9P2QVKM3NB7FW8A4TJGDC. Email belongs in a separate email claim (an OIDC public claim), not in sub.

  • When is it safe to read the JWT sub claim?

    Only after the full token has been verified: signature checked, exp/iss/aud validated. An attacker can put any value in an unverified payload's sub. The correct order is verify first, then use sub to look up the user. Never trust sub from a token whose signature has not been checked.

Related