Skip to content

Keycloak Identity Service

The Keycloak service is the centralized Identity Provider (IdP) for the platform, implementing authentication, single sign-on (SSO), and role management. It manages authorization across the platform by issuing cryptographically signed JSON Web Tokens (JWT) containing client-specific roles.

1. Deployment & Infrastructure Specification

Keycloak is containerized using a custom Dockerfile and orchestrated via docker-compose.yml.

Entrypoint & Run Commands

  • Command / Entrypoint: start-dev --import-realm This starts Keycloak in development mode and automatically imports any JSON realm definitions placed inside /opt/keycloak/data/import/ directory on container startup.
  • Ports: Mapped to host port 8080 (Internal container port 8080).
  • Service URL: https://keycloak.intelligence-cloud.gr

Default Admin Credentials

When the containers are initialized, default administrator credentials are bootstrapped: * Username: admin * Password: admin * Bootstrap Environment Variables: - KC_BOOTSTRAP_ADMIN_USERNAME=admin - KC_BOOTSTRAP_ADMIN_PASSWORD=admin

[!WARNING] These credentials are built strictly for local development and demonstration. For staging or production deployments, these environment variables must be changed in the secrets manager or .env files.

Database Integration

Keycloak persists all tenant metadata, client mappings, and accounts in a PostgreSQL database container: * Connection URL: jdbc:postgresql://postgres:5432/keycloak * User / DB Name: keycloak / password (defined in docker-compose.yml)

Prometheus Metrics Extension

The Keycloak container is custom-built to bundle the Aerogear Metrics SPI jar (keycloak-metrics-spi-7.0.0.jar) at /opt/keycloak/providers/. The build optimization runs /opt/keycloak/bin/kc.sh build to enable scrapable Prometheus endpoints at: https://keycloak.intelligence-cloud.gr/realms/intelligence-cloud/metrics

2. Realm Configuration

The system initializes a primary realm configured inside the configuration export file intelligence-cloud-realm-export.json.

  • Realm Name: intelligence-cloud
  • Flow Type: Standard OpenID Connect (OIDC) Browser Authorization Code Flow with PKCE (Proof Key for Code Exchange) enforced.
  • Token Expiration: Access tokens are short-lived (5 minutes) to mitigate risk of token theft, and refresh tokens are enabled.
  • Custom Themes: The authentication page uses a customized UI layout stored under the themes/intelligence-cloud/login directory.
  • Login Theme Value: intelligence-cloud

3. Client Configuration

The primary frontend client configuration is named angular-dash.

  • Client ID: angular-dash
  • Access Type: Public Client (publicClient: true). Since SPAs (Single Page Applications) run completely in user browsers, they cannot store a client secret safely.
  • Redirect URIs: Keycloak only redirects auth codes to pre-approved origin patterns to prevent token leakage:
  • http://localhost:4200/* (local development)
  • http://147.27.50.32:4200/* (infrastructure testing)
  • http://ui.intelligence-cloud.gr/* (non-secure production gateway)
  • https://ui.intelligence-cloud.gr/* (production secure SSL gateway)
  • Web Origins: Configured as +. This dynamically maps all entries listed in the Redirect URIs to Cross-Origin Resource Sharing (CORS) origins, allowing the frontend client to securely make OAuth token exchange calls.
  • Token Exchange Features: use.refresh.tokens = true is active, enabling standard OAuth 2.0 token refreshes directly from the client.
  • Client Implementation: The client configuration is bootstrapped in app.config.ts and guarded statelessly inside auth.guard.ts.

4. Roles & Inherited Roles (Composite Roles)

Keycloak uses client-level composite roles to construct an authorization hierarchy. The custom client angular-dash exposes three progressive tiers of access:

Inheritance & Permissions Mapping

Role Name Inherits From Access Level & Capabilities Inherited Roles
viewer None (Base) Read-only access to dashboards, platforms status, and metrics. None
editor viewer Read-write permissions. Can create, edit, or delete LXD container/virtual machines, networks, and server configurations. viewer
admin editor Full system administrator privileges. Access to administrative panels plus ability to list/manage user profiles. editor, viewer, realm-management/view-users, realm-management/query-users

Hierarchy Visualization

graph TD
    admin["Admin Role (angular-dash: admin)"]
    editor["Editor Role (angular-dash: editor)"]
    viewer["Viewer Role (angular-dash: viewer)"]

    queryUsers["realm-management: query-users"]
    viewUsers["realm-management: view-users"]

    admin --> editor
    admin --> queryUsers
    admin --> viewUsers
    editor --> viewer

[!NOTE] When a user logs in, these roles are embedded under resource_access.angular-dash.roles inside the JWT payload. The gateway reads this claim statelessly to grant or deny incoming API calls.

5. Mail Server (SMTP) Setup

SMTP settings are defined under the realm configuration to support outgoing transactional mail (e.g. email verifications, passwords resets, two-factor registrations).

SMTP Integration Parameters

  • SMTP Host: smtp.resend.com
  • SMTP Port: 465 (SSL connection)
  • SSL Protocol: Enabled (ssl: true)
  • STARTTLS Protocol: Disabled (starttls: false)
  • Authentication: Enabled (auth: true)
  • Username: resend (utilizes API token basic authentication)
  • Password: Concealed (set inside Keycloak Admin Portal or environment configs)
  • From Address: noreply@intelligence-cloud.gr
  • From Display Name: Intelligence Cloud
  • Timeouts: Socket, connection, and write timeouts are constrained to 10000ms (10 seconds) to prevent request blocking.

6. Common Operations & Diagnostics

Run Keycloak Separately

To start Postgres and Keycloak containers without booting up the rest of the microservices: 

docker compose up -d postgres keycloak

Reset / Force Re-import of Realm Setup

To update changes or wipe current configs, stop the container, delete the local Postgres volume, and spin the setup back up: 

# Stop and clean containers
docker compose down -v

# Restart Keycloak which imports intelligence-cloud-realm-export.json from scratch
docker compose up -d postgres keycloak

Validate SMTP Connection

  1. Log in to the Admin Console at https://keycloak.intelligence-cloud.gr.
  2. Select the intelligence-cloud realm from the top-left dropdown.
  3. Navigate to Realm Settings -> Email.
  4. Test connectivity by clicking the Test Connection button at the bottom of the form (requires a test user with a valid email).