Flow of Microservice Architecture

Syed Wasif Hussain — Sat, 30 Aug 2025 06:49:29 GMT

The Best Practice: Stateless JWTs for Microservices ✅

For a microservice architecture, you are correct that you don't want a central session database that every service has to call. This creates a bottleneck and a single point of failure. The best practice is a stateless JWT flow.

Here’s how it works:

Central Auth Service: You have one dedicated microservice (e.g., auth-service) responsible for user registration and login.
Token Issuance: When a user logs in via the auth-service, it verifies their credentials and issues a signed JWT. This JWT contains the userId and any other relevant, non-sensitive data (like user roles).
Client Storage: The client (e.g., a web browser or mobile app) receives this JWT and stores it.
API Gateway & Service Calls: The client includes the JWT in the Authorization header for all future requests to other microservices (e.g., product-service, order-service).
Stateless Verification: Each microservice has access to the same JWT_SECRET. When a request comes in, the service can independently verify the JWT's signature. If the signature is valid, the service trusts the payload and processes the request. No database call to Redis or a central auth server is needed for verification.

Now elaberating the 5th point:

A Question In my Mind

so each microservice will have jwt_secret in .env ets say authService have ‘kafafjajfljflfajla ‘ this as the secret key and productSerrvice have ‘dshfsaflsajfsafa ‘ this as a secret key in their .env file should the secret key must be same , and also how it will understand that the user is loged in or authenticated.

The secret key must be identical across all services that need to validate the JWT.

The Secret Key: The Master Key 🔑

Think of the JWT_SECRET as a master key for a building.

The auth-service is the only one that can create and issue new master keys (by signing the JWTs).
All other microservices ( product-service, order-service, etc.) are given a copy of that same master key.

If the auth-service signs a token with key-A and the product-service tries to verify it using key-B, the verification will fail. The product-service will conclude that the token is a forgery because it wasn't signed with the one and only master key it trusts.

So, to be crystal clear:

If your auth-service .env has:

JWT_SECRET="kafafjajfljflfajla"

Then your product-service .env must also have:

JWT_SECRET="kafafjajfljflfajla"

They must be exactly the same.

How a Service "Knows" You're Authenticated: The Ticket Analogy 🎟️

This is the key difference between stateful (sessions) and stateless (JWT) thinking. A microservice doesn't "know" a user is logged in in the way a traditional application does.

Instead, it validates proof on a per-request basis.

Let's use a concert analogy:

Logging In (The Ticket Booth): You go to the auth-service (the ticket booth) with your credentials (username/password). It verifies who you are and gives you a ticket (the JWT). This ticket is now your proof of identity.
Accessing a Route (The Concert Hall Entrance): You then go to the product-service (a concert hall entrance). To get in, you must present your ticket (the JWT in the Authorization header).
Authentication (The Usher's Job): The product-service (the usher) doesn't remember you from the ticket booth. It doesn't need to. It just performs two checks on the ticket itself:
- Is the ticket authentic? It checks the signature using its copy of the master key (JWT_SECRET). If the signature is valid, it knows the ticket was issued by the official ticket booth (auth-service) and hasn't been tampered with.
- Has the ticket expired? It checks the expiration date (exp claim) on the ticket.

If your ticket passes both checks, the usher lets you in for that one specific request. The service considers you "authenticated" for that transaction only. For your next request, you must show the ticket again, and it will be re-verified.

The service doesn't maintain a list of "logged-in" users. It simply trusts the verifiable proof (the JWT) that comes with every single request.

Lets understand it with a Simple example :

So basically we are talking about Asynchronous Microservice architecture.

Phase 1: The "Front Door" (Synchronous)

Every user interaction that requires immediate feedback must be synchronous. This is the entry point to your system.

Action: User logs in, user submits an order, user updates their profile.
Mechanism: Standard HTTP Request/Response.
Security: This is where JWT is essential. The server authenticates the user and provides an immediate response (token, 200 OK, 401 Unauthorized).

Imagine we have two microservices:
- Auth Service (runs on localhost:4000): Handles user login and creates JWTs.
- Data Service (runs on localhost:5000): Serves protected data that only authenticated users can access.

Step 1: The Shared Secret (Setup)

Both services need the exact same secret key.

In both the auth-service and data-service project folders, create a .env file:

Code snippet

    # This MUST be identical in both services
    JWT_SECRET="this-is-our-shared-secret-key-12345"

You'll also need to install packages in both projects: npm install express jsonwebtoken dotenv.

Step 2: Auth Service (Creating the Token) 🎟️

This service gives the user their "ticket" (the JWT) after they log in.

auth-service/index.js

JavaScript

    require('dotenv').config();
    const express = require('express');
    const jwt = 'jsonwebtoken';

    const app = express();
    app.use(express.json());

    // A simple login route
    app.post('/login', (req, res) => {
        // For this example, we'll accept any user named "test"
        const { username, password } = req.body;
        if (username === 'test' && password === 'password') {
            // User is valid, create the "ticket" (JWT)
            const userPayload = { userId: 'user123', role: 'customer' };

            const token = jwt.sign(
                userPayload,
                process.env.JWT_SECRET,
                { expiresIn: '1h' } // Token expires in 1 hour
            );

            res.json({ token: token });
        } else {
            res.status(401).send('Invalid credentials');
        }
    });

    app.listen(4000, () => console.log('Auth Service running on port 4000'));

To test this: Run the service and send a POST request to http://localhost:4000/login. You will get a JWT back.

Step 3: The Client (Using the Token)

Now the user's browser (the client) has the token. To get protected data, it sends that token to the Data Service.

Here's how that request looks in JavaScript:

The code is an example of what the client (frontend) does. You would not put this code inside your microservices.

  // The token we got from the /login endpoint
  const myToken = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."; // a long string

  fetch('http://localhost:5000/data', {
      method: 'GET',
      headers: {
          // This is the crucial part
          'Authorization': `Bearer ${myToken}`
      }
  })
  .then(res => res.json())
  .then(data => console.log(data));

Step 4: Data Service (Verifying the Token) 🛡️

This service acts as the "usher" checking the ticket. It uses the shared secret to verify the token it receives.

data-service/index.js

JavaScript

  require('dotenv').config();
  const express = require('express');
  const jwt = require('jsonwebtoken');

  const app = express();

  // Middleware to check the "ticket" (JWT)
  const verifyToken = (req, res, next) => {
      const authHeader = req.headers['authorization'];
      const token = authHeader && authHeader.split(' ')[1];

      if (!token) return res.status(401).send('Access Denied');

      try {
          // Here, it uses the SAME secret to verify the ticket's authenticity
          const verifiedPayload = jwt.verify(token, process.env.JWT_SECRET);
          req.user = verifiedPayload; // Attach user info to the request
          next(); // Ticket is valid, proceed
      } catch (err) {
          res.status(403).send('Invalid Token');
      }
  };

  // A protected route. The verifyToken middleware runs first.
  app.get('/data', verifyToken, (req, res) => {
      // If we reach here, the token was valid.
      // We can safely use the user data attached by the middleware.
      res.json({
          message: 'Here is your protected data!',
          accessedBy: req.user.userId // e.g., "user123"
      });
  });

  app.listen(5000, () => console.log('Data Service running on port 5000'));

The Flow Summarized:

A user sends their credentials to the Auth Service.
The Auth Service validates them and uses the JWT_SECRET to sign and create a JWT. It sends this token back.
The user's browser makes a request to the Data Service, putting the JWT in the Authorization: Bearer header.
The Data Service's middleware intercepts the request. It uses its identical copy of the JWT_SECRET to verify the token.
If verification succeeds, the request is allowed, and the service knows who the user is from the token's payload. If not, it's rejected.

Phase 2: The "Back Office" (Asynchronous)

Once the initial synchronous request is authenticated and accepted, you can then trigger background tasks that don't need immediate user feedback.

Action: Sending a confirmation email, processing a video upload, generating a report.
Mechanism: The API server publishes a job to a message queue like BullMQ, RabbitMQ, or Kafka.
Security: The job payload contains the trusted data (like userId) that was extracted from the JWT during Phase 1. Downstream services trust this data because it comes from an internal, secure source.

So, the flow is exactly as you said:

Synchronous Authentication: Secure the entry points with JWT.
Asynchronous Processing: Pass trusted data internally using message queues to handle background work.

Let's build out "Phase 2" step-by-step using your three services: AuthService, OrderService, and NotificationService.

We will show how the OrderService handles the synchronous request and then passes a job to the NotificationService asynchronously using BullMQ and Redis.

The Scenario
1. AuthService: (Already built) User logs in and gets a JWT.
2. OrderService (Producer): A user submits an order via a synchronous API call. This service validates the JWT, immediately tells the user "Order received," and then adds a send-order-email job to a queue.
3. NotificationService (Worker): This is a background service that does one thing: it listens for jobs in the queue. When it gets the send-order-email job, it processes it (simulating sending an email).

Prerequisites

Redis: You need a Redis server running. The easiest way is with Docker: docker run -p 6379:6379 -d redis
Packages: In your OrderService and NotificationService, you'll need to install a few packages: npm install express jsonwebtoken dotenv bullmq ioredis

Step 1: The Shared Secret & Setup

Just like before, the JWT_SECRET in your .env file must be identical across all three services: AuthService, OrderService, and NotificationService.

In all project folders, the .env file:

The Redis host and port must be the same for every service that needs to communicate through that specific BullMQ queue.

    JWT_SECRET="this-is-our-shared-secret-key-12345"
    REDIS_HOST="localhost"
    REDIS_PORT="6379"

Step 2: The `OrderService` (The Producer 🏭)

This service acts as the bridge. It handles the synchronous request and produces an asynchronous job.

order-service/index.js

    require('dotenv').config();
    const express = require('express');
    const jwt = require('jsonwebtoken');
    const { Queue } = require('bullmq');

    // --- Setup ---
    const app = express();
    app.use(express.json());

    // --- BullMQ Queue Setup ---
    // This connects to Redis and creates a queue named 'email-queue'
    const emailQueue = new Queue('email-queue', {
        connection: {
            host: process.env.REDIS_HOST,
            port: process.env.REDIS_PORT,
        },
    });

    // --- Middleware (Copied from before) ---
    const verifyToken = (req, res, next) => {
        const authHeader = req.headers['authorization'];
        const token = authHeader && authHeader.split(' ')[1];
        if (!token) return res.status(401).send('Access Denied');
        try {
            const verifiedPayload = jwt.verify(token, process.env.JWT_SECRET);
            req.user = verifiedPayload; // Attach { userId, role } to request
            next();
        } catch (err) {
            res.status(403).send('Invalid Token');
        }
    };

    // --- API Endpoint ---
    // This is the synchronous "Front Door" for creating an order
    app.post('/create-order', verifyToken, async (req, res) => {
        const { orderDetails } = req.body;
        const { userId } = req.user; // Get userId from the verified JWT

        console.log(`Order received for user: ${userId}`);

        // 1. Give IMMEDIATE feedback to the user
        res.status(200).json({ message: 'Order received! A confirmation email will be sent shortly.' });

        // 2. Add the background job to the queue (The Asynchronous Part)
        await emailQueue.add('send-order-email', {
            userId: userId,
            orderDetails: orderDetails,
        });
        console.log(`Job added to queue for user: ${userId}`);
    });

    app.listen(6000, () => console.log('Order Service running on port 6000'));

Step 3: The `NotificationService` (The Worker 👷)

This service is a background worker. It doesn't have any API endpoints. Its only job is to connect to the queue and process jobs.

notification-service/index.js

    require('dotenv').config();
    const { Worker } = require('bullmq');

    console.log('Notification Worker is starting...');

    // --- BullMQ Worker Setup ---
    // The worker connects to the SAME queue and processes jobs
    const worker = new Worker('email-queue', async job => {
        // This is the processor function. It runs for every job.
        console.log(`\nProcessing job: ${job.name} (ID: ${job.id})`);

        // Extract the trusted data passed from the OrderService
        const { userId, orderDetails } = job.data;
        console.log(`Data received: User ID -> ${userId}`);

        // Simulate sending an email
        console.log(`Simulating: Sending order confirmation email to user ${userId}...`);
        // In a real app, you would use a service like Nodemailer or SendGrid here
        await new Promise(resolve => setTimeout(resolve, 3000)); // Simulate a 3-second task
        console.log(`Email sent successfully to user ${userId}!`);

    }, {
        connection: {
            host: process.env.REDIS_HOST,
            port: process.env.REDIS_PORT,
        },
    });

    worker.on('completed', job => {
      console.log(`Job ${job.id} has completed!`);
    });

    worker.on('failed', (job, err) => {
      console.log(`Job ${job.id} has failed with ${err.message}`);
    });

How to Run and See the Full Flow

Start Redis: docker run -p 6379:6379 -d redis
Start all three services in separate terminal windows:
- node auth-service/index.js
- node order-service/index.js
- node notification-service/index.js (You'll see "Notification Worker is starting...")

Simulate the Client:

First, get a token (using curl or Postman):

Bash

  curl -X POST -H "Content-Type: application/json" -d '{"username":"test", "password":"password"}' http://localhost:4000/login

This will return a token. Copy it.

Second, create an order: Replace YOUR_TOKEN_HERE with the token you just copied.