HMAC Authentication

The IAM service supports an optional HMAC authentication layer for service-to-service communication. When enabled, every inbound request must carry four headers: a client identifier, a millisecond timestamp, a unique request ID, and an HMAC-SHA256 signature computed from a shared secret. The service verifies the signature using a constant-time comparison, rejects replayed requests via an LRU nonce cache, and enforces a configurable clock-skew window.

This layer protects IAM endpoints from unauthorized access by services on the same private network. Without HMAC, any service that can reach the IAM port can call its API. With HMAC, only services that possess the shared secret can produce valid signatures.

How it works

The hmacAuth middleware runs early in the Express middleware chain, before JSON body parsing and cookie parsing. It intercepts every inbound request and validates the four required headers before allowing the request to proceed.

Required headers

Signature computation

The signature is computed over a colon-separated string containing the client ID, timestamp, HTTP method, full request URL (including query string), and the request ID:

base = "{X-Client-Id}:{X-Timestamp}:{METHOD}:{originalUrl}:{X-Request-ID}"
signature = HMAC-SHA256(sharedSecret, base).hex()

For example, a POST request to /auth/user/refresh-session from the billing-service client:

base = "billing-service:1712419200000:POST:/auth/user/refresh-session:550e8400-e29b-41d4-a716-446655440000"
signature = HMAC-SHA256("my-shared-secret", base).hex()

Verification flow

The middleware performs five checks in sequence. The first failure short-circuits the chain and returns HTTP 401 with a reason string.

On success, the request ID is added to the nonce cache with a TTL of maxClockSkew, and the middleware calls next() to proceed to the route handler.

Health check bypass

GET /health requests from localhost (127.0.0.1, ::1, or ::ffff:127.0.0.1) bypass HMAC validation entirely. This allows container orchestrators (Docker, Kubernetes) to run health checks without needing access to the shared secret.

// These requests skip HMAC validation:
// GET http://127.0.0.1:10000/health
// GET http://[::1]:10000/health

Signing requests from a calling service

The calling service must compute the signature using the same base string format and the same shared secret. Here is a complete implementation:

import crypto from 'node:crypto'

function signRequest(
  method: string,
  url: string,
  secret: string,
  clientId: string
): Record<string, string> {
  const timestamp = Date.now().toString()
  const requestId = crypto.randomUUID()
  const base = `${clientId}:${timestamp}:${method}:${url}:${requestId}`
  const signature = crypto.createHmac('sha256', secret).update(base).digest('hex')

  return {
    'X-Client-Id': clientId,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
    'X-Request-ID': requestId,
  }
}

// Usage
const headers = signRequest(
  'POST',
  '/auth/user/refresh-session',
  process.env.HMAC_SECRET!,
  'billing-service'
)

const response = await fetch('https://iam.internal/auth/user/refresh-session', {
  method: 'POST',
  headers: {
    ...headers,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ token: refreshToken }),
})

Rejection handling

When HMAC validation fails, the reject function sends an HTTP 401 response with the reason string as the body. It also logs the rejection with the client ID for audit purposes.

Every rejection is logged at warn level with { Authorized: false, reason, clientId }. Successful validations are logged at info level with { Authorized: true, ClientID, Reason: 'Match' }.

Rotating the shared secret

To rotate the shared secret without downtime, update the services in the correct order:

Middleware mounting

The HMAC middleware is conditionally mounted in the Express application based on the service.Hmac configuration. When the Hmac block is not present (or service is undefined), the middleware is skipped entirely and all requests proceed without signature validation.

// From the service bootstrap (simplified)
if (config.service?.Hmac) {
  app.use(hmacAuth)
}

The middleware is mounted before express.json() and cookieParser(), meaning it runs before the request body is parsed. This is intentional: if the signature is invalid, the service rejects the request without spending resources on body parsing.

Configuration reference

All HMAC settings live under service.Hmac in the configuration.

Summary