A Short Overview

The easiest way to get a feel for Nidam is to run it.

Try Nidam

1. Download Nidam

Download the package for your platform and architecture, then extract the archive.

Platform	Architecture	Package
🪟 Windows	x64	Windows x64
🪟 Windows	arm	Windows arm
🐧 Linux	x64	Linux x64
🐧 Linux	arm	Linux arm
🍎 macOS	arm	I don't own a mac, I will try to figure a way to provide the binary

Source Code Github

2. Start Nidam

The commands and examples in this documentation use Windows as the operating system. If you are using Linux or macOS, adapt the commands and paths to your environment accordingly.

On Windows, open a PowerShell window, navigate to the extracted directory, and run:

.\nidam-launcher.ps1 start

The launcher starts the Nidam components and opens a browser tab pointing to the Nidam SPA.

By default, the SPA is available at:

http://localhost:7080/spa

3. Create an Account

The demo starts with an empty database, so the first step is to create a user.

Enter an email address and password, then enter the password again in the confirmation field. Accept the terms and conditions and click Sign up.

You should see:

You're successfully registered

You can now sign in using the credentials you just created.

Click Already have an account? Sign in, enter the same credentials, and click Sign in.

After a successful login, you will be redirected to:

http://localhost:7080/spa/secret

This is an SPA page that is accessible only to authenticated users.

4. See Authorization in Action

The Secret page makes two calls to the backend:

/demo
/top-secret

The results demonstrate the difference between authentication and authorization.

/demo returns:

200 OK

while /top-secret returns:

403 Access Denied

Why?

Users created by default are assigned the following authorities:

manage_users
manage_projects

The /demo endpoint requires the caller to have either manage_users or manage_projects, so the request succeeds.

The /top-secret endpoint requires the top-secret authority. Since newly created users do not have that authority, the request is rejected with 403 Access Denied.

This small example gives you a glimpse of how Nidam can handle both authentication and authorization for your application.

5. So, What Does Nidam Actually Do for You?

The demo you just ran uses Nidam's own sample backend and frontend. In a real application, those do not have to be yours.

You can tell Nidam to work with:

• your own backend
• your own frontend SPA
• your own database
• your own authorities

Your backend can use whichever framework you prefer. Nidam does not care whether it is Spring, .NET, Node.js, Go, Python, or something else entirely.

The same applies to your frontend. You can use React, Next.js, Angular, Vue, or any other frontend technology.

Your users can be stored in an SQL database or in MongoDB.

For highly available deployments, Redis can be used to store OAuth 2.0 objects, and Nidam itself can also be deployed in a High Availability configuration.

6. OAuth 2.0 Without the Heavy Lifting

Implementing OAuth 2.0 properly involves a lot of moving parts: authorization flows, tokens, sessions, clients, redirect URIs, security considerations, and more.

Nidam handles that complexity for you.

It also follows the Backend for Frontend (BFF) pattern. This means your SPA does not receive the OAuth access token directly. Nidam's BFF handles the OAuth tokens on the server side and forwards authenticated requests to your backend.

You can see this for yourself.

On the Secret page, open your browser's Network tab, then click either of the buttons that calls a backend endpoint, and inspect the request.

You will see the browser communicating with the BFF rather than receiving a JWT access token itself.

For more information about the BFF architecture, see the OAuth 2.0 for Browser-Based Applications RFC, particularly the section covering the Backend for Frontend (BFF) pattern.

7. What You Just Ran

The default Nidam bundle includes:

• Spring for the backend
• React for the SPA
• H2 as the embedded database

These components are provided to give you a complete, ready-to-run Nidam experience out of the box. They are not requirements for your own application — you can replace them with your preferred backend, frontend, and database.

The purpose of the default bundle is to let you experience Nidam's authentication and authorization flow immediately, without having to configure your own application first. Nidam handles the OAuth 2.0 complexity behind the scenes, so you can focus on your application.

Using Your Own Backend, Frontend, and Database

The default Nidam bundle gives you a complete application out of the box. You can now start replacing its components with your own.

We will do this in three steps:

1. Use your own backend.
2. Use your own frontend.
3. Use your own database.

At the end, you will have a setup where your application provides the backend, frontend, and user database, while Nidam handles the OAuth 2.0 flow and the Backend for Frontend (BFF) layer.

Backend

Let's start by replacing Nidam's included resource server with your own backend.

For this example, we will use Node.js with Express. Nidam provides three Node.js/Express examples that you can use:

• Node.js Express — Variant 1
• Node.js Express — Variant 2
• Node.js Express — Variant 3

Download one of the variants.

First, stop the running Nidam bundle:

.\nidam-launcher.ps1 stop

Now start Nidam again without its included resource server.

The resource server is the component named nidam and runs on port 4003. The overall project is also called Nidam, so the name can be a little confusing at first. In this documentation, Nidam refers to the overall software, while nidam refers to the included Spring Boot resource server.

Start Nidam without that resource server:

.\nidam-launcher.ps1 start -Exclude nidam

The startup output should now show six of the seven services:

Ports:
    H2:                 9092
    Registration:       4000
    SPA:                4001
    Token Generator:    4002
    Reverse Proxy:      7080
    BFF:                7081

Notice that the Nidam resource server on port 4003 is no longer running.

Now open a command-line window in the directory of the Node.js variant you downloaded and run:

npm install
npm start

Your Node.js/Express backend is now running in place of Nidam's included resource server.

Open:

http://localhost:7080/spa

and sign in using the account you created earlier.

The frontend is still the one included in the default bundle, but the backend serving your protected resources is now Node.js/Express.

Other Backend Examples

Nidam also provides examples using:

ASP.NET, Go, Python FastAPI, Micronaut, Jakarta EE / MicroProfile / Open Liberty, and Node.js / Express.

These projects are examples and sources of inspiration. They demonstrate how different technologies can integrate with Nidam; they are not frameworks you are required to use.

You are free to implement your backend using any language or framework you choose. Nidam only requires your resource server to implement the contract described in the following pages. As you will see, there is not much to it.

Nidam's own resource server is implemented with Spring Boot and is production-ready. If you are building a Spring-based application, you can use it as a reference or adapt its implementation to your own application.

The backend examples also illustrate an important distinction: some frameworks provide native support for acting as an OAuth 2.0 Resource Server, such as ASP.NET, Micronaut, and MicroProfile. Others, such as Go, Node.js, and Python, do not provide the same functionality out of the box and require you to implement or add the necessary OAuth 2.0 support yourself.

Frontend

At this point, Nidam is running without its own resource server, and your Node.js/Express backend is running instead.

The next step is to replace Nidam's included React SPA with your own frontend.

First, stop Nidam's included SPA:

Stopping the included SPA

.\nidam-launcher.ps1 stop spa

You can also keep using Nidam's own resource server if you prefer. In that case, simply stop the SPA and leave everything else running.

When Nidam is not already running, you can start the bundle without the included SPA with:

Start Nidam without the included SPA

.\nidam-launcher.ps1 start -Exclude spa

Now download the Next.js example.

Open a command-line window in the project directory and run:

npm install
npm run dev

The Next.js application is now running as your frontend.

Open:

http://localhost:7080/spa

and sign in as before.

The Next.js example intentionally has the same visual appearance as Nidam's React SPA, so the user experience looks almost identical. The implementation, however, is completely different.

You are now running Nidam with your own backend and your own frontend.

The remaining component is the database that stores your users.

Database

The default Nidam bundle uses an embedded H2 database. This is convenient for getting started, but you can use an external database for your application.

Nidam supports the following SQL databases:

MySQL, PostgreSQL, MariaDB, Microsoft SQL Server, Oracle Database, and IBM DB2.

It also supports MongoDB.

For the databases listed above, Nidam's native support means that you provide the database URL, username, and password, and Nidam handles the connection and persistence.

Let's replace H2 with MySQL.

First, stop Nidam:

Stopping Nidam

.\nidam-launcher.ps1 stop

Your MySQL server must already be running before you start Nidam. Otherwise, Nidam will not be able to connect to the database and will fail to start.

Create a database for Nidam. In MySQL terminology, this is commonly referred to as a schema.

For this example, we will use:

identity_hub

The Nidam folder already includes a configuration.yml file in its root directory. Open the file and configure it for your MySQL database.

This file is where you configure Nidam for your environment.

Set the MySQL connection properties:

configuration.yml

users-db-url: jdbc:mysql://localhost:3306/identity_hub
users-db-user: root
users-db-password: "your-password"

Because we are now providing the backend and frontend ourselves, we also need to exclude the components supplied by the default bundle:

• nidam — Nidam's included resource server
• spa — Nidam's included React SPA
• h2 — the embedded H2 database

Start Nidam without those components:

Start Nidam with your backend, frontend, and MySQL database

.\nidam-launcher.ps1 start -Exclude nidam,spa,h2

Alternatively, you can keep using Nidam's own backend and frontend and replace only the database. In that case, exclude only H2:

Start Nidam with its included backend and frontend, using MySQL

.\nidam-launcher.ps1 start -Exclude h2

Open:

http://localhost:7080/spa

The new MySQL database is empty, so the user you created earlier in H2 is not present. Create a new account and sign in.

You are now running Nidam with:

• your own backend
• your own frontend
• your own user database

while Nidam continues to handle the OAuth 2.0 authentication flow and the Backend for Frontend (BFF) layer.

Because Nidam follows the BFF pattern, your frontend never receives the JWT access token. The OAuth 2.0 tokens remain on the server side, while your frontend communicates with the BFF.

In other words, you choose the technologies that make up your application. Nidam takes care of the OAuth 2.0 plumbing between them.

When a Nidam Port Is Already in Use

Nidam uses the following ports by default:

Service	Port
H2	9092
Registration	4000
SPA	4001
Token Generator	4002
Nidam (Resource Server)	4003
Reverse Proxy	7080
BFF	7081

Most of the time, you can simply start Nidam using the commands shown in this introduction. However, one or more of these ports may already be in use by another application on your machine.

When that happens, open the configuration.yml file included in the root directory of the Nidam bundle and change the port for the service that is causing the conflict.

For example:

configuration.yml

h2-embedded-port:       2029
registration-port:      2030
react-port:             2031
authorization-server-port: 2032
resource-server-port:   2033
reverse-proxy-port:     2034
bff-port:               2035

You only need to change the ports that are already in use. Once you have saved the configuration, start Nidam normally.

The ports used by each service are printed during startup, so you can always see exactly which ports Nidam is using.

Result

At this point, you have seen both the default Nidam setup and how its components can be replaced with your own:

	Nidam Setup	Your Setup
Backend	Spring	Node.js / Express
Frontend	React CRA	Next.js
Database	Embedded H2	MySQL

The components in the right-hand column are only examples. You can use whichever backend, frontend, and database technologies you prefer.