Keycloak bootstrap and configuration behavior¶

When you run hubctl bootstrap, Altair SLC Hub performs a Keycloak configuration step to apply the settings it requires to function correctly.

This page explains how bootstrap behaves when Keycloak configuration is created for the first time, when bootstrap is run again later, and when existing Keycloak settings differ from the values expected by Altair SLC Hub.

For the bootstrap procedure itself, see Bootstrap.

Two kinds of Keycloak configuration¶

Keycloak configuration managed by Altair SLC Hub falls into two categories:

Required Config
Default-Only Config

This distinction determines how bootstrap behaves on a re-run.

Required Config¶

Required Config is configuration that Altair SLC Hub depends on for correct operation.

If this configuration is missing or differs from the expected value, Altair SLC Hub may not function correctly. For that reason, these settings are treated as owned by Altair SLC Hub.

Examples include:

realm name
Altair SLC Hub client IDs and their required scopes
service account role assignments
realm-management role composites required for the Altair SLC Hub Administrator role
client scope definitions that Altair SLC Hub reads from tokens

Warning

If Required Config already exists but differs from the expected value, bootstrap does not silently replace it. Instead, bootstrap reports the conflict and fails.

Default-Only Config¶

Default-Only Config is configuration that Altair SLC Hub creates with sensible defaults when it is first setting up Keycloak, but does not continue to enforce on later bootstrap runs.

This allows administrators to adapt Keycloak to local requirements without those changes being overwritten by bootstrap.

Examples include:

email server settings
password policy
brute-force detection settings
client redirect URLs and web origins
token lifetimes
reset-password settings

These settings may still be important operationally, but they are not treated as owned values in the same way as Required Config.

Why bootstrap behaves this way¶

Bootstrap has two goals that need to be balanced:

create a working Keycloak configuration for Altair SLC Hub
avoid overwriting administrator-managed settings on later runs

On first bootstrap run, both Required Config and Default-Only Config need to be created so that Altair SLC Hub is usable without additional manual setup.

On later bootstrap runs, preserving administrator changes becomes important. Some Keycloak settings are part of local operational policy rather than fixed product requirements. For example, password rules, SMTP settings, or token lifetimes may vary between environments.

At the same time, some configuration must remain consistent for Altair SLC Hub to keep working. If those required values were silently changed back, it could hide configuration drift. If they were silently accepted, Altair SLC Hub might fail in less obvious ways later. Failing early makes the problem visible and explicit.

This model makes the Keycloak configuration step operationally idempotent: bootstrap can be run repeatedly without overwriting legitimate administrator customization.

Bootstrap behavior¶

When configuration does not exist¶

When a Keycloak configuration item does not already exist, bootstrap creates it.

This applies to both:

Required Config
Default-Only Config

This is true whether it is the first-ever bootstrap run or a later run after the item was deleted from Keycloak.

In practice, this means bootstrap creates the full Keycloak baseline needed by Altair SLC Hub whenever required configuration items are missing.

See Perform initial data bootstrap for the bootstrap procedure.

When configuration already exists¶

When a configuration item already exists, bootstrap behavior depends on which category that item belongs to.

Category	If existing value matches expected value	If existing value differs from expected value
Required Config	Bootstrap continues with no change.	Bootstrap reports a conflict and fails.
Default-Only Config	Bootstrap continues with no change.	Bootstrap preserves the existing value and continues.

This makes bootstrap safe to run more than once while still protecting the configuration required by Altair SLC Hub.

Conflict behavior¶

If bootstrap detects that Required Config differs from the expected values, it does not overwrite those values automatically.

Instead, bootstrap:

reports which items conflict
shows the current and expected values
exits with a non-zero exit code

This makes the change visible to the administrator and avoids silently replacing existing Keycloak configuration.

Note

A conflict does not necessarily mean the current Keycloak configuration is invalid in general. It means the configuration no longer matches what Altair SLC Hub expects to manage as Required Config.

Resolving conflicts¶

There are two supported ways to resolve Required Config conflicts.

`hubctl keycloak apply`¶

Use hubctl keycloak apply when you want to review and apply only the Required Config changes needed to resolve drift or conflicts, without running the full bootstrap workflow.

This command shows the differences and applies only the Required Config items that differ. It does not overwrite Default-Only Config or unrelated Keycloak configuration.

For more information, see hubctl keycloak apply configuration management.

`hubctl bootstrap --forceupdatekeycloak`¶

Use hubctl bootstrap --forceupdatekeycloak when you want bootstrap itself to overwrite conflicting Required Config.

This is mainly useful in scripted or automated workflows where a separate review step is not needed.

Warning

--forceupdatekeycloak overwrites conflicting Required Config as part of bootstrap. Use it only when you understand and accept the changes that will be applied.

Administrator changes and bootstrap re-runs¶

The most important consequence of this model is that not all Keycloak changes are treated the same way.

Changes to Default-Only Config are preserved. This allows administrators to configure Keycloak for their own environment, for example by changing:

SMTP settings
password policies
brute-force protection settings
token and session lifetimes
redirect URLs and web origins

For more information about these areas, see:

Changes to Required Config are not preserved as administrator customization. If they differ from the expected values, bootstrap treats them as conflicts.

Domain and ingress changes¶

Changes to client redirect URLs and web origins are treated as Default-Only Config. This is important when moving Altair SLC Hub to a different hostname or updating ingress configuration.

If the external URL changes, administrators may need to update the relevant Keycloak client settings to match the new address. Those changes are preserved on later bootstrap runs.

For more information, see:

Identity providers and LDAP¶

Configuration for LDAP, Active Directory, and external identity providers is part of administrator-managed Keycloak setup and is not treated like product-owned Required Config in this model.

This means these integrations can be configured and maintained in Keycloak without bootstrap overwriting them on later runs.