JWT Signature

The JWT Signature feature in OverpoweredJS adds an extra layer of security by signing every payload with a JSON Web Token (JWT). This token verifies the authenticity and integrity of the data, ensuring that the payload hasn't been tampered with. To manage your JWT Signature keys, navigate to the API Keys section.

How It Works

Once you activate the JWT Signature feature, every API payload will automatically include a jwt field. For example:

{
  "clusterUUID": ...
  "botScore": ...
  "browserTraits": ...
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Verifying JWT

Node.js (jsonwebtoken)

import jwt from 'jsonwebtoken';

function decodeToken(token, secretKey) {
  try {
    const payload = jwt.verify(token, secretKey);
    return payload;
  } catch (err) {
    return null; // invalid token
  }
}

Python (pyjwt)

import jwt

def decode_token(token: str, secret_key: str):
    try:
        payload = jwt.decode(token, secret_key, algorithms=["HS256"])
        return payload
    except jwt.PyJWTError:
        return None

Go (github.com/golang-jwt/jwt/v5)

import (
    "github.com/golang-jwt/jwt/v5"
)

func DecodeToken(tokenStr string, secretKey []byte) (map[string]interface{}, error) {
    token, err := jwt.Parse(tokenStr, func(t *jwt.Token) (interface{}, error) {
        return secretKey, nil
    })
    if err != nil || !token.Valid {
        return nil, err
    }
    return token.Claims.(jwt.MapClaims), nil
}

Java (io.jsonwebtoken)

import io.jsonwebtoken.*;

public Map<String, Object> decodeToken(String token, String secretKey) {
    try {
        Claims claims = Jwts.parser()
            .setSigningKey(secretKey.getBytes())
            .parseClaimsJws(token)
            .getBody();
        return claims;
    } catch (JwtException e) {
        return null;
    }
}

Post-Verification

1. If decodeToken (or your language's verify/decode function) returns a non-null payload, the JWT's signature is valid.
2. Next, inspect the iat field. If the token was issued more than a short moment ago, generally over 30 seconds, it should be considered invalid.

{
  "iat": 1704067200 // Monday, 1 January 2024, 12:00:00 AM UTC
}

3. Only after these checks pass should you trust the decoded data and proceed with your business logic.

As always, follow security best practices such as regular JWT key rotation to keep your system secure.