JWT (JSON Web Token)

A JWT is a compact string consisting of three Base64Url-encoded segments separated by dots (.): Header.Payload.Signature. This structure is self-contained, meaning the payload carries all necessary claims (user identity, scopes, issuer) required for authorization, eliminating the need for the resource server to query a database or authorization server for each request. This enables efficient, stateless API design.

• Header: Contains metadata like the token type (JWT) and the signing algorithm (e.g., HS256, RS256).
• Payload: Contains the claims—statements about an entity (e.g., user) and additional data. Standard claims include iss (issuer), exp (expiration time), sub (subject).
• Signature: Created by signing the encoded header and payload with a secret or private key, ensuring the token's integrity.

The core security of a JWT lies in its digital signature (or Message Authentication Code for symmetric keys). The signature is generated using the algorithm specified in the header (e.g., HMAC SHA256, RSA SHA256). When a resource server receives a JWT, it can independently verify the signature using the appropriate key (a shared secret or the authorization server's public key). Successful verification proves:

• Integrity: The token has not been tampered with after issuance.
• Authenticity: The token was issued by a trusted party possessing the correct signing key.

This stateless verification allows scalable, distributed architectures where any service with the correct key can validate the token without coordinating with a central auth server.

JWTs use a standardized set of registered claim names defined in RFC 7519 for interoperability, while allowing custom claims for application-specific data.

Common Registered Claims:

• iss (Issuer): Identifies the principal that issued the JWT.
• sub (Subject): Identifies the principal that is the subject of the JWT.
• aud (Audience): Identifies the recipients that the JWT is intended for.
• exp (Expiration Time): Identifies the expiration time on or after which the JWT MUST NOT be accepted.
• iat (Issued At): Identifies the time at which the JWT was issued.

Custom Claims: Applications can define their own claims (e.g., user_role, permissions, tenant_id) to embed authorization context directly within the token. This flexibility makes JWTs adaptable to complex authorization models like Role-Based Access Control (RBAC) or custom attribute-based systems.

JWTs come in two primary security forms, defined by separate RFCs:

• JSON Web Signature (JWS) - RFC 7515: A signed JWT. The payload is Base64Url encoded but not encrypted, meaning its contents are readable by anyone who possesses the token. The signature ensures integrity and authenticity. This is the most common form, used for access tokens where the claims need to be read by the client or intermediate gateways.

• JSON Web Encryption (JWE) - RFC 7516: An encrypted JWT. The payload is encrypted, making the claims confidential. Only parties with the correct decryption key can read the contents. JWE is used when token contents are highly sensitive and must not be exposed to the client (e.g., tokens passed through an untrusted browser).

Most API authentication uses JWS, as the payload typically contains non-sensitive authorization context needed by the resource server.

JWTs are a foundational technology in modern API authentication and authorization flows, particularly within the OAuth 2.0 and OpenID Connect (OIDC) ecosystems.

Primary Applications:

• OAuth 2.0 Access Tokens: JWTs are commonly used as structured, self-contained access tokens, allowing resource servers to validate scopes and user context without a network call.
• OpenID Connect ID Tokens: In OIDC, the ID Token is always a JWT. It contains claims about the authentication event and user profile, which the client uses to verify the user's identity.
• Session Management: JWTs can replace traditional server-side sessions in stateless web applications (e.g., Single Page Applications). The token is stored client-side (often in an HTTP-only cookie for security) and sent with each request.
• Service-to-Service (M2M) Communication: In the OAuth 2.0 Client Credentials flow, JWTs can be used as client assertion tokens for authenticating the client to the authorization server.

While powerful, JWTs require careful implementation to avoid security pitfalls.

Key Risks and Mitigations:

• Algorithm Confusion ("alg": "none"): Attackers may try to strip or alter the signature. Mitigation: Always explicitly validate the signing algorithm on the server and reject tokens with "none" or unexpected algorithms.
• Token Storage: JWTs stored in browser localStorage are vulnerable to XSS attacks. Prefer secure, HTTP-only cookies for web apps, though this introduces CSRF concerns that must be addressed.
• Token Expiry: JWTs are valid until their exp claim. Use short-lived access tokens (minutes) paired with long-lived refresh tokens (secured server-side) to balance security and usability.
• Logout/Revocation Challenges: Because JWTs are stateless, they cannot be individually revoked before expiration. Mitigations include using very short token lifetimes, maintaining a small token blocklist, or using token introspection (RFC 7662) for active validation.
• Sensitive Data in Payload: Avoid placing sensitive data (e.g., passwords, full PII) in an unencrypted (JWS) token payload. Use JWE for confidentiality.