Header Structure

The JWT header is a JSON object that is Base64URL encoded and forms the first part of the JWT token. It typically contains information about the signing algorithm and key references.

{
  "alg": "HS256",
  "typ": "JWT",
  "kid": "key-1"
}

Standard Header Parameters

Detailed Parameter Descriptions

Algorithm (alg)

The "alg" parameter identifies the cryptographic algorithm used to sign or encrypt the JWT.

Common Values:

• none - No signature (not recommended for production)
• HS256 - HMAC using SHA-256
• HS384 - HMAC using SHA-384
• HS512 - HMAC using SHA-512
• RS256 - RSASSA-PKCS1-v1_5 using SHA-256
• RS384 - RSASSA-PKCS1-v1_5 using SHA-384
• RS512 - RSASSA-PKCS1-v1_5 using SHA-512
• ES256 - ECDSA using P-256 and SHA-256
• ES384 - ECDSA using P-384 and SHA-384
• ES512 - ECDSA using P-521 and SHA-512
• PS256 - RSASSA-PSS using SHA-256
• PS384 - RSASSA-PSS using SHA-384
• PS512 - RSASSA-PSS using SHA-512

{
  "alg": "RS256",
  "typ": "JWT"
}

Type (typ)

The "typ" parameter declares the media type of the complete JWT. For JWTs, this is typically "JWT".

{
  "alg": "HS256",
  "typ": "JWT"
}

Key ID (kid)

The "kid" parameter is a hint indicating which key was used to secure the JWT. This allows the verifier to identify the correct key when multiple keys are available.

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "rsa-key-1"
}

JWK Set URL (jku)

The "jku" parameter is a URI that refers to a resource for a set of JSON-encoded public keys, one of which corresponds to the key used to digitally sign the JWT.

{
  "alg": "RS256",
  "typ": "JWT",
  "jku": "https://example.com/.well-known/jwks.json"
}

JSON Web Key (jwk)

The "jwk" parameter is the public key that corresponds to the key used to digitally sign the JWT, represented as a JWK object.

{
  "alg": "RS256",
  "typ": "JWT",
  "jwk": {
    "kty": "RSA",
    "use": "sig",
    "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
    "e": "AQAB"
  }
}

Critical (crit)

The "crit" parameter indicates that extensions to the JWT header are being used that MUST be understood and processed.

{
  "alg": "HS256",
  "typ": "JWT",
  "crit": ["exp"],
  "exp": 1300819380
}

Security Considerations

Algorithm Validation

• Always validate the algorithm parameter
• Use algorithm whitelisting instead of blacklisting
• Never accept the "none" algorithm in production
• Be aware of algorithm confusion attacks

Key Reference Security

• Validate "kid" parameters to prevent injection attacks
• Restrict "jku" URLs to trusted domains
• Be cautious with embedded public keys in "jwk" parameter
• Implement proper certificate validation for X.509 parameters

Best Practices

• Include only necessary header parameters
• Use consistent parameter naming
• Implement proper input validation
• Document custom header parameters

Common Header Examples

Basic HMAC-signed JWT

{
  "alg": "HS256",
  "typ": "JWT"
}

RSA-signed JWT with Key ID

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "2011-04-29"
}

ECDSA-signed JWT with JWK Set URL

{
  "alg": "ES256",
  "typ": "JWT",
  "jku": "https://example.com/.well-known/jwks.json",
  "kid": "ec-key-1"
}

JWT with embedded public key

{
  "alg": "RS256",
  "typ": "JWT",
  "jwk": {
    "kty": "RSA",
    "use": "sig",
    "n": "...",
    "e": "AQAB"
  }
}

JWT with X.509 certificate reference

{
  "alg": "RS256",
  "typ": "JWT",
  "x5u": "https://example.com/cert.pem",
  "x5t": "dGhpcyBpcyBhIFNIQTEgdGVzdA"
}

Validation Examples

Node.js Header Validation

const jwt = require('jsonwebtoken');

function validateJWTHeader(token) {
    try {
        // Decode header without verification
        const decoded = jwt.decode(token, { complete: true });
        
        if (!decoded || !decoded.header) {
            throw new Error('Invalid JWT format');
        }
        
        const header = decoded.header;
        
        // Validate algorithm
        const allowedAlgorithms = ['HS256', 'RS256', 'ES256'];
        if (!allowedAlgorithms.includes(header.alg)) {
            throw new Error(`Unsupported algorithm: ${header.alg}`);
        }
        
        // Validate type
        if (header.typ && header.typ !== 'JWT') {
            throw new Error(`Unsupported type: ${header.typ}`);
        }
        
        // Validate kid if present
        if (header.kid) {
            const allowedKids = ['key-1', 'key-2', 'rsa-key-1'];
            if (!allowedKids.includes(header.kid)) {
                throw new Error(`Invalid key ID: ${header.kid}`);
            }
        }
        
        return header;
    } catch (err) {
        throw new Error(`Header validation failed: ${err.message}`);
    }
}

Python Header Validation

import jwt
import json

def validate_jwt_header(token):
    try:
        # Decode header without verification
        header = jwt.get_unverified_header(token)
        
        # Validate algorithm
        allowed_algorithms = ['HS256', 'RS256', 'ES256']
        if header.get('alg') not in allowed_algorithms:
            raise ValueError(f"Unsupported algorithm: {header.get('alg')}")
        
        # Validate type
        if 'typ' in header and header['typ'] != 'JWT':
            raise ValueError(f"Unsupported type: {header['typ']}")
        
        # Validate kid if present
        if 'kid' in header:
            allowed_kids = ['key-1', 'key-2', 'rsa-key-1']
            if header['kid'] not in allowed_kids:
                raise ValueError(f"Invalid key ID: {header['kid']}")
        
        return header
    except Exception as e:
        raise ValueError(f"Header validation failed: {str(e)}")

Conclusion

Understanding JWT header parameters is crucial for implementing secure JWT-based authentication. Always validate header parameters properly and be aware of potential security implications when using key reference parameters.