Changelog

• 21st May, 2026
  • Author: Angelo Marchese
  • First version

1. BlueGPS And Keycloak Authentication

BlueGPS uses Keycloak as the central authentication system.

Keycloak is responsible for authenticating users, integrating with external identity sources, issuing tokens, and managing sessions. The BlueGPS frontend, mobile app, and backend do not authenticate users directly. They integrate with Keycloak and trust the tokens issued by Keycloak.

The BlueGPS frontend and mobile app use the standard OAuth 2.0 / OpenID Connect authorization code flow.

In this flow:

• The user starts from the BlueGPS frontend or mobile app.
• The application redirects the user to Keycloak.
• Keycloak authenticates the user.
• Keycloak returns an authorization code to the application.
• The application exchanges the authorization code for tokens.
• The application calls the backend using the access token.
• The backend validates the token before serving the request.

Step-by-step flow

1. The user opens the BlueGPS frontend or mobile app.
2. The application redirects the user to Keycloak.
3. Keycloak shows the login page.
4. The user enters their username and password.
5. Keycloak validates the credentials and creates a user session.
6. Keycloak returns an authorization code to the frontend or mobile app.
7. The frontend or mobile app exchanges the authorization code with Keycloak.
8. Keycloak returns an ID token and access token.
9. The frontend or mobile app calls the backend API with the access token.
10. The backend validates the token and permissions.
11. The backend returns the protected data.

Integration responsibilities

2. External Identity Provider Integration

Keycloak can integrate with an external identity provider such as Microsoft Entra ID.

In this model, Keycloak acts as an identity broker:

• BlueGPS still redirects users to Keycloak.
• Keycloak redirects the user to Microsoft Entra ID.
• Microsoft Entra ID authenticates the user.
• Keycloak receives the authentication result from Microsoft Entra ID.
• Keycloak maps the external identity to a BlueGPS user.
• Keycloak issues the tokens used by BlueGPS.

The important point is that BlueGPS continues to trust Keycloak-issued tokens. The backend does not need to validate Microsoft Entra ID tokens directly.

Step-by-step flow

1. The user opens the BlueGPS frontend or mobile app.
2. The application redirects the user to Keycloak.
3. Keycloak redirects the user to Microsoft Entra ID.
4. Microsoft Entra ID shows the login page.
5. Microsoft Entra ID authenticates the user and applies enterprise security controls such as MFA or conditional access.
6. Microsoft Entra ID returns the authentication result back to Keycloak.
7. Keycloak maps the external user to a local Keycloak user identity and applies BlueGPS role and group mappings.
8. Keycloak returns an authorization code to the frontend or mobile app.
9. The frontend or mobile app exchanges the authorization code with Keycloak.
10. Keycloak returns Keycloak tokens (ID token and access token).
11. The frontend or mobile app calls the backend API with the Keycloak access token.
12. The backend validates the Keycloak token.
13. The backend returns the protected data.

Integration responsibilities

Attribute and Group Mapping

Keycloak can use mappers to map claims from the external identity provider's token (such as group membership information) to Keycloak groups. This allows users to automatically be assigned to the appropriate groups based on their enterprise directory attributes.

The requirement is that appropriate claims should be present on the external identity provider's token for the group mapping to work.

Configuring the groups claim in Microsoft Entra ID

When using Microsoft Entra ID as the external identity provider, the groups claim must be explicitly added to the tokens issued to Keycloak. To do this:

1. Open the Azure Portal and navigate to Microsoft Entra ID.
2. Go to Enterprise applications and select the application registered for Keycloak.
3. Under Manage, click Single sign-on.
4. In the Attributes & Claims section, click Edit.
5. Click Add new claim.
6. Set the claim Name to groups.
7. Set the Source attribute to user.groups.
8. Save the claim.

Once this claim is present in the token, the groups claim will contain the object IDs of the groups the user belongs to in Microsoft Entra ID. These are GUIDs, not display names (for example, xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

On the Keycloak side, a mapper can be created on the identity provider configuration to read the groups claim and match each group object ID to a Keycloak group. This allows a specific Entra ID group ID to be mapped to a specific Keycloak group, so that users are automatically assigned the correct roles and permissions when they log in through Microsoft Entra ID.

3. LDAP Integration

Keycloak can integrate with LDAP as a user federation source.

In this model:

• Users still log in through Keycloak.
• Keycloak connects to LDAP to find users and validate credentials.
• LDAP remains behind Keycloak.
• BlueGPS does not connect directly to LDAP.
• After successful authentication, Keycloak issues the tokens used by BlueGPS.

Step-by-step flow

1. The user opens the BlueGPS frontend or mobile app.
2. The application redirects the user to Keycloak.
3. Keycloak shows the login page.
4. The user enters their username and password.
5. Keycloak searches LDAP for the user.
6. LDAP returns the matching user entry.
7. Keycloak validates the credentials against LDAP.
8. LDAP returns the authentication result.
9. Keycloak maps LDAP attributes and groups to the Keycloak user model.
10. Keycloak returns an authorization code to the frontend or mobile app.
11. The frontend or mobile app exchanges the authorization code with Keycloak.
12. Keycloak returns Keycloak tokens (ID token and access token).
13. The frontend or mobile app calls the backend API with the Keycloak access token.
14. The backend returns the protected data.

Integration responsibilities

Summary

Keycloak is the central authentication layer for BlueGPS.

• The frontend and mobile app authenticate users through Keycloak.
• The backend validates Keycloak access tokens.
• Microsoft Entra ID can be integrated through Keycloak as an external identity provider.
• LDAP can be integrated through Keycloak as a user federation source.
• BlueGPS services trust Keycloak as the token issuer.

Changelog

• 18th May, 2026
  • Author: Francesco Distefano
  • First review
• 18th May, 2026
  • Author: Angelo Marchese
  • First version

1. Summary

This document describes the setup of the BlueGPS application on an on-premise environment. It covers the software components that make up the application, their execution model, and the infrastructure requirements for each server in the deployment.

2. Software components

The BlueGPS application on an on-premise environment is composed of several software components that are grouped into logical layers: the application layer, the IPS positioning layer, the database layer and the observability layer. Most components run as Docker containers managed through Docker Compose. The only exception is the IPS service, which runs as a web application deployed on a system Tomcat service.

The following figure shows the software architecture of the BlueGPS application and the communication channels between its components.

2.1 Application containers

The application layer is made up of the following Docker containers, all executed on the application server:

• Web proxy: an nginx web server that listens for HTTPS requests on port 443. It is the single entry point for all inbound traffic and acts as a TLS termination point. It routes requests to the frontend microservices, the API gateway and the authentication server based on the URL path.
• API gateway: a Spring Boot application that acts as a reverse proxy routing external API requests to the appropriate backend microservice. It listens for HTTP requests on port 8080.
• Frontend microservices: one or more nginx containers that serve the BlueGPS frontend applications (developed in Flutter and Angular). Each container listens for HTTP requests on port 8080.
• Backend microservices: a set of Spring Boot applications that implement the domain logic of the BlueGPS application. They communicate with each other either synchronously via HTTP or asynchronously through the RabbitMQ message broker. They connect to the database services (MySQL on TCP/3306, MongoDB on TCP/27017, Redis on TCP/6379).
• Authentication server: a Keycloak container that manages authentication and authorization for the application. It is based on the OIDC and OAuth 2.0 protocols and listens for HTTP requests on port 8080.
• Message broker: a RabbitMQ container used for asynchronous communication between backend microservices. It listens on TCP/5672.
• Mosquitto broker: an MQTT container used for communication between the application and the IPS service. It listens on port TCP/8883.

2.2 IPS service

The IPS (Indoor Positioning System) service is the only component that does not run as a Docker container. It is deployed as a web application inside a system Tomcat service running directly on the IPS server operating system. The IPS server receives positioning data and exposes an HTTP API on port 8080 that is consumed by the backend microservices of the application server. Another option is for the IPS server to send data to the application via the MQTT server exposed on port TCP/8883.

2.3 Database services

The database layer runs on a dedicated database server and consists of the following Docker containers:

• MySQL: relational database used by several backend microservices to store structured application data. Exposed on TCP/3306.
• MongoDB: document-oriented database used by backend microservices that require flexible schema storage. Exposed on TCP/27017.
• Redis: in-memory data store used as a cache and session store. Exposed on TCP/6379.

2.4 Observability services

The observability layer runs on a dedicated observability server and consists of the following Docker containers:

• Grafana Alloy: a log collector that collects logs from each server and forwards them to the backend observability storage.
• Prometheus: a metrics collection and storage server. It scrapes metrics exposed by the application containers and the database containers and stores them for querying and alerting.

3. Infrastructure setup

3.1 Architecture overview

The on-premise deployment of the BlueGPS application is distributed across four servers, each dedicated to a specific layer of the architecture. All servers must reside on the same private network. The following figure illustrates the on-premise deployment architecture.

3.2 Server requirements

The table below lists the minimum hardware and storage requirements for each server in the on-premise deployment. The additional disk is used exclusively for application data (container volumes, database files, metrics storage) and, except for the IPS server, must be divided into two partitions mounted at the indicated mount points before any installation is performed.

All servers must run a supported 64-bit Linux operating system, with Ubuntu Server 24.04 LTS being the recommended distribution.

Except for the IPS server, the latest stable release of the Docker engine should be installed on all the hosts.

N.B. The server requirements listed above are minimums and may vary based on the specific workload.

3.3 Two-server deployment

As a more compact alternative to the four-server reference layout described above, BlueGPS can also be deployed on two servers (physical or virtual). This variant collapses the application, database and observability layers onto a single host, keeping the IPS service isolated on its own machine — which remains a hard requirement because the Position Engine runs as a system Tomcat service alongside the LAN-attached locators.

The resulting topology is:

• Server 1 — BlueGPS Application server
  • Hosts all application containers (web proxy, API gateway, frontend microservices, backend microservices, Keycloak, RabbitMQ, Mosquitto).
  • Hosts the database containers (MySQL, MongoDB, Redis) co-located on the same host instead of on a dedicated DB server.
  • Hosts the observability containers (Grafana Alloy, Prometheus) co-located on the same host instead of on a dedicated observability server.
  • Linux server, recommended Ubuntu Server 24.04 LTS, Docker engine installed.
• Server 2 — IPS / Location server
  • Runs the Position Engine inside a system Tomcat service (no Docker).
  • LAN-attached to the PoE switch that powers and connects the locators.
  • Linux server, recommended Ubuntu Server 24.04 LTS.

Both servers must reside on the same private network. The Application server reaches the Internet only for licence verification against https://license2.synapseslab.cloud; all other traffic stays on the LAN.

Network communications

The table below summarises every network channel that must be opened between the components. Ports marked configurable can be changed in the BlueGPS application configuration and on the IPS server.

Firewall recommendations

• Expose only TCP / 443 of the Application server to client networks; keep MQTT / 8883 and WSS / 443 restricted to clients that actually need real-time push.
• Keep the IPS server and the locators on a dedicated VLAN; allow only the Application server to reach HTTP / 8080 and UDP / 15000–15001 on the IPS server.
• Outbound HTTPS to license2.synapseslab.cloud must be reachable from the Application server.
• TFTP / 69 must be reachable from the IPS server to the locators network for firmware updates; it should never be exposed beyond the locators VLAN.