Keycloak#

Overview#

Keycloak is the NVIDIA Mission Control identity provider. It issues the OpenID Connect tokens that front-end applications such as Launchpad use to authenticate operators, and it can broker an external OAuth2 identity provider and federate BCM’s LDAP users into the realm. Its realm state persists in a CloudNativePG-backed PostgreSQL cluster, and a one-time realm import applies the NVIDIA Mission Control realm, clients, and federation configuration.

How it works#

Keycloak is delivered as three Argo CD Applications:

keycloak: The KeycloakX identity provider.
keycloak-cnpg: Its PostgreSQL database, a CloudNativePG Cluster reconciled by the shared cnpg-operator (refer to CloudNativePG).
keycloak-config-cli: The realm import that applies the NVIDIA Mission Control realm, its clients, and any OAuth2 broker or BCM LDAP federation you enable.

Keycloak’s admin password, database password, and client secrets come from OpenBao. You provide them in secrets.yaml (Secrets), not in the values file. External Secrets and the OpenBao injector deliver them to the workloads (refer to External Secrets Operator and OpenBao).

%%{init: {'theme': 'base', 'themeVariables': {'lineColor': '#888888', 'edgeLabelBackground': '#e8e8e8'}}}%% flowchart TB OB["OpenBao"] Inj["Vault Agent injector"] ES["External Secrets"] subgraph kc["keycloak namespace"] Pod["KeycloakX pod"] DB["PostgreSQL Cluster"] end OB --> Inj OB --> ES Inj -.->|"admin + LDAP secrets at runtime"| Pod ES -.->|"database password"| DB ES -.->|"database password"| Pod style kc fill:#eef5ff,stroke:#1565c0,stroke-width:2px style OB fill:#ef7b4d,stroke:#c5410a,color:#fff style Inj fill:#e3f2fd,stroke:#1565c0,color:#000 style ES fill:#e3f2fd,stroke:#1565c0,color:#000 style Pod fill:#fffde7,stroke:#f9a825,color:#000 style DB fill:#fffde7,stroke:#f9a825,color:#000 linkStyle default stroke-width:1.5px

Configuration#

Add these settings under the keycloak, keycloakCnpg, and keycloakConfigCli keys in values.yaml. Each key already carries the pinned version and syncWave from Installing GitOps-Managed Components; the following fields are the ones you set. A field shown with a value uses that value as its default when you omit it.

The keycloak block configures the identity provider.

keycloak:
  fqdn: <keycloak-fqdn>                # set to your Keycloak host name; defaults to keycloak.dgx-<cluster-name>.nvidia.com
  realm: nmc                           # optional, realm Keycloak serves and the import targets
  routeEnabled: true                   # optional, emit the external Gateway route
  serviceMonitorEnabled: false         # optional, scrape Keycloak metrics with a ServiceMonitor
  realmImportEnabled: false            # set true for the standard install; creates the nmc realm and its OIDC clients
  oauth2Enabled: false                 # optional, broker an external OAuth2 identity provider
  oauth2Alias: nmc                     # optional, broker alias used when oauth2Enabled
  oauth2BaseUrl: <oauth2-base-url>     # set to the external provider base URL when oauth2Enabled
  ldapEnabled: false                   # optional, federate BCM LDAP users into the realm
  ldapHost: ldapserver.cm.cluster      # BCM LDAP host name; must match its server cert SAN
  ldapHostIp: 10.141.255.254           # set to your BCM LDAP server address

fqdn – the Keycloak host name. Defaults to keycloak.dgx-<cluster-name>.nvidia.com. Set it to your environment’s host name.
realm – the realm Keycloak serves and the import targets. Default nmc.
routeEnabled – emit the external Gateway route. Default true.
serviceMonitorEnabled – scrape Keycloak metrics with a ServiceMonitor. Default false.
realmImportEnabled – run the keycloak-config-cli realm import. Default false. Set it to true for the standard install. The import creates the nmc realm and the nmc-launchpad, argocd, and argocd-cli OIDC clients that Launchpad and Argo CD single sign-on require. It drives keycloakConfigCli.enabled.
oauth2Enabled – broker an external OAuth2 identity provider. Default false.
oauth2Alias – the broker alias for the external OAuth2 provider. Default nmc. Used when oauth2Enabled.
oauth2BaseUrl – the external provider base URL. No default. Set it when oauth2Enabled.
ldapEnabled – federate BCM’s LDAP users into the realm. Default false. Refer to BCM LDAP authentication (optional).
ldapHost – the BCM LDAP server host name, which must match its server certificate SAN. Default ldapserver.cm.cluster. Used when ldapEnabled.
ldapHostIp – the address of your BCM LDAP server. The Keycloak Pod resolves ldapHost to it through a hostAlias, so the server certificate SAN matches. Confirm the address for your cluster. Default 10.141.255.254.

The keycloakCnpg block configures the CloudNativePG database.

keycloakCnpg:
  instances: 2                         # optional, number of PostgreSQL instances
  storageSize: 2Gi                     # optional, per-instance volume size
  monitoringEnabled: false             # optional, enable CNPG monitoring

instances – number of PostgreSQL instances. Default 2.
storageSize – per-instance volume size. Default 2Gi.
monitoringEnabled – enable CNPG monitoring. Default false.

The keycloakConfigCli block configures the realm import.

keycloakConfigCli:
  launchpadRedirectUri: https://<launchpad-fqdn>/*   # optional, OAuth redirect URI for the Launchpad client
  launchpadWebOrigin: https://<launchpad-fqdn>       # optional, OAuth web origin for the Launchpad client
  ldapBaseDn: dc=cm,dc=cluster                       # optional, BCM LDAP users base DN
  ldapBindDn: cn=readonlyroot,dc=cm,dc=cluster       # optional, BCM LDAP bind DN

launchpadRedirectUri – the OAuth redirect URI for the Launchpad client. Defaults to https://<launchpad-fqdn>/*.
launchpadWebOrigin – the OAuth web origin for the Launchpad client. Defaults to https://<launchpad-fqdn>.
ldapBaseDn – the BCM LDAP users base DN. Default dc=cm,dc=cluster.
ldapBindDn – the BCM LDAP bind DN. Default cn=readonlyroot,dc=cm,dc=cluster.

Cross-field consistency rules:

When oauth2Enabled is true, both oauth2Alias and oauth2BaseUrl must be non-empty, and you must set the OAuth2 IDP credentials in secrets.yaml.
When ldapEnabled is true, ldapHost must be non-empty and must match the BCM LDAP server certificate SAN.
When ldapEnabled is true, k8s_bootstrap_secrets_ldap_enabled must also be true in secrets.yaml. Refer to BCM LDAP authentication (optional).

Secrets#

Keycloak consumes bootstrap secrets. Leave the admin and database passwords empty to auto-generate them. The OAuth2 IDP and BCM LDAP blocks are needed only when their feature is enabled. Add them to secrets.yaml:

k8s_bootstrap_secrets_keycloak_admin_password: ""       # Keycloak admin password (user is admin); leave empty to auto-generate
k8s_bootstrap_secrets_keycloak_database_password: ""    # PostgreSQL password for the keycloak user; leave empty to auto-generate

# Only when brokering an external OAuth2 identity provider:
k8s_bootstrap_secrets_oauth2_idp_enabled: false
k8s_bootstrap_secrets_oauth2_idp_client_id: <client-id>          # required when enabled
k8s_bootstrap_secrets_oauth2_idp_client_secret: <client-secret>  # required when enabled

# Only when federating users from BCM LDAP (seed on the BCM head node):
k8s_bootstrap_secrets_ldap_enabled: false

k8s_bootstrap_secrets_keycloak_admin_password – the Keycloak admin password. The user name is admin. Leave it empty to auto-generate.
k8s_bootstrap_secrets_keycloak_database_password – the PostgreSQL password for the keycloak user. Leave it empty to auto-generate.
k8s_bootstrap_secrets_oauth2_idp_* – the external provider client id and secret. Required when k8s_bootstrap_secrets_oauth2_idp_enabled is true.
k8s_bootstrap_secrets_ldap_enabled – seed the BCM LDAP bind password and client certificate. Set it together with keycloak.ldapEnabled. Refer to BCM LDAP authentication (optional).

The Launchpad OIDC client secret is seeded with Keycloak. It is documented on NMC Launchpad.

BCM LDAP authentication (optional)#

BCM publishes its users in an LDAP directory. Keycloak federates that directory into the realm over a mutual TLS connection, so BCM accounts sign in to NVIDIA Mission Control through Keycloak.

These settings federate BCM’s directory. To sign users in from another identity provider, broker it with oauth2Enabled.

Turn it on in both files:

values.yaml: set keycloak.ldapEnabled: true, and set ldapHostIp to your BCM LDAP server address.
secrets.yaml: set k8s_bootstrap_secrets_ldap_enabled: true.

ldapEnabled makes OpenBao expect the LDAP material and the seed creates it, so the OpenBao configure Job fails when the two disagree.

The realm import generates the rest: the federation provider, its user and group mappers, the Keycloak keystore and truststore wiring, and the host alias.

Operations#

Secret rotation is a direct bao kv put under nmc-admin. The configure Job’s KV load is create-only and will not overwrite an existing path. A full rotation also requires changing the value where the component already stored it, because a running component does not re-read a rotated KV path on its own:

Rotating keycloak/database does not change the running PostgreSQL password. initdb honors the password only on first install, so the live password must be changed in PostgreSQL (for example with ALTER USER) to match.
Rotating the admin or client secrets requires the corresponding Keycloak Admin API update or a keycloak-config-cli rerun.

Warning

Rotating keycloak/realm/<realm>/user-federation/bcm-ldap requires a manual rollout restart of the KeycloakX workload. The injector renders the LDAP keystore, CA, and bind material only at Pod start, so the new material does not take effect until the Pod is recycled.

The BCM LDAP client certificate the seed mints is valid for 365 days. Plan its replacement before it expires. The seed and the configure Job both write once, so replacing the certificate means writing the new material to the KV path directly and restarting the KeycloakX workload.

To add or remove a federated identity source or client, change the keycloak and keycloakConfigCli settings, seed any new KV path, and rerun the realm import. Refer to Installing GitOps-Managed Components for the deploy mechanics.

Verify#

Confirm Keycloak:

Confirm the three Keycloak Applications report Healthy in Argo CD: keycloak, keycloak-cnpg, and keycloak-config-cli. The keycloak-cnpg Application needs the shared cnpg-operator Healthy first.
Confirm the CNPG Cluster reports its instances ready and that the keycloak-cnpg-cluster-password Secret exists in the keycloak namespace.
Confirm the realm import completed and that the configured realm and the nmc-launchpad, argocd, and argocd-cli clients are present.
When BCM LDAP or OAuth2 is enabled, confirm the federation provider or broker alias appears in the realm.
When BCM LDAP is enabled, Keycloak imports the accounts about five minutes after the realm import creates the federation provider. To import them immediately, open User federation > bcm-ldap and select Action > Sync all users.