Separate API’s with the same secret key have incompatible JWT’s: Unraveling the Mystery

If you’re reading this, chances are you’ve stumbled upon the frustrating issue of separate API’s with the same secret key producing incompatible JSON Web Tokens (JWT’s). Don’t worry, you’re not alone! In this article, we’ll delve into the reasons behind this phenomenon and provide you with actionable solutions to overcome it.

What are JSON Web Tokens (JWT’s)?

Before we dive into the problem, let’s take a step back and understand what JWT’s are. JSON Web Tokens are a compact, URL-safe means of transmitting information between two parties. They’re commonly used in authentication and authorization scenarios, where a server generates a token that a client can use to access protected resources.

{
  "alg": "HS256",
  "typ": "JWT"
}.
{
  "user_id": "123",
  "username": "johnDoe",
  "iat": 1643723400,
  "exp": 1643726800
}.
[signature]

The JWT structure consists of three parts: the header, payload, and signature. The header specifies the algorithm used for signing, while the payload contains the claims or data being transmitted. The signature is generated by hashing the header and payload with a secret key.

The Problem: Incompatible JWT’s

Now, let’s get back to the issue at hand. You’ve created two separate API’s, each with its own JWT implementation, but sharing the same secret key. Here’s the scenario:

API 1	API 2
Generated JWT: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMTIzIiwidXNlcm5hbWUiOiJKb2huRG9lIiwiaWF0IjoxNjQzNzIzNDAwLCJleHAiOjE2NDM3MjY4MDB9.QtG6Pf_24Q7oV5uWmV7VpQ	Generated JWT: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMTIzIiwidXNlcm5hbWUiOiJKb2huRG9lIiwiaWF0IjoxNjQzNzIzNDAwLCJleHAiOjE2NDM3MjY4MDB9.Q9tPf_24Q7oV5uWmV7VpQ

Both API’s use the same secret key, but the generated JWT’s are different. Why is that?

Reason 1: Header and Payload Concatenation

The first reason lies in the way the header and payload are concatenated before signing. Although both API’s use the same algorithm (HS256) and secret key, the concatenation process might differ.


// API 1
header = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9";
payload = "{\"user_id\":\"123\",\"username\":\"johnDoe\",\"iat\":1643723400,\"exp\":1643726800}";
unsignedToken = header + "." + payload;
signature = hmacSha256(unsignedToken, secretKey);

// API 2
header = "{\"alg\":\"HS256\",\"typ\":\"JWT\"}";
payload = "{\"user_id\":\"123\",\"username\":\"johnDoe\",\"iat\":1643723400,\"exp\":1643726800}";
unsignedToken = header + "." + payload;
signature = hmacSha256(unsignedToken, secretKey);


Note the subtle difference in the way the header is constructed. API 1 uses a URL-safe base64-encoded header, while API 2 uses a JSON object. This discrepancy leads to different unsigned tokens being generated, resulting in incompatible JWT’s.

Reason 2: Payload Ordering

The second reason for incompatible JWT’s is the ordering of claims in the payload. Although the payloads contain the same data, the order of the claims can affect the generated signature.


// API 1
payload = "{\"user_id\":\"123\",\"username\":\"johnDoe\",\"iat\":1643723400,\"exp\":1643726800}";

// API 2
payload = "{\"username\":\"johnDoe\",\"user_id\":\"123\",\"iat\":1643723400,\"exp\":1643726800}";


In this example, the ordering of the `user_id` and `username` claims differs between API’s. This might seem insignificant, but it affects the generated signature, leading to incompatible JWT’s.

Solutions to the Problem

Now that we’ve identified the reasons behind the issue, let’s explore the solutions:

Solution 1: Standardize Header and Payload Construction

Ensure that both API’s follow the same process for constructing the header and payload. Use a consistent method for encoding the header and ordering the claims in the payload.


header = base64urlEncode("{\"alg\":\"HS256\",\"typ\":\"JWT\"}");
payload = base64urlEncode("{\"user_id\":\"123\",\"username\":\"johnDoe\",\"iat\":1643723400,\"exp\":1643726800}");
unsignedToken = header + "." + payload;
signature = hmacSha256(unsignedToken, secretKey);


Solution 2: Use a Canonicalization Algorithm

Implement a canonicalization algorithm to normalize the payload before signing. This ensures that the ordering of claims doesn’t affect the generated signature.


payload = "{\"exp\":1643726800,\"iat\":1643723400,\"user_id\":\"123\",\"username\":\"johnDoe\"}";
sortedPayload = sortClaims(payload);
unsignedToken = header + "." + sortedPayload;
signature = hmacSha256(unsignedToken, secretKey);


Solution 3: Use Separate Secret Keys

The simplest solution is to use separate secret keys for each API. This eliminates the possibility of incompatible JWT’s due to differences in header and payload construction or payload ordering.

API 1	API 2
Secret Key: secretKey1	Secret Key: secretKey2

By using separate secret keys, you ensure that the generated JWT’s are unique and compatible only with their respective API’s.

Conclusion

In this article, we’ve explored the reasons behind the issue of separate API’s with the same secret key generating incompatible JWT’s. We’ve also provided actionable solutions to overcome this problem. By standardizing header and payload construction, using a canonicalization algorithm, or employing separate secret keys, you can ensure that your JWT’s are compatible across different API’s.

Remember, security is all about attention to detail. By following best practices and being mindful of the subtleties in JWT implementation, you can build robust and secure authentication systems that protect your users’ data.

1. Use a consistent method for constructing headers and payloads.
2. Implement a canonicalization algorithm to normalize payloads.
3. Employ separate secret keys for each API to ensure unique JWT’s.

By following these guidelines, you’ll be well on your way to creating secure and compatible JWT’s that safeguard your users’ data and simplify authentication across your API’s.

Frequently Asked Question

If you’re wondering why separate APIs with the same secret key can’t get along, we’ve got the scoop!