# Keycloak (/docs/runtime/components/keycloak)



Component Category [#component-category]

Access and security / identity and access management

Component Description [#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 [#why-it-is-used]

In BullSequana AI Runtime, 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.

How Components Get SSO [#how-components-get-sso]

Platform components do not configure Keycloak manually. Instead, each component that needs SSO is enrolled automatically through a pair of Argo CD hook jobs managed by the Terraform layer.

Enrollment flow [#enrollment-flow]

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

1. **PreSync setup job** -- 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 [#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 Terraform layer generates this secret from component-specific locals and variables, using a shared template.

How the enroll credentials work [#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 created by Terraform and distributed to every namespace that has SSO enabled.

Enabling or disabling SSO for a component [#enabling-or-disabling-sso-for-a-component]

Each component has an `sso_enable` flag in its Terraform variable block. 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 scope](/docs/deployment/configuration-model#sso-scope) for the full list of components and how to control SSO at the deployment level.

Components with SSO support [#components-with-sso-support]

The following components currently support automatic SSO enrollment:

**Runtime:** Grafana, PgAdmin, MinIO, Argo CD

**CoreAI:** CoreAI Web Portal, CoreAI API (via LLM Backend), Langfuse, MLflow, Temporal, Model Installer

**ProAI:** Superset, Kafka (Strimzi), Airbyte (via oauth2-proxy), Attu (via oauth2-proxy)

APISIX uses a separate integration path as an API gateway introspector rather than a user-facing client.

Learn More [#learn-more]

* [Keycloak documentation](https://www.keycloak.org/documentation)
* [keycloak/keycloak on GitHub](https://github.com/keycloak/keycloak)

Interacts With [#interacts-with]

* `APISIX`, for API authentication and token introspection.
* `Temporal`, `Grafana`, `PgAdmin`, `Argo CD`, `MinIO`, `Langfuse`, `MLflow`, `Superset`, `Kafka`, and `CoreAI` services, which use Keycloak for login and OIDC-based access through automatic SSO enrollment.

Related Pages [#related-pages]

* [Access and Authentication](/docs/guides/access)
* [Security Model](/docs/runtime/runtime-security-model)
* [Configuration Model](/docs/deployment/configuration-model)