Keycloak
Identity and access management component for Foundation authentication and component SSO enrollment.
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 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 BSQAI Tenant Operator creates each tenant's Organization and, when configured, registers the tenant's external OIDC or SAML identity provider as a broker for that Organization. See Access and authentication. Organizations, not manually maintained realm groups, are the tenant source of truth. The reserved Global Organization, and any Organization listed in [auth] organizations of the Keycloak component, comes from the Keycloak component's organizations reconcile job. That job runs after each sync and every 15 minutes, creates a listed Organization that is missing, and refuses to replace the Global Organization's recorded UUID.
Keycloak administration access
Signing in to the AI Web Portal never grants access to Keycloak's administration API. The BSQAI API's sign-in client does not use full role scope, so a signed-in user's token carries only the roles the platform consumes, such as the Tuples roles. It never carries Keycloak administration roles.
The BSQAI API administers Keycloak through a separate service-account client, llm-backend-admin. That client holds the Keycloak administration roles and cannot sign anyone in.
The bootstrap platform administrator, admin in the platform realm, manages the platform through the AI Web Portal and holds no Keycloak administration roles. On existing installations, the platform removes those roles from this account. To use the Keycloak Admin Console, sign in with the master realm administrator. Its username comes from [auth] master_admin_username in the Keycloak component's variables.toml and defaults to admin.
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:
-
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
-
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:
| File | Purpose |
|---|---|
client.json | Full OIDC client definition: client ID, secret, redirect URIs, scopes, protocol mappers, flow settings |
groups.json | Realm groups to create, optionally with attributes and role bindings |
roles.json | Realm roles to create |
service-account-client-roles.json | Client role mappings for service accounts |
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:
usernameandpasswordfor a dedicated enroll userkeycloak-urlpointing to the internal Keycloak servicerealmidentifying the target realm (typicallydataplatform)
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, OpenBao, the Rook-Ceph dashboard through Envoy Gateway OIDC, Argo CD, and the BSQAI Tenant Operator (a service-account client that signs nobody in)
AI: AI Web Portal and BSQAI API (llm-backend client), Temporal UI through Envoy Gateway OIDC
Data: Superset, Kafka (Strimzi), Lakekeeper, Argo Workflows, Studio data ingestion (through the Portal and BSQAI API), Kubeflow (via OAuth2 Proxy)
MLflow has no login client: it is reached only through the BSQAI API. Argo CD's client is part of the Keycloak component's realm configuration rather than an enrollment job.
Learn More
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. Platform components reach it inside the cluster over its internal TLS service. Each SSO-enabled component's registration lives in its own <component>-keycloak-sso-config Secret, which the platform CLI generates.
Before an upgrade, an Argo CD Sync hook job creates a Keycloak database backup and validates the version transition. Only the gate's own service account, RBAC, and script are synced before it; every other Keycloak resource waits until the gate succeeds.
Interacts With
BSQAI APIandAI Web Portal, which use Organization membership to establish tenant context.BSQAI Tenant Operator, which creates tenant Organizations and their external identity provider brokers through its service-account client.Temporal,Grafana,PgAdmin,OpenBao,Argo CD,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 (Kubeflow).