JSON Web Token

What is a JSON Web Token (JWT)?

A JSON Web Token (JWT) is a compact, URL-safe token format that encodes claims as a JSON object and is digitally signed to ensure integrity and authenticity. Defined in RFC 7519, JWTs are widely used to transmit authentication and authorization information between parties -- most commonly between an identity provider and an application, or between microservices. A JWT can be verified by any party that has the signing key, without needing to call back to the issuing server.

JWTs are the token format of choice in modern identity systems. OpenID Connect uses JWTs as ID tokens to represent user identity, and OAuth 2.0 authorization servers frequently issue access tokens in JWT format. Their self-contained nature makes them particularly valuable in distributed architectures where low-latency token validation is critical.

A JWT consists of three Base64URL-encoded parts separated by dots: header, payload, and signature. The header specifies the signing algorithm, the payload contains the claims (data), and the signature ensures the token has not been tampered with. For detailed coverage of JWT usage in identity protocols, see OAuth 2 in Action.

How JWTs Work

A JWT's lifecycle involves creation, transmission, and verification:

• Token creation -- The issuing server (e.g., an authorization server) constructs the JWT header and payload, then signs the token using a secret key (HMAC) or a private key (RSA, ECDSA).
• Token delivery -- The JWT is transmitted to the client, typically in an HTTP response body after an OAuth 2.0 token exchange or OIDC authentication flow.
• Token usage -- The client includes the JWT in subsequent requests, usually in the Authorization: Bearer header.
• Token verification -- The receiving server (resource server) validates the signature using the corresponding public key or shared secret, then checks claims like exp (expiration), iss (issuer), and aud (audience).

A JWT looks like this:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwiaXNzIjoiaHR0cHM6
Ly9hdXRoLmV4YW1wbGUuY29tIiwiYXVkIjoiYXBpLmV4
YW1wbGUuY29tIiwiZXhwIjoxNzExODAwMDAwLCJyb2xl
cyI6WyJ1c2VyIl19.
<signature>

Decoded payload:

{
  "sub": "1234567890",
  "iss": "https://auth.example.com",
  "aud": "api.example.com",
  "exp": 1711800000,
  "roles": ["user"]
}

Key standard claims include sub (subject -- the user), iss (issuer), aud (audience -- the intended recipient), exp (expiration), iat (issued at), and nbf (not before).

JWTs in Practice

JWTs are used extensively in modern web architectures. OpenID Connect mandates JWTs for ID tokens, making them central to authentication in systems built on Okta, Auth0, Microsoft Entra ID, and Keycloak. When an OAuth 2.0 authorization server issues a JWT access token, resource servers can validate it locally by checking the signature against the issuer's public key (published at a JWKS endpoint), eliminating per-request calls to the authorization server.

In microservices architectures, JWTs propagate user identity and permissions across service boundaries. A gateway validates the JWT and passes it downstream, allowing each service to extract claims without redundant authentication. This pattern is fundamental to scalable API security.

JWTs are also used for short-lived, stateless sessions. Instead of storing session data server-side, the JWT itself carries all necessary session information. However, this approach requires careful handling of token revocation, since JWTs cannot be invalidated before expiration without additional infrastructure like token blocklists.

Common Misconceptions

"JWTs are encrypted." Standard JWTs (JWS -- JSON Web Signature) are signed but not encrypted. The payload is Base64URL-encoded, which is trivially decodable. Anyone who intercepts a JWT can read its claims. For confidential payloads, JWE (JSON Web Encryption) adds encryption, but it is less commonly used than JWS. "JWTs are always the right choice for sessions." JWTs work well for stateless, short-lived tokens in API-to-API communication. For browser-based sessions, server-side sessions with opaque session IDs stored in httpOnly cookies are often simpler and easier to revoke. JWTs introduce token-size and revocation challenges that may not suit all session use cases. "Long-lived JWTs with all user data are efficient." Large JWTs add overhead to every HTTP request. Including excessive claims in JWTs increases token size and can leak sensitive information. Best practice is to keep JWTs minimal and short-lived, using token introspection or UserInfo endpoints for detailed claims when needed.

Key Standards & RFCs

• RFC 7519 (JWT) -- Defines the JSON Web Token format and core claim semantics.
• RFC 7515 (JWS) -- JSON Web Signature standard for signing JWTs.
• RFC 7516 (JWE) -- JSON Web Encryption for encrypting JWT payloads.
• RFC 7517 (JWK) -- JSON Web Key format for representing cryptographic keys, including the JWKS (Key Set) endpoint format.
• RFC 7518 (JWA) -- JSON Web Algorithms specifying the cryptographic algorithms for JWS and JWE (RS256, ES256, etc.).
• RFC 9068 -- Defines a standard profile for JWT access tokens in OAuth 2.0.

Frequently Asked Questions

What is a JWT?

A JSON Web Token (JWT) is a compact, digitally signed token that encodes claims as JSON, commonly used to transmit identity and authorization information between services.

How does a JWT work?

A server creates a JWT by signing a JSON payload with a secret or private key. Recipients verify the signature to ensure the token is authentic and unmodified, then read the claims inside to make authorization decisions.

What are JWTs used for?

JWTs are used as ID tokens in OpenID Connect, as access tokens in OAuth 2.0, for stateless API authentication, and for propagating user context across microservices.

What are the benefits of JWTs?

JWTs are compact and URL-safe, can be verified without calling the issuer (using public keys), carry structured claims, and work well in distributed and stateless architectures.

JWT vs Opaque Tokens?

JWTs are self-contained -- the resource server can validate them locally using the issuer's public key. Opaque tokens are random strings that require a call to the authorization server's introspection endpoint to validate. JWTs reduce latency but are harder to revoke before expiration.