Skip to main content

Secure Server-to-Server Communication

When building a distributed system where the Archibald backend must communicate with external APIs (like SAP Commerce or CDC) or other internal microservices, you must distinguish between User Sessions and Service Identity.

JWE vs. JWT in Archibald​

It is important to understand which technology to use based on the communication path:

  • User to Server (JWE): Archibald uses JSON Web Encryption (JWE) for user sessions (the nct cookie). JWE encrypts the payload so it cannot be read by the client. This is used to protect user privacy.
  • Server to Server (Signed JWT): For communication between services, Archibald typically uses Signed JSON Web Tokens (JWT). These tokens are not necessarily encrypted, but they are digitally signed using a private key (RS256) to prove the identity of the calling service.

Best Practices​

Use Signed JWTs for Identity​

When your Archibald backend calls a service like SAP CDC, it uses the createSignedJWT utility from @archibald/auth. This proves to the external system that the request is coming from your authorized application.

// Example: Generating a signed JWT for an external service
import { createSignedJWT } from '@archibald/auth';

const token = await createSignedJWT(privateKey, { kid: userKey });

Validate Tokens on the Receiver Side​

If you are building a custom microservice that receives requests from Archibald:

  1. Check the Signature: Use a library like jose or jsonwebtoken and the public key of the Archibald server to verify the token hasn't been tampered with.
  2. Validate Claims: Check the iat (issued at) and exp (expiration) claims to prevent replay attacks.

Use API Keys for Public Ingress​

For internal services exposed to the public internet but intended for specific partners, use API Keys (secrets) passed in custom headers. Ensure these keys are stored as secrets in your environment configuration and never committed to code.

Network Level Security (mTLS)​

Whenever possible, supplement token-based security with network-level protection like Mutual TLS (mTLS) if you are running in a service mesh (like Istio/Linkerd), ensuring that only authorized containers can physically talk to each other.

By combining JWE for user privacy and Signed JWTs for service identity, you create a robust, multi-layered security architecture.