OpenID Connect provider of the platform: realm enterprise-ai with the portal, control-plane and cli clients, federation with the bank directory (LDAP or Entra ID).
Generated from catalog/services/keycloak.yaml: do not edit by hand.
Summary
| |
|---|
| Version | 26.8.1 |
| Use | install and configure, configure and connect |
| Layer | functional (AI catalog) |
| Category | Identity and secrets |
| Installation methods | binary, podman |
| External connection | no |
| Sandbox only | no |
Licence
| |
|---|
| SPDX identifier | Apache-2.0 |
| Licence policy | core licence (MIT or Apache-2.0) |
| Licence exception | - |
| Platform component | keycloak |
Packages and artifacts
A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.
Images are pinned by tag in the descriptor, and by digest when the descriptor declares one (the offline bundle then refuses a pulled image that does not carry it); the digest is recorded in the mirror of the Manager when the offline bundle is imported, and every pull or load is checked against it.
Supported systems and architectures
| Method | Operating systems | Architectures |
|---|
binary | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64, aarch64 (not restricted by the descriptor) |
podman | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64, aarch64 (not restricted by the descriptor) |
Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.
Prerequisites
Host
- at least 2048 MB of memory (blocking,
memory).
Network and ports
| Component | Port name | Port | Opened in the host firewall |
|---|
keycloak-server | http | 8443/tcp | yes |
keycloak-server | management | 9000/tcp | yes |
keycloak-server | jgroups | 7800/tcp | yes |
keycloak-server | jgroups_fd | 57800/tcp | yes |
Services and connections needed
database: postgresql.directory: ldap (optional).entra: oidc (optional).
Details and resolution: see Dependencies.
Installation methods and modes
| Method | Default | What the method uses |
|---|
binary | yes | the binary archives of the descriptor, unpacked under the service directory |
podman | - | the container images of the descriptor, run by Podman under systemd |
Components
| Component | Kind | Installation methods | Ports |
|---|
Keycloak server (keycloak-server) | master | binary, podman | 8443/tcp, 9000/tcp, 7800/tcp, 57800/tcp |
Single node (standalone) (default)
One Keycloak node, local cache.
What the mode deploys:
| Component | Placement |
|---|
keycloak-server | min 1, max 1 |
Cluster (cluster)
Several nodes sharing distributed caches (JGroups, discovery jdbc-ping through the database).
What the mode deploys:
| Component | Placement |
|---|
keycloak-server | min 2, recommended 3 |
Install this service
The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.
-
Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.
-
Choose the service. On the Service step, select Keycloak. The card shows the licence Apache-2.0 and the dependencies the installation needs. Pick the Method among binary, podman (default binary).
-
Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode: standalone (default), cluster. Each mode deploys the components listed in Installation methods and modes.
-
Bind the dependencies. On the Bindings step, choose for each dependency (database, directory, entra) Install with the platform or Use an existing connection; an optional dependency can stay on No binding.
-
Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.
-
Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.
-
Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services.
Connect an existing service
| |
|---|
| Schemes | https, http |
| Default port | 8443 |
| Authentication | required |
| Health check | management_url + /health/ready |
| Authentication method | Fields | Description |
|---|
client_credentials | client_id, client_secret | Confidential client of the realm (for example control-plane): its id and the secret of its Credentials tab. |
Official documentation: https://www.keycloak.org/docs/latest/server_admin/index.html#_service_accounts
| Field | Type | Default | Description | Notes |
|---|
Management interface URL (management_url) | url | - | Management interface URL of the existing service. | - |
Realm (realm) | string | navin | Realm used by the platform. | - |
High availability
| |
|---|
| Cluster | native (native) |
| High availability | native (native) |
| Failover | load balancer (load-balancer) |
| Replication | native (native) |
| Quorum | none (none) |
| Discovery | database (database) |
| Entry point | load balancer (load-balancer) |
| Official documentation | https://www.keycloak.org/high-availability/introduction |
| Peer TLS parameter | tls_enabled |
Prerequisites
| Prerequisite | Must be highly available | Modes | Description |
|---|
database | yes | modes of level ha or cluster | Highly available PostgreSQL holding realms, users and offline sessions. |
Topology per mode
| Modes | Highest catalog level | Distribution | Quorum component | Fault domains | Description |
|---|
standalone | standalone (standalone) | single (single) | - | 1 | One node with a local cache. |
cluster | cluster (cluster) | active-active (active-active) | - | 2 | Nodes sharing the embedded Infinispan distributed caches, discovered through the database (jdbc-ping). |
Notes
- The nodes find each other through the database (jdbc-ping): the JGroups port must be open between them.
Configuration parameters
Network
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
HTTP(S) port (port) | port | 8443 | - | no | no | yes | Port of the login pages and of the OIDC endpoints (HTTPS when TLS is on, else HTTP). |
Management port (management_port) | port | 9000 | - | no | no | yes | Port of /health and /metrics. |
JGroups port (jgroups_port) | port | 7800 | - | no | no | yes | Cluster transport between the nodes (cluster mode). |
JGroups failure detection port (jgroups_fd_port) | port | 57800 | - | no | no | yes | Failure detection port of JGroups (FD_SOCK2, JGroups port plus 50000). |
TLS (tls_enabled) | bool | true | - | no | no | yes | Serve HTTPS with a certificate of the manager CA (plain HTTP only behind a TLS proxy). |
Public URL (public_url) | url | https://{{ host.fqdn }}:{{ config.port }} | - | no | no | no | Address the browsers and the Control Plane use (hostname of the issuer). |
Realm
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
Realm (realm) | string | enterprise-ai | - | no | no | no | Realm of the platform (imported from deploy/keycloak at first start). |
Import the realm (import_realm) | bool | true | - | no | no | no | Import the enterprise-ai realm at start when it does not exist yet. |
Portal URL (portal_url) | url | https://{{ host.fqdn }}:3000 | - | no | no | no | Address of the portal, allowed as redirect URI and web origin of the portal client. |
Bootstrap admin password (admin_password) | password | generated | - | no | yes | no | Temporary admin of the master realm, user admin; replace it after the first login. |
Initial user password (initial_password) | password | generated | - | no | yes | no | Temporary password of the imported users (change and TOTP enforced at first login). |
Control Plane client secret (control_plane_client_secret) | password | generated | - | no | yes | no | Secret of the confidential client control-plane, given to the Control Plane through its binding. |
Tuning
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
Java heap (heap) | size | 2g | m | no | no | yes | Maximum heap of the JVM. (recommended clamp(round(host.memory_mb * 0.25), 1024, 8192)) |
Log level (log_level) | enum | INFO | DEBUG, INFO, WARN, ERROR | no | no | no | Root log level. |
Dependencies
For each active dependency the Manager takes the first of: the binding chosen in the wizard; a service of the same installation that provides it; a service already installed in the cluster; the only connection of the expected type. Otherwise an optional dependency stays unbound, and a required one is added to the installation in its default mode (the column below names the catalog service added).
| Binding | Provided by | Connection type | Endpoint | Optional | When nothing is bound | Description |
|---|
database | postgresql | postgresql | sql | no | postgresql is added to the installation | Database of the realms, users and sessions. |
directory | - | ldap | - | yes | stays unbound (optional) | Directory of the bank (LDAP or Active Directory) federated in the realm, declared as an LDAP connection of the Manager. |
entra | - | oidc | - | yes | stays unbound (optional) | Microsoft Entra ID tenant brokered by the realm (OpenID Connect connection: issuer, client id and secret). |
Endpoints
| Endpoint | Scheme | Component | Port | Path | TLS parameter | Binding parameters | Binding secrets | Provisioning command |
|---|
http | http | keycloak-server | 8443 (port) | - | tls_enabled | issuer, jwks_url, client_id | client_secret | - |
Client configuration files
Files rendered for the client configuration download:
keycloak.env (client.env.j2)
Commands
| Command | Component | Target | Description |
|---|
Export the realm (export_realm) | keycloak-server | first host | Exports the realm to a file under the data directory (users excluded). |
Health checks
Liveness (per instance)
| Component | Check | Details |
|---|
keycloak-server | HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.management_port }}/health/ready | Expected 200; 90 retries; interval 2 s; timeout 5 s |
Readiness (service check)
| Check | Details |
|---|
HTTP {{ config.public_url }}/realms/{{ config.realm }}/.well-known/openid-configuration | Expected 200; 10 retries; interval 3 s; timeout 5 s |
Preflight checks
| Check | Type | Meaning | Severity | Components |
|---|
memory | memory_mb {"min": 2048} | at least 2048 MB of memory | blocking | every component |
port_free | port_free {"param": "port"} | port 8443 free on the host | blocking | every component |
Uninstall
Paths removed when the data is purged: {{ paths.data }}, {{ paths.log }}.
Quick links
- Administration console:
{{ config.public_url }}/admin/
- OIDC discovery:
{{ config.public_url }}/realms/{{ config.realm }}/.well-known/openid-configuration
Upstream documentation