The Cornerstone of Trust: Why JWS Matters

(Figure 1: JWS Asymmetric Flow for Distributed Trust)

We have graduated from "using" error messages to "configuring" the core security mechanisms. This article is for the senior engineers and DevOps teams responsible for managing a digiRunner instance.

Recall the "Invalid Signature" 401 error from Part 2. That error is actually a success story: it means the JWS (JSON Web Signature) mechanism is working. JWS is the cornerstone feature that guarantees a token's integrity.

The security relies on an asymmetric flow:

Sign: digiRunner (as the Auth Server) signs the token using a Private Key.
Verify: digiRunner (as the Gateway) verifies the token using the corresponding Public Key.
Distributed Trust: Crucially, downstream microservices can also use that Public Key to verify tokens independently.

How digiRunner Manages Private Keys (Configuration as Security)

(Figure 2: Configuration as Security in OpenTPI)

digiRunner avoids hardcoding keys. Instead, it employs a "Configuration as Security" model using a KeyStore file (e.g., JKS format).

To configure the JWS signing key, you must define the following properties in your configuration file. These settings determine which key is used to generate tokens:

digiRunner.token.key-store.path: Specifies the directory path where the KeyStore file is located (Default: keys).
digiRunner.token.key-store.name: Specifies the filename of the KeyStore (Default: opendgr-token.jks).
digiRunner.token.key-store-password: The password required to access the KeyStore.
digiRunner.token.keyAlias: The specific alias for the private key within the KeyStore (Default: opendgr-token).
digiRunner.token.keyStoreType: The type of KeyStore used (Default: JKS).

DevOps Best Practice: This design allows you to manage the KeyStore file and password as Kubernetes Secrets or Docker Secrets, mounting them at runtime. This completely decouples "security" (key rotation) from "development" (application code).

Step-by-Step Guide: How to Rotate Your JWS Private Key

(Figure 3: 3 Steps for JWS Key Rotation)

Key rotation is a critical compliance requirement. Here is the operational guide for system administrators to rotate keys in digiRunner:

Prepare a New KeyStore: Generate a new key pair (public and private) and save it as a new KeyStore file (e.g., new-core-token.jks).
Update Configuration: Place the new file in the configured path and update the properties (name, password, alias) to point to the new credentials.
Restart digiRunner: Since these are property-level settings, you must restart the digiRunner instance for the changes to take effect.

The "Aha!" Moment: Public Key Exchange and Zero-Trust

(Figure 4: Zero-Trust Public Key Exchange Architecture)

How does a downstream microservice know the signature is valid without calling the Gateway every time?

digiRunner provides a discoverable endpoint that enables Zero-Trust architecture. Clients and services can query the following endpoint to retrieve the current Public Key:

https://{dgr-ip}:{dgr-port}/dgrv4/ssotoken/enccert

This design is extremely powerful. A downstream microservice (like a Spring Boot app) can fetch this public key on startup, cache it, and independently verify the integrity of every JWT it receives. It does not need to blindly trust the Gateway; it can mathematically prove the token's validity itself.

Series Conclusion: Building Resilient Systems

Over this four-part series, we have journeyed from frustration to mastery:

Part 1: We identified the pain of vague "401" errors and the need for better Developer Experience (DX).
Part 2: We learned to distinguish "Authentication Failures" and fix expired or tampered tokens.
Part 3: We mastered "Authorization," understanding the nuance of 403 Forbidden and scope permissions.
Part 4: We established the cryptographic foundation of trust (JWS) that makes the entire ecosystem secure.

digiRunner is an open-source platform designed for engineers. It respects your time, enhances your debugging workflow, and provides the robust, configurable security needed for modern AI and FinTech applications.

FAQ:

1. What is JWS in digiRunner?

JWS (JSON Web Signature) is the cornerstone security mechanism that guarantees a token's integrity using an asymmetric flow.

2. How does digiRunner verify tokens asymmetrically?

The Auth Server signs the token with a Private Key, while the Gateway and downstream microservices verify it using the corresponding Public Key.

3. How does digiRunner manage private keys securely?

It employs a "Configuration as Security" model, storing keys in a KeyStore file (like JKS) configured via properties to avoid hardcoding.

4. What is the DevOps best practice for digiRunner KeyStores?

Mount the KeyStore file and password as Kubernetes or Docker Secrets at runtime, completely decoupling security from application code development.

5. How do you rotate JWS private keys in digiRunner?

Generate a new KeyStore, update the configuration properties with the new credentials, and restart the digiRunner instance to apply changes.

6. How do downstream microservices verify tokens independently?

They fetch and cache the Public Key from digiRunner's discoverable endpoint, mathematically proving the JWT's validity without querying the Gateway.

7. Which endpoint provides the Public Key for Zero-Trust?

Microservices can retrieve the current Public Key by querying this specific discoverable endpoint: https://{dgr-ip}:{dgr-port}/dgrv4/ssotoken/enccert

Securing Microservices: Configuring JWS Key Rotation and Zero-Trust in digiRunner