Skip to main content

Introduction

Assuming you’ve read the home page, let’s get started.

📋 Prerequisites​

You will need:

  • Java 21 for the microservices (plus Maven)
  • Node.js LTS version (minimum v14) for the React SPA
  • MySQL 9.4 database

Database Setup​

Nidam's default configuration stores user accounts in MySQL. Before starting:

  1. Have MySQL running on port 3306
  2. Create a schema called identity_hub

📦 Repositories​

Nidam is split across several repositories. You’ll run them locally to get the full system working.

1. Registration Service​

https://github.com/Mehdi-HAFID/registration Port: 4000
Handles user sign-ups and saves accounts to your database.

The Registration and Authorization Server need database access. They expect these defaults:

application.yml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/identity_hub
    username: root
    password: "CcmN*`6@3T9H%P#yg^V<7v"
Security Note

These are default development values. Make sure to change them to your own credentials. Update them in both the Registration Service and Authorization Server. The documentation assumes you're using defaults, so if you change them, update them in both:

  • registration/src/main/resources/application.yml
  • token-generator/src/main/resources/application.yml

2. Authorization Server (Token Generator)​

https://github.com/Mehdi-HAFID/token-generator Port: 4002
Handles login, issues tokens, and manages logout. Requires database access.

3. Reverse Proxy​

https://github.com/Mehdi-HAFID/reverse-proxy Port: 7080
Serves everything under the same origin (a requirement). This is the entry point to the system.

4. Resource Server (Nidam)​

https://github.com/Mehdi-HAFID/nidam Port: 4003
Where your backend application code lives. Add your APIs here. Protected by token validation.

5. Backend for Frontend (BFF)​

https://github.com/Mehdi-HAFID/bff Port: 7081
This is the key to the castle. It receives tokens and saves them server-side, associates a session with them, and persists the session as a cookie. All communication between the SPA and Resource Server goes through here. This is why the SPA and BFF must be served under the same origin (hence the reverse proxy).

6. Nidam SPA​

https://github.com/Mehdi-HAFID/nidam-spa Port: 4001
A frontend built with Create React App (CRA). CRA is deprecated, but you can use any SPA (React, Angular, Vue, etc.). Future versions will ship with a Next.js SPA.

The SPA only depends on the URI properties defined in the .env file (or an equivalent configuration source). The same applies to all five Spring services. We’ll cover the details in later sections — for now, we’ll assume the default values.

Running Nidam​

Once you have all repositories cloned:

Starting the Backend Services​

Run each service in sequence (not in parallel) using:

mvn spring-boot:run

Start them in this order:

  1. Registration Service
  2. Authorization Server
  3. Reverse Proxy
  4. Resource Server
  5. BFF
tip

I highly recommend sticking with the default ports when you're just getting started with Nidam. You can customize them later once you're familiar with the system.

Starting the Frontend​

Navigate to the SPA directory and run:

npm install  # First time only
npm start

🎉 Accessing Nidam​

The SPA must always be accessed via the reverse proxy:

✅ http://localhost:7080/react-ui
❌ http://localhost:4001/react-ui

The User Flow​

  1. First Visit to http://localhost:7080/react-ui → Redirected to sign-up page
  2. After Sign-up → Click "Login" → Redirected to authorization server
  3. After Login → Back to the SPA with full access
  4. Behind the Scenes → Tokens are stored server-side, browser only gets a secure cookie

How Components Connect​

The Reverse Proxy is your single entry point, routing to:

  • /react-ui/* → React SPA
  • /auth/* → Authorization Server
  • /bff/* → Backend for Frontend

These services should never be accessed directly.

Only the Registration Service (4000) is called directly by the SPA.

The BFF is the security orchestrator:

  • Stores tokens server-side
  • Adds them to API calls automatically
  • Manages sessions via secure cookies

Architecture​

Here’s the full picture:

Nidam Architecture

Screenshots from a running setup:

sign up login signed in

danger

nidam.com is not owned by me or affiliated with Nidam. Used for demonstration only. Nidam is served exclusively by nidam.derbyware.com.

Troubleshooting Quick Fixes​

ProblemSolution
Database connection errorCheck MySQL is running and identity_hub schema exists
Port already in useMake sure no other services are using ports 4000-4003, 7080-7081
Can't access the appAlways use http://localhost:7080/react-ui, not port 4001
Services won't startStart them sequentially, not all at once

What's Next?​

Next, we’ll dive deeper into configuration and customization to make Nidam yours.