sub
requiredscope: openid (required)Type: string (case-sensitive)
sub (subject) is the stable, unique identifier for the user within the issuer. It is the canonical user ID in OIDC. Always use sub (not email) as the primary user identifier in your database – emails can change, sub never changes for a given user at a given provider.
Details
The sub claim is the most important claim in OIDC. It uniquely identifies the user within the issuer's system.
Sub is permanent: once assigned, the sub value never changes for a specific user at a specific identity provider. Email addresses can be changed or reused. Sub is the safe database key.
Sub is issuer-scoped: the same physical person has different sub values at different providers (Google vs GitHub vs Apple). If you support multiple identity providers, store both the iss (issuer) and sub as a composite key: (iss, sub) is globally unique.
Sub format: providers choose their own format. Google uses a large numeric string ('110248495921238986516'). GitHub uses an integer. Auth0 uses a compound string ('github|123456' or 'google-oauth2|123456'). The format is opaque – treat it as an opaque string.
PAIRWISE sub: some providers (Apple Sign In) issue a different sub for each application ('pairwise' mode). The user's sub is unique per client_id, not globally. This enhances privacy but prevents cross-app user linking.
Example Values
| Label | Value |
|---|---|
| Google sub | "110248495921238986516" |
| Auth0 sub | "github|1234567" |
| Apple sub (pairwise) | "000123.abc456def789.1234" |
Validation Rules
MUST be present in every ID Token – the only required claim alongside iss, aud, exp, iat
MUST be unique per user per issuer
MUST NOT change for a given user at a given issuer
Use (iss, sub) as the composite database key when supporting multiple providers
Never use email as a primary key – use sub