sub (Subject) Claim
The sub (subject) claim identifies the principal that is the subject of the JWT — typically a stable user ID, service account ID, or device identifier. sub should be unique within the issuer's namespace and immutable across password changes. It is the primary key for authorization lookups and audit trails. OpenID Connect builds on sub for identity federation. Implementations across Node.js, Python, Go, Ruby, and Java follow the same RFC standards, so concepts transfer directly between stacks. Security reviews should treat this as part of your full authentication threat model, not an isolated configuration detail. Document expected behavior for client teams so tokens are issued, stored, and validated consistently across services.
Why It Matters
Never use email alone as sub if it can change. Prefer opaque internal IDs. In multi-tenant systems, combine sub with tenant context in separate claims. Authorization decisions should resolve permissions from sub, not from unverified custom claims alone. Getting this wrong often surfaces only after an incident, when forged or replayed tokens expose gaps in validation or secret handling. Platform teams should encode these rules in libraries, linting, and deployment checklists so individual services cannot drift silently. Pair technical controls with monitoring: log verification failures, track unusual token lifetimes, and alert on spikes in 401 responses.
Code Example
{
"sub": "usr_8f3k2m9x",
"iss": "https://auth.example.com",
"exp": 1720454400
}Related Terms
Related Tools
Related Articles
Frequently Asked Questions
Can sub be an email?
Possible but discouraged if emails change. Use a stable internal user identifier instead. Consult your JWT library documentation for exact option names, defaults, and error types. When in doubt, prefer stricter validation and shorter token lifetimes over permissive shortcuts. Test edge cases with expired, malformed, and wrong-algorithm tokens in CI before shipping auth changes.
Is sub required?
Strongly recommended. Many frameworks assume sub exists for user resolution. Consult your JWT library documentation for exact option names, defaults, and error types. When in doubt, prefer stricter validation and shorter token lifetimes over permissive shortcuts. Test edge cases with expired, malformed, and wrong-algorithm tokens in CI before shipping auth changes.
sub vs user ID in custom claims?
Use sub for the canonical subject per RFC 7519. Custom claims can add display metadata. Consult your JWT library documentation for exact option names, defaults, and error types. When in doubt, prefer stricter validation and shorter token lifetimes over permissive shortcuts.