2026-08-30 · 8 min read
- jwt
- security
- oauth
JWT is a token format family rather than one universal profile. A compact value may be a signed JWS, an encrypted JWE, or one wrapped inside the other. The typ header can identify the outer object or application profile, while cty can describe nested content.
These headers improve dispatch and interoperability, but they are protected metadata only after the enclosing cryptographic operation succeeds. They cannot replace signature verification, authenticated decryption, or claim validation.
Write the expected token profile first
Document the exact sequence accepted at each endpoint, such as an encrypted outer token containing a signed access token. State required typ and cty values, compact or JSON serialization, algorithms, key sources, issuer, audience, and maximum nesting depth.
- Reject plain claims where an encrypted outer layer is required.
- Reject nested content where only a signed JWT is expected.
- Compare media-type values according to the selected profile.
- Do not infer an algorithm from key type or token contents.
Process layers in a fixed order
Parse only enough untrusted metadata to select a preconfigured validation path. Authenticate or decrypt the outer layer using an allowlisted algorithm, enforce its type rules, then pass the authenticated payload to the inner validator.
The inner validator must independently constrain algorithms and validate issuer, audience, time claims, and profile-specific fields. A valid outer layer does not make arbitrary inner claims trustworthy.
Assign keys and responsibilities
Separate encryption keys from signing keys and record which service owns each operation. A gateway may decrypt for confidentiality while a resource server verifies the issuer's signature and authorizes scopes. Avoid designs where a proxy forwards unverified claims as trusted headers.
- Rotate inner and outer keys without assuming identical schedules.
- Bound token length and decompressed or decrypted payload size.
- Reject recursive nesting beyond the documented profile.
- Log failure categories and token fingerprints, never bearer values.
Create safe interoperability fixtures
Use Flashman's JWT tool for synthetic headers and claims, Base64 tool for individual encoded fixtures, JSON formatter for metadata, diff tool for profile comparison, and timestamp converter for expiration boundaries. Browser inspection is diagnostic; authoritative verification stays in trusted application code.
Test plain, signed, encrypted, signed-then-encrypted, wrong type, wrong content type, unexpected algorithm, missing key, invalid inner signature, expired claims, duplicate headers, and excessive nesting across every supported library.