Improve Unified-Security handler to support HMAC validation

[stevehu]

Description
Request raised by an API team to have each request body payload HMAC signature validated by the LGW against configured private key (e.g. Workday provided key).
This flow is similar to eSignature flow use case (Asia), however the request now is to have the LGW to validate, and only when signature is valid, then proceed and route the call downstream to AWS endpoint (whereas for eSignature the HMAC is NOT validated by LGW which only pass-through to downstream to validate)

[stevehu]

Yes—the issue (#2772) is too underspecified to begin a reliable design. The first question is especially important: it says both “HMAC” and
“private key,” but those describe different cryptographic models.

Blocking questions

1. Is this actually HMAC using a shared secret, or an asymmetric digital signature verified with Workday’s public key?

2. Can the API team provide the applicable Workday specification or documentation?

3. Can they provide a sanitized test vector containing:

   • Exact request headers
   • Exact raw request body
   • Key/secret encoding
   • Expected signature

4. Which algorithm is required: HmacSHA256, HmacSHA512, RSA-SHA256, or something else?

5. Which header carries the signature, and what is its exact format?

6. Is the signature encoded as hexadecimal, Base64, or Base64URL?

7. What exactly is signed?

   • Raw body bytes
   • A body hash
   • Canonicalized JSON
   • Method, path, query, timestamp, and selected headers plus body

8. If JSON is signed, are whitespace, property order, line endings, and character encoding significant?

9. Is the signature calculated before or after decompression for gzip-encoded requests?

10. Does the protocol include a timestamp or nonce to prevent replay attacks? What clock-skew and replay window apply?

Request scope and authentication

11. Which HTTP methods and path prefixes require validation?

12. Which content types must be supported: JSON, XML, form data, multipart, or binary?

13. What happens for a matching request with an empty body?

14. Is HMAC required in addition to JWT/API-key authentication, or is it an alternative authentication mechanism?

15. Should entries in anonymousPrefixes bypass HMAC validation? They currently bypass every security check in light-4j/unified-security/src/main/java/com/networknt/security/
    UnifiedSecurityHandler.java:81.

16. Is the requirement gateway-specific, or should every application using UnifiedSecurityHandler gain this capability?

17. Should configuration be selected only by path prefix, or by method, endpoint, provider, tenant, or host?

The authentication-composition question matters because the current handler chooses between its authorization-header branch and API-key branch; it does not naturally express “JWT AND HMAC.”
See light-4j/unified-security/src/main/java/com/networknt/security/UnifiedSecurityHandler.java:100.

Key management

18. Where will the secret or verification key be stored—config server, environment secret, Kubernetes secret, Vault, or a keystore?
19. Should configuration contain the key itself or only a secret reference?
20. Can there be multiple Workday tenants or signing keys?
21. Does the request contain a key ID, and how is that mapped to the configured key?
22. What is the rotation process? Must old and new keys be accepted concurrently?
23. Should missing or invalid key configuration fail gateway startup, or reject only affected requests?
24. Must key changes be picked up through configuration reload without restarting the gateway?

Body handling and forwarding

25. What is the maximum signed payload size?
26. Is buffering the complete body acceptable, or must large bodies be verified as a stream?
27. Must the downstream AWS endpoint receive the exact original bytes and signature header unchanged?
28. Should the gateway remove the signature header after validation?
29. Can any request-transform or normalization handler run before verification?

This area blocks design because the existing body handler consumes and parses request content, sometimes converting it to UTF-8 text. HMAC normally needs exact bytes, not reconstructed JSON
or text; see light-4j/body/src/main/java/com/networknt/body/BodyHandler.java:102 and light-4j/body/src/main/java/com/networknt/body/RequestBodyInterceptor.java:80.

Failure behavior and operations

30. What response status and error body should be returned for:

• Missing signature
• Malformed signature
• Invalid signature
• Unknown key ID
• Expired timestamp or replayed request
• Key provider unavailable

31. Are audit events or metrics required for validation failures?
32. Which fields may be logged? The secret, complete signature, and body should not be logged.
33. Is a monitor-only rollout mode needed before enforcement?
34. What throughput and latency targets must validation meet?

Minimum acceptance tests

Before design, I would ask the API team to confirm these cases:

• Valid signature routes the original request unchanged.
• A one-byte body modification is rejected.
• Missing and malformed signatures are rejected correctly.
• Replay or stale timestamp is rejected, if applicable.
• Key rotation accepts the intended old/new keys.
• Whitespace, Unicode, line endings, and compression behave according to the vendor specification.
• Oversized payload behavior is defined.

A concise requirement can then be written as:

For requests matching {methods and routes}, the gateway must validate {signature header} using {algorithm} over {exact canonical input}, with the key selected from {key source/key ID}.
Validation is {in addition to/instead of} existing authentication. Invalid requests receive {response}, replay protection follows {policy}, and valid requests are forwarded {unchanged/
transformed as specified}.

I would not start the design until questions 1–10 and 14 are answered.

[stevehu]

Regarging the blocking questions on https://github.com/networknt/light-4j/issues/2772:

1. Is this actually HMAC using a shared secret, or an asymmetric digital signature verified with Workday’s public key? [GO]: It is a shared secret.
2. Can the API team provide the applicable Workday specification or documentation? [GO]: Documentation for GitHub is available here: [ https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries ](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries) .
3. Can they provide a sanitized test vector containing:
Exact request headers
Exact raw request body
Key/secret encoding
Expected signature
[GO]: Sample payload:

Secret: It's a Secret to Everybody

Request body:
Hello, World!

X-Hub-Signature-256: sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17

 

4. Which algorithm is required: HmacSHA256, HmacSHA512, RSA-SHA256, or something else? [GO]: HmacSHA256
5. Which header carries the signature, and what is its exact format? [GO]: X-Hub-Signature-256: sha256=<hex-hmac-sha256> - for example, X-Hub-Signature-256: sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17
6. Is the signature encoded as hexadecimal, Base64, or Base64URL? [GO]: Hexadecimal
7. What exactly is signed? [GO]: Request Body
Raw body bytes
A body hash
Canonicalized JSON
Method, path, query, timestamp, and selected headers plus body
8. If JSON is signed, are whitespace, property order, line endings, and character encoding significant? [GO]: Yes, all characters in request body should be considered.
9. Is the signature calculated before or after decompression for gzip-encoded requests? [GO]: I suspect it’s the uncompressed request body, but it’s not definitive in the documentation.
10. Does the protocol include a timestamp or nonce to prevent replay attacks? What clock-skew and replay window apply? [GO]: None identified, it’s likely there will be a unique identifier inside the request body, but no specific validation of this is required.
 

I found https://yepcode.io/blog/validate-stripe-webhook-signatures/ (Stripe) and https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md (proposed standard adopted by a few such as Twilio and Zapier) as a couple other examples outside of GitHub.