What Is a JWT Token? Claims, Signature Algorithms, and Security Best Practices

What Is a JWT Token? Claims, Signature Algorithms, and Security Best Practices

JSON Web Tokens (JWT) specified in RFC 7519 are an open, industry-standard method for representing claims securely between two parties. JWTs are widely used for stateless authentication in REST APIs, microservices, and Single Page Applications (SPAs).

However, improper implementation of JWT verification can introduce critical authentication bypass vulnerabilities.

Anatomy of a JWT Token

A JWT string consists of three base64url-encoded parts separated by dots (.):

HEADER . PAYLOAD . SIGNATURE

Example:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

1. Header

Contains token type and signing algorithm:

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

2. Payload (Claims)

Contains statements about an entity (typically the user) and additional metadata:

• sub (Subject): User ID
• iat (Issued At): Timestamp
• exp (Expiration): Expiry timestamp
• iss (Issuer): Identity provider URL

3. Signature

Created by taking the encoded header, encoded payload, a secret key, and signing with the specified algorithm.

JWT Payload Structure

jsonCopy
{
  "iss": "https://example.com",
  "sub": "1234567890",
  "iat": 1643723900,
  "exp": 1643723900,
  "aud": "https://example.com/api/v1",
  "jti": "1234567890",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "roles": ["admin", "moderator"]
}

JWT Signature Generation

bashCopy
echo -n '{"alg":"HS256","typ":"JWT"}' | base64
echo -n '{"iss":"https://example.com","sub":"1234567890","iat":1643723900,"exp":1643723900,"aud":"https://example.com/api/v1","jti":"1234567890","name":"John Doe","email":"john.doe@example.com","roles":["admin","moderator"]}' | base64
secret_key="your_secret_key_here"
signature=$(echo -n "$(base64 -d <<< "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9")$(base64 -d <<< "eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ")" | openssl dgst -sha256 -hmac "$secret_key" -binary | base64 -w 0)

2. Symmetric (HS256) vs Asymmetric (RS256) Signing

3. Common JWT Vulnerabilities to Avoid

1. The "alg: none" Vulnerability

Some poorly written libraries accept tokens where alg is set to none, bypassing signature validation. Always explicitly enforce allowed algorithms in server middleware.

2. Algorithm Confusion Attack (HS256 vs RS256)

If a server expects RS256 (asymmetric) but receives HS256, an attacker can sign the token using the server's public key as the secret key. Verify token algorithm before signature evaluation.

3. Missing Expiration (exp) Check

Tokens without expiration live forever. Always enforce short lifespan (e.g. 15 minutes) for access tokens and use refresh token rotation.

4. Developer Tools on Teksolvr

Inspect and debug tokens securely with Teksolvr tools:

• Decode headers and claims with our online JWT Decoder.
• Test regex validation rules with the Regex Tester.
• Generate random secrets using the Password & Key Generator.

5. Example Use Cases

• Authentication: Use JWT for stateless authentication in REST APIs, microservices, and Single Page Applications (SPAs).
• Authorization: Use JWT to store user roles and permissions, enabling fine-grained access control.
• Session Management: Use JWT to manage user sessions, eliminating the need for server-side session storage.

6. Security Best Practices

• Use HTTPS to prevent token interception and tampering.
• Enforce short-lived access tokens and refresh tokens.
• Use a secure random number generator to generate secret keys.
• Implement token blacklisting to prevent token reuse.
• Regularly rotate secret keys and refresh tokens.

7. References

• RFC 7519: JSON Web Tokens (JWT)
• RFC 7515: JSON Web Signature (JWS)
• RFC 7516: JSON Web Encryption (JWE)

8. Image Credits

• 

  Diagram Name

9. Troubleshooting Checklist

• Verify token signature and algorithm.
• Check token expiration and refresh token rotation.
• Ensure secure random number generator for secret key generation.
• Implement token blacklisting to prevent token reuse.

10. FAQs

• Q: What is a JWT token? A: A JWT token is a JSON object that contains claims, a signature, and a header.
• Q: What is the difference between symmetric and asymmetric signing? A: Symmetric signing uses a shared secret key, while asymmetric signing uses a public/private key pair.
• Q: How do I prevent the "alg: none" vulnerability? A: Always explicitly enforce allowed algorithms in server middleware.

11. Conclusion

JSON Web Tokens (JWT) are a widely used method for representing claims securely between two parties. However, improper implementation of JWT verification can introduce critical authentication bypass vulnerabilities. By following security best practices, such as using HTTPS, enforcing short-lived access tokens, and implementing token blacklisting, you can ensure secure and reliable JWT token usage in your applications.