JWT Security Implementation

This guide documents the JWT security implementation in the Tracker REST API, including security measures, vulnerability protections, and best practices.

Overview

The Tracker REST API uses JSON Web Tokens (JWT) for authentication and authorization. Our implementation follows security best practices to protect against common JWT vulnerabilities and attacks.

Security Architecture

Core Security Components

• Signature Verification: All tokens must have valid HMAC-SHA256 signatures
• Algorithm Enforcement: Strict whitelist of allowed algorithms
• Claim Validation: Comprehensive validation of all JWT claims
• No Unverified Operations: Zero tolerance for unverified JWT processing

Implementation Location

The JWT security implementation is located in app/core/security.py and includes:

• create_access_token() - Secure token creation
• create_refresh_token() - Refresh token generation
• decode_token() - Secure token verification and decoding

Security Measures

1. Signature Verification

# All tokens require valid signatures
jwt.decode(
    token,
    settings.SECRET_KEY,
    algorithms=[settings.ALGORITHM],
    options={
        "verify_signature": True,  # Mandatory signature verification
        # ... other options
    }
)

Protection Against:

• Unsigned tokens
• Tokens with invalid signatures
• Signature bypass attacks

2. Algorithm Enforcement

# Strict algorithm whitelist
algorithms=[settings.ALGORITHM]  # Only HS256 allowed

Protection Against:

• None algorithm attacks ("alg": "none")
• Algorithm confusion attacks (RS256 → HS256)
• Algorithm switching attacks

3. Comprehensive Claim Validation

options={
    "verify_signature": True,
    "verify_exp": True,      # Expiration validation
    "verify_aud": True,      # Audience validation
    "verify_iss": True,      # Issuer validation
    "require_exp": True,     # Expiration required
    "require_iat": True,     # Issued-at required
    "require_jti": True,     # JWT ID required
}

Protection Against:

• Expired tokens
• Tokens with wrong audience
• Tokens from wrong issuer
• Tokens missing critical claims

4. Secure Token Structure

Each JWT includes comprehensive claims:

{
  "exp": 1234567890, // Expiration time
  "iat": 1234567800, // Issued at
  "sub": "user_id", // Subject (user ID)
  "iss": "tracker-api", // Issuer
  "aud": "tracker-clients", // Audience
  "jti": "unique-token-id", // JWT ID (unique identifier)
  "token_type": "access" // Token type
}

Vulnerability Protections

✅ None Algorithm Attacks

Vulnerability: Accepting tokens with "alg": "none"

Our Protection:

• Algorithm whitelist prevents acceptance of "none" algorithm
• No unverified header parsing
• Strict algorithm enforcement

Test Result: ✅ SECURE

✅ Algorithm Confusion Attacks

Vulnerability: Switching algorithms (e.g., RS256 to HS256)

Our Protection:

• Only configured algorithm accepted
• No algorithm switching allowed
• Explicit algorithm specification

Test Result: ✅ SECURE

✅ Signature Validation Bypass

Vulnerability: Missing or invalid signatures being accepted

Our Protection:

• verify_signature: True enforced
• No unverified JWT operations
• All tokens must have valid signatures

Test Result: ✅ SECURE

✅ Payload Modification Attacks

Vulnerability: Modified claims (roles, user ID, expiration)

Our Protection:

• Full signature verification prevents tampering
• Any payload modification invalidates signature
• Comprehensive claim validation

Test Result: ✅ SECURE

✅ Token Structure Attacks

Vulnerability: Malformed tokens being processed

Our Protection:

• Jose library handles parsing securely
• Invalid formats rejected before processing
• Proper error handling

Test Result: ✅ SECURE

✅ Header Parameter Attacks

Vulnerability: Malicious header parameters (kid, jku, jwk)

Our Protection:

• Simple HMAC-based signing
• No processing of dangerous header parameters
• No key rotation complexity

Test Result: ✅ SECURE

Security Configuration

Required Settings

Ensure these settings are properly configured:

# Strong secret key (minimum 32 characters)
SECRET_KEY = "your-strong-secret-key-here"

# Secure algorithm
ALGORITHM = "HS256"

# Proper issuer and audience
JWT_ISSUER = "tracker-api"
JWT_AUDIENCE = "tracker-clients"

# Reasonable token lifetimes
ACCESS_TOKEN_EXPIRE_MINUTES = 30
REFRESH_TOKEN_EXPIRE_DAYS = 7

Secret Key Security

• Minimum Length: 32 characters
• Randomness: Use cryptographically secure random generation
• Storage: Store in environment variables, never in code
• Rotation: Implement regular secret rotation

Security Testing

Automated Testing

Our test suite includes comprehensive JWT security tests:

# Run JWT security tests
./run_tests_with_coverage.sh tests/core/test_security.py

Test Coverage:

• Token creation and validation
• Algorithm enforcement
• Signature verification
• Claim validation
• Error handling
• Edge cases

Manual Security Testing

For comprehensive security testing, consider implementing tests for:

1. None Algorithm Attacks
2. Algorithm Switching
3. Signature Bypass
4. Payload Modification
5. Weak Secret Detection
6. Token Structure Attacks

Security Monitoring

Recommended Monitoring

• Failed Authentication Attempts: Monitor for unusual patterns
• Token Validation Errors: Track JWT validation failures
• Algorithm Mismatch: Alert on unexpected algorithm usage
• Expired Token Usage: Monitor for expired token attempts

Logging

The implementation includes secure logging:

# Development: Detailed error logging
if settings.ENVIRONMENT != "production":
    print(f"Token decode error: {str(e)}")

# Production: Minimal information disclosure
# Errors logged without exposing sensitive details

Best Practices

Development

1. Use Strong Secrets: Generate cryptographically secure secret keys
2. Test Regularly: Run security tests with every deployment
3. Monitor Logs: Watch for authentication anomalies
4. Update Dependencies: Keep JWT libraries updated

Production

1. Environment Variables: Store secrets in environment variables
2. HTTPS Only: Always use HTTPS in production
3. Rate Limiting: Implement rate limiting on auth endpoints
4. Token Blacklisting: Consider implementing token revocation

Security Auditing

1. Regular Reviews: Audit JWT implementation quarterly
2. Penetration Testing: Include JWT testing in security assessments
3. Dependency Scanning: Monitor for vulnerabilities in JWT libraries
4. Code Reviews: Review all authentication-related code changes

Compliance

Standards Compliance

Our implementation follows:

• RFC 7519: JSON Web Token (JWT) standard
• RFC 7515: JSON Web Signature (JWS) standard
• OWASP Guidelines: JWT security best practices
• SonarQube Rules: Security quality standards

Security Certifications

• ✅ SonarQube S5659: JWT signature verification
• ✅ OWASP JWT Security: Comprehensive protection
• ✅ Industry Standards: RFC compliance

Troubleshooting

Common Issues

Invalid Token Errors:

• Check token format (header.payload.signature)
• Verify secret key configuration
• Confirm algorithm settings

Signature Verification Failures:

• Ensure secret key matches token creation
• Check for token tampering
• Verify algorithm consistency

Claim Validation Errors:

• Check token expiration
• Verify audience and issuer settings
• Ensure required claims are present

Debug Mode

For development debugging:

# Enable detailed error logging
ENVIRONMENT = "development"

Migration Notes

From Previous Implementation

If migrating from an older JWT implementation:

1. Remove Unverified Operations: Eliminate any get_unverified_header() usage
2. Add Claim Validation: Implement comprehensive claim checking
3. Update Tests: Ensure tests cover security scenarios
4. Review Configuration: Verify all security settings

Breaking Changes

• Tokens without required claims will be rejected
• Invalid algorithms will be rejected
• Unverified operations are no longer supported

Token Refresh and Session Management

For comprehensive information about JWT token refresh, session restoration, and handling mobile/Safari-specific challenges, see:

• JWT Token Refresh Implementation - Complete guide to automatic token refresh
• Wake-up session restoration for sleeping tabs
• Apple Safari and iOS-specific optimizations
• Mobile device authentication patterns
• Automatic login with refresh cookies

Safari Tab Sleep Considerations

Modern web applications must handle Safari's aggressive tab sleeping behavior, especially on iOS devices. Our JWT refresh implementation includes:

• Automatic wake-up detection when tabs become active
• Session restoration using refresh cookies
• Extended token lifetimes (4 hours) to reduce sleep impact
• Activity-based sleep detection to minimize false positives

See the Safari Tab Sleep section for detailed implementation guidance.

Related Documentation

• JWT Token Refresh Implementation - Token refresh and session management
• API Authentication
• User Management
• Security Testing Guide

Security Contact

For security-related issues or questions:

• Review this documentation first
• Check the test suite for examples
• Consult OWASP JWT security guidelines
• Consider professional security audit for production systems