Keycloak

Component Category

Access and security / identity and access management

Component Description

Keycloak is the identity and access management platform used to authenticate users and services. It centralizes identity, login flows, and access-related integration across the platform.

Why It Is Used

In BullSequana AI Foundation, Keycloak provides centralized authentication, single sign-on, identity federation, and user access management across platform services. It helps keep access consistent across interfaces and APIs instead of duplicating authentication logic in each component.

Organizations and tenants

BullSequana AI 1.3.0 uses Keycloak Organizations as the identity boundary for platform tenants. Organization membership determines which tenant a JWT user can select. The BSQAI API combines that identity context with OpenFGA authorization for tenant-scoped resources.

The tenant lifecycle workflow reconciles Organizations rather than relying on manually maintained realm groups as the tenant source of truth.

How Components Get SSO

Platform components do not configure Keycloak manually. Instead, each component that needs SSO is enrolled automatically through a pair of Kubernetes jobs managed by the platform CLI.

Enrollment flow

When a component with SSO enabled is synced by ArgoCD, two Kubernetes jobs handle registration and deregistration:

1. Setup job (negative sync wave) -- runs before the component is deployed. It waits for Keycloak to be reachable, authenticates with dedicated enroll credentials, then creates or updates:

   • a Keycloak OIDC client for the component (client ID, secret, redirect URIs, scopes, protocol mappers)
   • any realm groups the component needs (for example, admin or user groups)
   • any realm roles the component defines
   • group-to-role mappings that connect groups to roles
   • service account client role mappings when machine-to-machine access is needed
   • membership of the admin user in all declared groups

2. PostDelete cleanup job -- runs when the component's Argo CD application is deleted. It removes the OIDC client, groups, and roles that the setup job created, so Keycloak stays clean.

Both jobs are idempotent. They detect existing resources and only modify them when the desired state has drifted from the current Keycloak configuration.

What gets registered per component

Each SSO-enabled component provides a configuration secret (<component>-keycloak-sso-config) containing:

The platform CLI generates this secret from the component's [sso] table in variables.toml, using a shared template.

How the enroll credentials work

The setup and cleanup jobs authenticate against Keycloak using a shared secret called keycloak-enroll-credentials. This secret contains:

• username and password for a dedicated enroll user
• keycloak-url pointing to the internal Keycloak service
• realm identifying the target realm (typically dataplatform)

These credentials are generated by the platform CLI and distributed to every namespace that has SSO enabled.

Enabling or disabling SSO for a component

Each component has an enabled field in its [sso] table in variables.toml. It defaults to true. When set to false:

• the SSO config secret is not generated
• the setup and cleanup jobs are not created
• the component deploys without Keycloak integration

See Configuration model — SSO configuration for how to control SSO at deployment level.

Components with SSO support

The following components currently support automatic SSO enrollment:

Foundation: Grafana, PgAdmin, the Rook-Ceph dashboard through Envoy Gateway OIDC, ArgoCD

AI: AI Web Portal, BSQAI API (via LLM Backend), MLflow, Temporal, Model Installer, LiteLLM

Data: Superset, Kafka (Strimzi), Airbyte (via OAuth2 Proxy), Attu (via OAuth2 Proxy)

Learn More

• Keycloak documentation
• keycloak/keycloak on GitHub

Deployment notes

Keycloak deploys into the keycloak namespace at sync wave 7 in the common tier. It runs as a stateless server backed by the CNPG PostgreSQL cluster, with an init container that waits for database readiness before starting. SSO client registrations for all platform components are stored in a shared secret managed by the platform CLI.

Before an upgrade, an Argo CD PreSync job creates a Keycloak database backup and validates the version transition. The deployment proceeds only after that gate succeeds.

Interacts With

• BSQAI API and AI Web Portal, which use Organization membership to establish tenant context.
• Temporal, Grafana, PgAdmin, Argo CD, MLflow, LiteLLM, Superset, Kafka, and other services, which use Keycloak for login and OIDC-based access through automatic SSO enrollment.
• OpenFGA, which applies resource authorization after Keycloak establishes identity and tenant membership.
• OAuth2 Proxy, which delegates authentication to Keycloak for services that lack native SSO (Airbyte, Attu).

Related Pages

• Access and Authentication
• Security Model
• Configuration Model