Skip to main content

Advanced Features

High Availability​

Nidam consists of multiple services that work together as one system. For high availability (HA), you can run multiple instances of selected services:

  • token-generator
  • bff
  • registration

The following example demonstrates how to run an additional token-generator instance on another machine and configure Nidam's reverse proxy to distribute requests across both instances. It also explains how to secure communication with the additional instance using HTTPS.

Prerequisite: Enable Redis​

Before configuring high availability, you must run Nidam in Redis mode.

In configuration.yml, set:

nidam:
  session-mode: redis

See Redis configuration for details.

Run an additional token-generator instance​

1. Prepare the deployment package​

This example uses two machines on the same local network:

  • Machine 1: The original Nidam installation, at 192.168.1.3.
  • Machine 2: The additional token-generator instance, at 192.168.1.8.

The original installation must be reachable from the other machine. For this example, the relevant properties in Machine 1's configuration.yml are:

Nidam configuration.yml
host: http://192.168.1.3
host-origin: 192.168.1.3

The host property defines Nidam's client-facing origin. The host-origin property is used by two internal connection URLs, the default Redis and H2 database URLs.

For example, the default token-generator internal URLs are:

redis-url: redis://:mehdi@${host-origin}:6379
users-db-url: jdbc:h2:tcp://${host-origin}:${h2-embedded-port}/identity_hub

Setting host-origin to 192.168.1.3 allows these services to use the original machine's network address rather than localhost.

If you have already configured explicit database and Redis URLs for your environment, setting host-origin is redundant. Use the appropriate connection settings for your deployment.

Important: Nidam must have been started at least once before you create the package. On its first startup, Nidam creates the key folder containing the JWK signing key material required by the token-generator.

Assume Nidam is running on Machine 1, and you want to run an additional token-generator instance on Machine 2.

Nidam provides the nidam-ha.ps1 script to prepare a ZIP archive containing the files required to run the additional instance.

From your Nidam installation directory on Machine 1, execute:

.\nidam-ha.ps1 token-generator

The script creates a ZIP archive containing:

  • token-generator-2.0.0.jar
  • configuration.yml
  • jdbc/ folder
  • key/ folder
  • runtime/ folder
  • token-generator-ui/ folder

Copy the ZIP archive to Machine 2 and extract it into a directory of your choice.

2. Configure the additional instance​

The additional instance must listen on a port that is available on its host.

If both instances run on the same machine, assign each instance a different port. For example:

Additional instance configuration.yml
authorization-server-port: 4010

If the additional instance runs on Machine 2 and port 4002 is available, you can keep the default port.

The two instances must use compatible configuration and shared resources. In particular, keep the following consistent with the original instance:

  • Database connection settings and credentials.
  • Password encoders.
  • OAuth client credentials and related OAuth configuration.
  • Redis configuration.
  • The same signing key material.
  • Rate-limiter settings, if customized.
  • Token TTL settings, if customized.
  • nidam.persistence-mode, if using MongoDB.

The additional instance must connect to the same shared database and Redis deployment as the original instance. Both instances must also use the same signing key.

The deployment script carries the original configuration.yml into the archive. You can trim the additional instance's configuration to the properties it actually needs.

For this example, the resulting configuration is:

final Instance 2 configuration.yml
host: http://192.168.1.3
host-origin: 192.168.1.3

authorization-server-port: 4010

nidam:
  session-mode: "redis"

The host and host-origin values continue to reference the original Nidam installation. Only authorization-server-port changes because the additional instance listens on a different port.

Also, you can remove, if used, nidam.protocol: https the entry only relates to Nidam reverse proxy, not token-generator, bff or registration services

3. Start the additional instance​

Open a PowerShell terminal in the directory where you extracted the ZIP archive.

For any database configuration except for Oracle and IBM, run:

runtime\bin\java.exe -jar token-generator-2.0.0.jar --spring.profiles.active=prod

If you use Oracle, load the JDBC driver from the bundled jdbc/oracle/ directory:

runtime\bin\java.exe "-Dloader.path=jdbc/oracle/" -jar token-generator-2.0.0.jar --spring.profiles.active=prod

If you use IBM Db2, use:

runtime\bin\java.exe "-Dloader.path=jdbc/db2/" -jar token-generator-2.0.0.jar --spring.profiles.active=prod

Run these commands from the extracted deployment directory so that the relative paths resolve correctly.

4. Register the additional instance with the reverse proxy​

Next, configure the reverse proxy on Machine 1 to discover the additional instance.

Open the original Nidam installation's configuration.yml and add the additional instance to the token-generator list:

Nidam configuration.yml

---

spring:
  config:
    activate:
      on-profile: reverse-proxy
  cloud:
    discovery:
      client:
        simple:
          instances:
            token-generator:
              - uri: ${authorization-server-uri}
              - uri: http://192.168.1.8:4010/auth

The two entries represent:

  • ${authorization-server-uri} — the original token-generator instance.
  • http://192.168.1.8:4010/auth — the additional instance on Machine 2.

Machine 2 local ip address is 192.168.1.8.

Important: Do not remove the --- separator. It separates the reverse-proxy-specific HA configuration from the rest of configuration.yml. Without it, the profile condition can affect the wrong configuration document, potentially preventing other Nidam services from starting.

The port is determined by authorization-server-port in the additional instance's configuration. If that property is not defined, the default port is 4002.

To register a third instance, add another entry to the list. For example:

- uri: http://192.168.1.9:4011/auth

Use the appropriate hostname and port for each instance.

5. Restart the reverse proxy​

After updating the configuration, restart only the reverse proxy so that it reloads the instance list:

.\nidam.ps1 restart -Exclude nidam,spa,bff,h2,registration,token-generator

The reverse proxy can now route requests to the original instance and the additional instance.

This configuration has been tested locally with both instances running on different ports and across separate physical machines.

Run an external token-generator instance with HTTPS​

When an additional token-generator instance runs on another machine, you can configure it to accept HTTPS connections. This encrypts communication between the reverse proxy and the external instance.

The following example uses a local ip 192.168.1.8, to demonstrate the configuration. In production, use a hostname/ip that resolves to the external machine and a certificate valid for that hostname/ip.

1. Add the certificate files​

On the machine running the additional token-generator instance, create an https/ directory beside the JAR.

Place the PEM-encoded server certificate and its corresponding private key in that directory:

https/
├── token-generator.pem
└── token-generator-key.pem
  • token-generator.pem must contain the server certificate and, when applicable, the intermediate certificates required to validate its chain.
  • token-generator-key.pem must contain the private key corresponding to that certificate.

Keep the private key secure.

2. Enable HTTPS on the additional instance​

Open the additional instance's own configuration.yml—the file extracted from nidam-ha.ps1— and add:

Additional instance configuration.yml
ha:
  token-generator:
    https: true

This enables HTTPS for that instance.

Do not make this change in the original Nidam installation's configuration.yml. The property is intended here for the additional instance only.

3. Update the reverse proxy's instance URI​

Return to Machine 1 and edit the original Nidam installation's configuration.yml.

Change the additional instance's URI to use HTTPS:

Nidam configuration.yml

---

spring:
  config:
    activate:
      on-profile: reverse-proxy
  cloud:
    discovery:
      client:
        simple:
          instances:
            token-generator:
              - uri: ${authorization-server-uri}
              - uri: https://192.168.1.8:4010/auth

The first instance remains unchanged. Only the additional instance's URI changes to HTTPS.

Make sure the reverse proxy's JVM trusts the certificate's issuing CA and validates the certificate hostname. If you use a private or locally generated CA, configure the necessary trust before deploying this setup to another machine read here.

4. Start the additional instance​

From its extracted deployment directory, start the additional instance as usual:

runtime\bin\java.exe -jar token-generator-2.0.0.jar --spring.profiles.active=prod

If you use Oracle or IBM Db2, use the corresponding JDBC driver command described earlier.

5. Restart the reverse proxy​

On Machine 1, restart the reverse proxy to apply the updated URI:

.\nidam.ps1 restart -Exclude nidam,spa,bff,h2,registration,token-generator

The reverse proxy will now communicate with the additional instance over HTTPS, protecting traffic between the two machines in transit.

Important

Do not enable ha.token-generator.https: true in the original Nidam installation's configuration.yml. In the current setup, enabling HTTPS on Nidam's built-in token-generator instance causes startup failure.

Set this property only in the separate configuration.yml of the additional HA instance.

Same rule applies to the BFF (discussed next) and registration (after BFF).

Run an additional BFF instance​

1. Prepare the deployment package​

As with token-generator, use the nidam-ha.ps1 script to prepare the deployment package.

From the original Nidam installation directory, execute:

.\nidam-ha.ps1 bff

The script creates a ZIP archive containing the files required to run the additional BFF instance:

  • bff-2.0.0.jar
  • configuration.yml
  • runtime/

Copy the ZIP archive to the machine where you want to run the additional instance and extract it into a directory of your choice.

2. Configure the additional instance​

For this example, the additional BFF instance runs on a separate machine and listens on port 7082.

In the additional instance's configuration.yml, set:

bff-port: 7082

The final configuration for this example is:

Additional BFF instance configuration.yml
host: https://192.168.1.3
host-origin: 192.168.1.3

bff-port: 7082

nidam:
  session-mode: "redis"

The host and host-origin properties continue to reference the original Nidam installation. The additional BFF instance uses the same Redis deployment and session mode as the original instance.

3. Start the additional instance​

Open a PowerShell terminal in the extracted deployment directory and execute:

runtime\bin\java.exe -jar bff-2.0.0.jar --spring.profiles.active=prod

4. Register the additional instance with the reverse proxy​

On the original Nidam installation, open configuration.yml and add the additional BFF instance to the reverse proxy's discovery configuration:

Nidam configuration.yml

---

spring:
  config:
    activate:
      on-profile: reverse-proxy
  cloud:
    discovery:
      client:
        simple:
          instances:
            token-generator:
              - uri: ${authorization-server-uri}
              - uri: https://192.168.1.8:4010/auth
            bff:
              - uri: ${bff-uri}
              - uri: http://192.168.1.8:7082

The bff list now contains two entries:

  • ${bff-uri} — the original BFF instance.
  • http://192.168.1.8:7082 — the additional BFF instance.

Replace the example IP address and port with the address and port of your additional instance.

Keep the --- separator to ensure that the reverse-proxy-specific configuration is applied to the correct configuration document.

5. Restart the reverse proxy​

Restart only the reverse proxy to apply the updated instance list:

.\nidam.ps1 restart -Exclude nidam,spa,bff,h2,registration,token-generator

The reverse proxy can now distribute requests across both BFF instances.

Enable HTTPS for the additional BFF instance​

The HTTPS configuration follows the same procedure described in Run an external token-generator instance with HTTPS. The differences are the certificate filenames, the BFF-specific configuration property, and the instance URI.

On the machine running the additional BFF instance, place the PEM-encoded server certificate and its corresponding private key in an https/ directory beside the JAR:

https/
├── bff.pem
└── bff-key.pem

In the additional instance's own configuration.yml, enable HTTPS:

Additional BFF instance configuration.yml
ha:
  bff:
    https: true

Then, in the original Nidam installation's configuration.yml, change the additional BFF instance's URI from HTTP to HTTPS. For example:

- uri: https://192.168.1.8:7082

The original BFF URI remains unchanged.

Finally, restart the reverse proxy using the command described in Step 5 to apply the updated URI.

Run an additional Registration instance​

To not repeat everything here are the relevant code.

.\nidam-ha.ps1 registration

Zip:

  • jdbc/ folder
  • runtime/ fodler
  • configuration.yml
  • registration-2.0.0.jar
Additional Registration instance configuration.yml
host-origin: 192.168.1.3

registration-port: 4020

ha:
  registration:
    https: true

https/
├── registration.pem
└── registration-key.pem
runtime\bin\java.exe -jar registration-2.0.0.jar --spring.profiles.active=prod
Nidam configuration.yml

---

spring:
  config:
    activate:
      on-profile: reverse-proxy
  cloud:
    discovery:
      client:
        simple:
          instances:
            token-generator:
              - uri: ${authorization-server-uri}
              - uri: https://192.168.1.8:4010/auth
            bff:
              - uri: ${bff-uri}
              - uri: http://192.168.1.8:7082
            registration:
              - uri: ${registration-uri}
              - uri: https://192.168.1.8:4020

.\nidam.ps1 restart -Exclude nidam,spa,bff,h2,registration,token-generator