Cybersecurity glossary
What is the Subject Claim (sub)?
Learn what the JWT subject claim (sub) is, how it identifies the principal a token is about, why stable unique subjects matter, and how to use sub safely in authorization.
Definition
The subject claim (sub) is a registered JWT claim that identifies the principal that is the subject of the token—typically a user, service account, or client—providing a stable identifier relying parties use after validation to key authorization and audit decisions.
Why the subject claim matters
After cryptography succeeds, applications still need to know who was asserted. The subject claim (sub) is the standard identifier for that principal.
Stable, unique subjects make sessions, audits, and authorization coherent. Mutable or non-unique subjects create account merges, broken entitlement checks, and federated identity bugs.
What sub should provide
Principal identity
A value that represents the user or service the token is about.
Stability over time
Remains constant across sessions even if display names change.
Issuer-scoped uniqueness
Uniquely identifies the subject within that iss namespace.
Authorization join key
Links verified tokens to local accounts, tenants, and policy.
Using sub safely after verification
Validate token cryptography
Verify signature, algorithm policy, and trusted keys.
Confirm iss and time claims
Ensure the assertion is from a trusted issuer and currently valid.
Read sub as issuer-scoped ID
Treat (iss, sub) as the federated identity key when multiple IdPs exist.
Map to local account context
Resolve tenant membership and status without trusting client-supplied user IDs.
Authorize the requested object
Check the subject owns or may access the specific resource (anti-BOLA).
Audit with subject identifiers
Record sub (and iss) in security logs for traceability.
Subject design choices
| Subject design | Pros | Cons |
|---|---|---|
| Opaque IdP identifier | Stable, privacy-friendly | Needs mapping table locally |
| Email as sub | Human recognizable | Changes; collision and takeover risks |
| Pairwise sub per client | Reduces cross-app correlation | Harder cross-product identity linking |
| Database primary key mirrored | Simple app joins | Leaks internal IDs if tokens are exposed |
Subject claim checklist
- Require sub on user authentication and OIDC ID tokens.
- Key federated identities by (iss, sub), not sub alone.
- Prefer stable opaque identifiers over emails or usernames.
- Never authorize solely from a user id in the URL without matching sub.
- Document pairwise vs public subject policies with your IdP.
- Handle account linking carefully when subjects change across IdP migrations.
- Include sub in audit events without logging unnecessary PII claims.
- Test missing/blank sub rejection paths.
The practical takeaway
The subject claim (sub) identifies who a token is about. It is the hinge between verified assertions and application identity.
Keep it stable and unique within the issuer, always pair it with iss in multi-IdP systems, and bind every object-level authorization decision to that authenticated subject.
Related security terms
Claim
General concept of issuer assertions about a subject.
JWT Claim
How claims are structured inside JWT payloads.
OpenID Connect (OIDC)
Requires sub in ID tokens as the end-user identifier.
Broken Object-Level Authorization (BOLA)
Fails when APIs trust object IDs without binding to the authenticated subject.
Access Token
API credential that commonly carries a subject identifier.
Frequently asked questions
What is the sub claim in simple terms?
sub says who the token is about—usually the user or service identity. After the token is verified, apps use that ID to load the right account and enforce permissions.
Should sub be an email address?
Prefer a stable opaque identifier. Emails change and can create account-takeover or collision issues if used as the primary subject.
Is sub globally unique?
Within an issuer, sub must uniquely identify the subject. Across issuers, uniqueness is not guaranteed—always pair sub with iss for a federated identity key.
What are pairwise subject identifiers?
Some IdPs issue different sub values per client to reduce cross-app correlation while remaining stable for each client.
Can authorization rely on sub alone?
sub identifies the principal. Authorization still needs scopes/roles and object-level checks to prevent IDOR/BOLA.
Do machine clients have a sub?
Often yes—service accounts or client identifiers appear as subjects depending on the token profile.
What if sub is missing?
For user authentication tokens and OIDC ID tokens, missing sub is typically invalid. Access-token profiles may vary but should document required identity claims.
References
Explore authoritative guidance and frameworks related to subject claim (sub).
Explore every security definition
Return to the glossary to search by term, alias, starting letter, or security category.