JWT sub (Subject) Claim

The sub (subject) claim identifies the principal that is the subject of the JWT. In most applications, this is the user ID or account identifier. The JWT specification (RFC 7519) states that the sub value must be either locally unique within the issuer's context or globally unique, and it must be a string.

Typical usage:

{
  "sub": "auth0|507f1f77bcf86cd799439011",
  "name": "Jane Developer",
  "iat": 1700000000,
  "exp": 1700003600
}

Here, the sub claim contains a unique user identifier from an identity provider. This value is what the receiving service uses to look up the user in its database, apply authorization rules, and associate the request with a specific account.

What to put in sub:

Use an opaque, stable identifier like a database primary key, UUID, or provider-specific user ID. Never use mutable values like email addresses or usernames as the subject because users might change these. If you use email addresses and a user changes their email, the old token's sub no longer maps correctly. Opaque IDs like UUIDs solve this problem permanently.

sub in multi-tenant systems:

In multi-tenant architectures, the sub claim alone may not be sufficient to uniquely identify a user across tenants. Combine it with the iss (issuer) claim to create a globally unique identity. The pair (iss, sub) is guaranteed to be unique per the JWT specification. For example, sub: "user123" from issuer https://tenant-a.auth.com is a different identity than sub: "user123" from https://tenant-b.auth.com.

Authorization vs. authentication:

The sub claim identifies who the token represents (authentication), but it does not dictate what they can do (authorization). Authorization decisions should be based on additional claims like roles, permissions, or scopes. Never grant access based solely on the presence of a sub claim; always verify the token signature and check that the subject has the necessary permissions for the requested resource.