DEV Community: martinfernandezcx

Securing Microservices with JWT Validation at the Nginx Proxy Layer

martinfernandezcx — Wed, 28 May 2025 20:16:43 +0000

In a microservices architecture, separating concerns is critical for maintainability, scalability, and security. One key decision when building APIs is how and where to handle authentication. A common pattern is to delegate authentication to a dedicated authentication microservice, which issues tokens (e.g., JWTs), and use those tokens to access protected resources on independent backend APIs. When working on an infrastructure change, we faced the challenge of either integrating authentication in the Node.js backend (without the proper libraries) or maintaining a single backend solely for authorization.

The options we considered were:

Having the Go backend validate the token and proxy to the Node.js backend over authenticated routes. (We tried this, but the Go proxy became messy and difficult to maintain.)
Performing authentication in Node.js (infrastructure restrictions led us to abandon this approach.)
Implementing a different authentication method using the existing infrastructure

And this third one is what we came up with after investigating.

This post demonstrates how to validate JWT tokens directly in Nginx before routing requests to your protected Node.js API, centralizing authorization enforcement at the gateway layer.
This keeps the authentication within the infrastructure boundaries and allows us to simplify both the Go backend and the Node.js backend by relying on the NGINX layer.

Why JWT at the Proxy?

Decouples concerns: Authentication logic doesn't pollute your API code.
Consistent enforcement: All routes must pass the same token checks before hitting backend services.
Performance: Nginx (especially via OpenResty) is efficient and fast at handling token validation.

Options for JWT Validation

Validate JWT in each backend service
- Pros: Full control per service.
- Cons: Repeated logic, potential for inconsistency.
Use Nginx with a third-party JWT module
- Commercial option with NGINX Plus.
Use OpenResty (Nginx + Lua) with lua-resty-jwt
- Open-source, flexible, and efficient.

OpenResty + Lua

We use OpenResty and the lua-resty-jwt library to inspect JWTs in the Nginx layer. If valid, we forward requests to the backend. Otherwise, Nginx returns a 401 response.

Architecture

auth-api: issues JWTs via login endpoint.
node-api: protected and public routes.
nginx: gateway with Lua-based JWT validation.

Security Considerations

Some of these concerns were left out of this POC but we would like to mention for a proper production implementation. Please read through and evaluate wether it fits to your scenario or not.

Protection Against Common Attacks

Replay Attacks
- Implement token expiration (exp claim)
- Use short-lived tokens (15-60 minutes)
- Consider implementing a token blacklist for revoked tokens
- Use nonce values in token claims
- Implement request timestamp validation
Token Theft Prevention
- Always use HTTPS for token transmission
- Implement secure cookie attributes (HttpOnly, Secure, SameSite)
- Use token binding to prevent token reuse
- Implement rate limiting on authentication endpoints
- Monitor for suspicious patterns (multiple failed validations)

Token Expiration Best Practices

Short-lived Access Tokens
- Set expiration time between 15-60 minutes
- Use refresh tokens for longer sessions
- Implement sliding expiration for active users
Refresh Token Strategy
- Longer expiration (days/weeks)
- Store refresh tokens securely
- Implement refresh token rotation
- Maintain a refresh token family tree
Expiration Implementation

   -- Example of expiration check in Lua
   local jwt = require "resty.jwt"
   local validators = require "resty.jwt-validators"

   validators.set_system_leeway(0) -- Strict time validation
   validators.register_validator("exp", validators.opt_is_not_expired())

Grace Period Considerations
- Implement a small grace period (30 seconds) for clock skew
- Handle token expiration gracefully
- Provide clear error messages for expired tokens
- Implement automatic token refresh when possible

Project Layout

You can find the full source here:

GitHub Repo: martinfernandezcx/NGINXAUTH

How It Works

Client logs in via /api/auth/login, receives JWT.
Client sends Authorization: Bearer <token> on protected requests.
Nginx runs a Lua script to:
- Check token structure.
- Validate signature and expiration.
- Inject user ID into a request header.
Validated requests reach the Node.js service with identity attached.

Testing with Postman

The project includes a comprehensive Postman test suite to verify the JWT authentication flow and API endpoints. The test suite covers authentication, public routes, and protected routes with various scenarios.

Test Suite Structure

The Postman collection (postman/jwt-nginx-auth-tests.json) includes:

Authentication Tests
- Login endpoint validation
- Token format verification
- Automatic token storage for subsequent requests
Public Endpoint Tests
- Access to public routes
- Response format validation
Protected Endpoint Tests
- Access without token (401)
- Access with invalid token (401)
- Access with valid token (200)
- Response payload validation

Running the Tests

Prerequisites
- Install Postman
- Start the application:
```
 docker-compose up --build
```
Import the Collection
- Open Postman
- Click "Import" button
- Select the postman/jwt-nginx-auth-tests.json file
- select the postman\environment.json file
- The collection will be imported with all test cases
Run the Tests
- Select the "JWT Nginx Auth Tests" collection
- Click the "Run" button
- Postman will execute all tests in sequence
- View test results in the Postman console
Test Flow
- Tests run in a specific order to ensure proper token handling
- Login test stores the token for subsequent requests
- Protected route tests verify token validation
- Each test includes assertions for status codes and response formats

Test Cases break down

Login Test

   pm.test("Status code is 200", function () {
       pm.response.to.have.status(200);
   });
   pm.test("Response has token", function () {
       var jsonData = pm.response.json();
       pm.expect(jsonData).to.have.property('token');
   });

Protected Route Test

   pm.test("Status code is 200", function () {
       pm.response.to.have.status(200);
   });
   pm.test("Response contains protected data", function () {
       var jsonData = pm.response.json();
       pm.expect(jsonData).to.have.property('message');
   });

Environment Variables

The test suite uses Postman environment variables:

auth_token: Automatically set after successful login
Used in subsequent requests to protected routes

Continuous Integration

The Postman collection can be integrated into CI/CD pipelines using:

Newman CLI tool
Postman's CI/CD integrations
Custom test runners

Example Newman command:

newman run postman/jwt-nginx-auth-tests.json -e postman/environment.json

Running the tests

To run the tests you can use npm run test:postman:cli, or import both files on postman and run it there as mentioned above.

Conclusion

Centralizing JWT validation in the proxy simplifies backend services, enforces uniform security, and keeps authentication logic out of each microservice. This pattern is ideal for architectures using distinct auth and business logic APIs.

In contrast, validating tokens in the Node.js API itself might allow greater control over roles or context-based access logic but at the cost of duplication and potential inconsistency.

OpenResty strikes a solid balance between performance, flexibility, and maintainability in JWT-based authentication.

Apendix-A: Problems Found and Solutions

During the implementation of this JWT authentication system, we encountered several issues that required specific solutions:

OpenResty Dependencies
- Problem: Missing Perl and curl in the OpenResty Alpine image
- Solution: Added required packages in Dockerfile:
```
 RUN apk add --no-cache perl curl
```
Nginx User Configuration
- Problem: Missing nginx user in the container
- Solution: Created nginx user and group:
```
 RUN addgroup -S nginx && adduser -S -G nginx nginx
```
MIME Types Configuration
- Problem: Missing mime.types file in OpenResty Alpine image
- Solution: Created custom mime.types file and copied it to the correct location:
```
 COPY mime.types /etc/nginx/mime.types
```

Lua Package Path

Problem: Lua package path directive in wrong context
Solution: Moved lua_package_path to http context in nginx.conf:

 http {
     lua_package_path "/usr/local/openresty/lualib/?.lua;;";
     lua_package_cpath "/usr/local/openresty/lualib/?.so;;";
 }

Log Directory Permissions
- Problem: Nginx couldn't write to log directory
- Solution: Created log directory and set proper permissions:
```
 RUN mkdir -p /var/log/nginx && \
     chown -R nginx:nginx /var/log/nginx
```
Unit tests and routes issues
- Problem: Postman tests were failing with 404 on /protected
- Solution: Changed auth-api/index.js /login route and node-api/index.js /protected to /user

These solutions ensure proper functionality of the JWT authentication system while maintaining security and following best practices for containerized applications.

Performance Testing: Why, When, and What

martinfernandezcx — Tue, 03 Oct 2023 19:43:32 +0000

Overview

When you have an application, regardless of whether it's in production or not, there comes a point when you need to perform performance testing. You might start by searching for various paid services, free tools that are rather difficult to understand, and concepts like load testing, spike testing, stress testing, and more.
Let's try to clarify this matter and provide a useful walkthrough with a live example.
If you have an API, performance can be divided into two sections: internal and external. Internal performance should evaluate memory allocation, the number of threads, disposed objects, etc. External performance is related, but it measures response time, the number of accepted requests, etc.
Let's focus on the external performance for now.

The WHY

We perform performance testing for two main reasons, among others: verification and detection. For verification, we intend to check whether the application fulfills the expected demand, and for detection, we test to verify if the application breaks, and at what load. This latter test can be executed when the boundaries are not clear enough or to test the app's behavior outside the usage boundaries, usually above the maximum level. This is really useful when we are trying to prepare for eventual spikes or future increases in demand.

The WHEN

We perform performance testing once we know the expected usage of the app at the point of going into production. We run it before going into production and during production.
However, we do not run it with every release, do we? This decision depends on various factors: the environment, your needs, the team you have to perform these tests, the criticality of the affected areas of that release, and the application itself.

The WHAT

This is the most crucial part. Location, location, location.

Before you start

Things you need to know BEFORE you start thinking about performance, and the first one is boundaries.
What do we understand by boundaries? Well, boundaries are the limits your application will hit when running.

Going back to boundaries and regarding external testing of an API, what you need to know in advance is:
- How many requests per second are you expecting, both maximum and minimum?
- Are you expecting load peaks? How many? At what times? For how long?
Without this information, then running performance tests makes less sense as you don't have a comparison point.

Nice, you got the info? Then it's time to start doing setups.
Well, not there yet. First, you have to draft a plan.

The plan

To draft a plan, you need to consider the types of performance testing and decide on your objectives.
Most commonly, you can:
- Load test
- Spike testing
- Stress test
- Mixed
Each strategy has its benefits and drawbacks, and this is tightly bound to what you want to test.

All of these are usually composed of the start-up, the load, and the tear-down phases.

The start-up

There are several ways to do this. You can use a step-up/down pattern, linear increase (even varying the steepness), or you could use exponential increase/decrease.

Step up in 4 phases

Important things to note here:
You have a target of virtual users; each one of them will run one or more requests based on your configuration and your needs. As you can see here, we are targeting 1000 virtual users, from 0 to 1000 in 16 minutes, and then holding for 30 minutes and tearing down again in 15 minutes.

In this case, we were testing for a breaking point, which we found at 500 virtual users. This is also called a Load test pattern, as the heaviest load will occur during sustained time, and we will test how the servers behave when load is held, besides the advantage it provides if you don't know your boundaries.

If you already know your limits, then you can plan differently like:

As you can see, the pattern is different, and it's targeting different results.
The former one is increasing by steps so we can measure at different moments in time and also check for infrastructure changes and responses (pods warming up, memory allocation, processor, etc.)
The latter one increases directly to the top, holds, and then decreases. Here, the target could be evaluating if we have memory leaks or if the processor can spawn multiple threads and so on. Numerous metrics can be evaluated, and it will depend on what you are looking for. I'm just mentioning the common ones.

The hold

At this stage is where you want to decide if you want to hold, for how much time, if you will have spikes, how many, how long? How steep?

For instance, the next image shows a holding pattern interrupted by a 4x peak.

At this point, we may want to check container warm-up, horizontal and vertical scaling, failure recovery, and so on, given that the spike increase is really fast; these are the common breaking points (network and scaling).

The Tear down

Once you have verified the behavior under load or spikes, it's time to let the services cool down, for the same reason that we stepped in; we want to do the tear down to check how the infrastructure is reacting. It could be memory analysis, how much and how fast it got cleared? How fast instances stopped? And etc…

Real-life config

Now, all of this is fine, but WHAT are we testing?? This, of course, varies according to your project. Let's begin by testing a specific endpoint, shall we?
To test an endpoint is basically configuring the given tool to perform a GET/POST/PUT. In this case, I'm going to show how to run a GET to a specific API endpoint.

Let's use, for this purpose, jMeter.
By default, JMeter has some tools to assemble a query such as thread groups, but there are also some cool plugins that we will be using:

Start by installing the custom threads group that contains the Ultimate thread group. By using this plugin, you will be able to configure the steps you want and many other options.
Second, add some graph generators of your choice.

Once you have done this, create a test plan and add an Ultimate thread group.
The thread group should consist of the following components at a minimum:

The HTTP Request
- Then here, I'm adding input data from a CSV to send query parameters, a Header manager to send a basic auth token, and a throughput timer.
Let's break it into pieces:
- The HTTP request is pretty self-explanatory:
- You have the name
- Protocol
- Server
- Path
- Verb
- And other parameters like port, etc.
Then there are config elements, the first one is the CSV file input
Then the HTTP header manager
- This is optional and also provides options for basic, JWT, and all the other headers you need to add.
Third is the throughput. Here is where you also handle the load. It's not the same to have 1000 VU with 1000 requests per minute per user than having 1 request per second per VU.

As you can see in the image:

We are sending a maximum of 1 request per second per VU. The options here allow you to set an amount shared across all VUs or per VU, as seen in the image.

Wrapping up and information analysis

Once the process has completed, it's time to look at the graphs and see what information is being presented and our pain points and the need to improve items. Some results from the previous configuration:

Response time and threads

This is calculating the average time based on the number of VUs. As you can see in the image, it was averaging 22 seconds for a simple GET.

200 responses and threads

Here, you'll notice two key points: the performance under constant throughput and the variance in 200 responses.
If you add to this the following image:

Errors and threads

We can see that when reaching about 500 VU, the number of 502 and 504 errors started increasing.
Further analysis revealed that our instances were not able to handle the load, and we determined that horizontal scaling combined with a small increase in resources on the actual pods would solve the problem, as you will see in the following image, that for the same pattern of load, the number of errors drastically reduced.

Conclusion

When running performance analysis, it's really important to know what you will be looking for. Second, of course, is K.I.S.S. You don't need fancy graphics or complicated-to-configure tools, just go simple and straightforward.
Then, make sure you capture all that's important to you and also compare it to the hardware metrics (not covered in this demo) so you can add graphs, logs, and hardware metrics to get a great combo and know what you need to improve.
And last but not least, double-check and triple-check your findings. Running performance tests should be done in isolated environments, but if that is not possible, and you will target staging/UAT, make sure you have two or three runs at different times of the day so you can evaluate your results as well and compare.
Hopefully, this post will aid you in running your first set of performance tests.

Good Luck.
this article was fully written by a person, based on a live example and experience and not by an AI