Skip to content

08. Keycloak

Keycloak is the centralized identity and access management system that handles authentication and authorization across all components of AClimate v3. Instead of each application managing its own user database, Keycloak provides a single point where users authenticate and receive tokens that authorize them to access the different platform services.

How AClimate Uses Keycloak

The WebAPI is the primary consumer of Keycloak authentication. When a user logs in through the frontend or admin portal, they provide their credentials to Keycloak, which returns a JWT access token. This token is then included in every request to the WebAPI, and the API validates the token against Keycloak's public keys before processing any request. The API uses a token validation endpoint that fetches the Keycloak certificates and decodes the JWT to verify its authenticity and extract the user roles and permissions.

The admin portal integrates with Keycloak through OAuth, allowing administrators to log in with their existing Keycloak credentials. The portal also provides user and role management interfaces that synchronize with Keycloak, so administrators can create users, assign roles, and manage permissions directly from the admin interface without needing to access the Keycloak admin console separately.

The frontend uses the keycloak-js library in the AuthProvider context, which is wrapped around the entire application in the root layout. When users visit the frontend, the AuthProvider checks if they have a valid Keycloak session. If not, they are redirected to the Keycloak login page. Once authenticated, the frontend receives a token that it sends with every API request. The frontend configuration specifies the Keycloak URL, realm name, and client ID that identify the AClimate application to the Keycloak server.

Key Concepts

When setting up Keycloak for AClimate, a realm is created that serves as the security domain for the platform. Within this realm, each application that needs authentication is registered as a client. There are typically two clients: one for the frontend and one for the admin portal. Roles are defined within each client or at the realm level to control what actions users can perform. The admin portal uses roles like "admin" and "editor" to restrict access to specific configuration sections.

Configuration

The platform components are configured with the following environment variables that define how they connect to Keycloak:

  • KEYCLOAK_URL: the base URL of the Keycloak server
  • KEYCLOAK_REALM: the realm name for AClimate
  • KEYCLOAK_CLIENT_ID: the client identifier used by each application
  • KEYCLOAK_CLIENT_SECRET: the client secret used by server-side components

These variables have default values set in the application configuration files for local development, but are configured with the actual Keycloak server details in production environments.

Authentication Flow

When a user accesses the frontend or admin portal for the first time, they are redirected to the Keycloak login page where they enter their credentials. Keycloak validates the credentials against its user database and issues a JWT access token along with a refresh token. The access token is short-lived and is included in every subsequent API request in the Authorization header. When the access token expires, the frontend or admin portal uses the refresh token to obtain a new one without requiring the user to log in again. The WebAPI validates every incoming request by checking the JWT token signature and expiration against Keycloak's public keys.

Keycloak Database

Keycloak stores all its configuration and user data in a dedicated relational database. This database contains tables for realms, users with encrypted credentials, role mappings that associate users with their permissions, registered client applications, authentication event logs for auditing, and active session information.