What is JSON Web Token (JWT)?
A JSON Web Token is a compact sequence of URL-safe parts that carries a set of claims. A JWT can be signed as a JSON Web Signature or encrypted as JSON Web Encryption. A signed JWT lets a receiver detect changes, but it does not hide the claims. The receiver must validate the token's cryptographic protection, issuer, audience, time claims, and application-specific requirements before it trusts any claim.
Why it matters
JWTs let systems carry verifiable claims between trust boundaries without a database lookup for each claim set. A weak validation rule can let a valid token from the wrong issuer, audience, or context cross that boundary.
How it works
- The issuer creates a protected header and claim set, selects an approved algorithm and key, and signs or encrypts the token.
- The sender sends the token only to its intended receiver over a protected channel.
- The receiver selects the correct validation rules and key, verifies the cryptographic protection, and checks issuer, audience, expiry, not-before time, and required claims before use.
Example
After Pomerium authorizes a request, it sends a short-lived signed JWT assertion to an upstream application. The application validates the Pomerium key, issuer, audience, and time claims before it uses the email or group claims.
Pomerium boundary
Pomerium can send X-Pomerium-Jwt-Assertion to an upstream application after authorization. Pomerium publishes verification keys. The upstream application must validate the token and must block direct requests that bypass Pomerium.
Limits and non-claims
- A signed JWT is not encrypted. Anyone who obtains it can read its claims unless the token also uses encryption.
- A valid signature does not prove that the issuer, audience, subject, or requested action is acceptable.
- JWT is a token format. An OAuth access token does not have to be a JWT, and a JWT is not automatically an OAuth access token.
- A bearer JWT can be replayed if a party obtains it and the receiver accepts it.
Evaluation checklist
- Define the exact token type, issuer, audience, algorithm, key source, and required claims.
- Reject unexpected algorithms, duplicate or ambiguous claim forms, invalid signatures, and tokens outside their time window.
- Keep each validation rule specific to one protocol and token purpose.
- Protect tokens in transit and storage, avoid sensitive claims, and define key rotation and revocation behavior.
