Header (JWT/JWS)

The header of a JWT (or JWS) is the first dot-separated segment, a base64url-encoded JSON object that describes the token’s signature properties. Decode it and you get a small JSON object typically containing 2-5 fields.

Standard header fields (RFC 7515 §4):

• alg — algorithm. Required. e.g., HS256, RS256, ES256, or none.
• typ — type. Conventionally "JWT" when the payload is a JWT claims set.
• kid — key ID. Lets the receiver pick the right key from a key set when the issuer rotates keys.
• jwk / jku — embedded JSON Web Key or URL to one. Less common; security-sensitive if used.
• cty — content type. Used when the payload is nested JOSE structure (e.g., a JWE inside a JWS).

Worked example. A header decoding to:

{ "alg": "RS256", "typ": "JWT", "kid": "2024-q1-key" }

declares the token is signed with RS256 (RSA + SHA-256), is a JWT (so the payload is a claims set), and was signed with the key identified by 2024-q1-key in the issuer’s key directory.

Critical security note: never trust the alg field alone. Verify that the algorithm matches what your key is suitable for. The alg-confusion attack works by passing a token signed with HS256 (HMAC) using your RSA public key as the HMAC secret — if your verifier blindly trusts alg, it accepts the forgery.

The compact base64url encoding of the header makes it human-inspectable: pasting the first dot-separated segment of any JWT into a base64url decoder reveals the algorithm and key reference within seconds. This is the entry point of every JWT debugging session — if the header decodes to garbage, the token is malformed; if it decodes to a JSON object you don’t recognise, the issuer changed something.

When and why it matters

The JWT header matters every time a service verifies a token. The classic CVE chain: a verifier accepts the alg field at face value and lets a token specifying "alg": "none" pass without signature verification at all. This bug shipped in production libraries as recently as 2015 (CVE-2015-9235, affecting Auth0’s node-jsonwebtoken). The defence is to enforce, in the verification call, the exact algorithm the library should accept — e.g., jwt.verify(token, key, { algorithms: ['RS256'] }) — and never trust the header to pick the algorithm. A second class of bug, the alg-confusion attack, exploits libraries that auto-select HMAC vs RSA based on the header: the attacker hands the verifier a token claiming HS256 but signs it with the RSA public key (which is published) used as the HMAC secret. The verifier validates against the public key and accepts the forgery. Both bugs are header-trust issues. For new JWT integrations, audit the verification call and verify it pins the algorithm. Reference: OWASP — JSON Web Token cheat sheet.

The kid header in production key rotation: in any real-world system that issues tokens at scale, the signing key needs to rotate periodically — every 90 days is a common policy. The kid field lets the issuer publish multiple keys simultaneously (old keys for in-flight tokens, new keys for fresh issuances) and the verifier picks the right one from a JWKS endpoint. The standard rotation pattern: announce the new key in the JWKS while still signing with the old key, wait one token-lifetime, switch issuance to the new key, wait one more lifetime, then remove the old key from the JWKS. The kid field is what makes this graceful — without it, key rotation requires a synchronised flag-day cutover.

What the jku / x5u attack vector looks like: some implementations allow the header to point at an arbitrary URL where the verification key supposedly lives. An attacker who sets jku to a URL they control can present any key they want and the verifier will use it. Modern guidance (RFC 8725, JOSE best practices) is to either reject jku/x5u entirely or enforce an allow-list of trusted URLs. New JWT integrations should not rely on header-controlled key location. Reference: RFC 8725 — JSON Web Token Best Current Practices.