Keycloak configuration

6.14. Keycloak configuration#

This section outlines practical use cases for integrating Keycloak as an identity provider within Nubus for Kubernetes. It addresses DevOps engineers, system engineers, system administrators, and developers who are responsible for configuring authentication and identity management in Nubus for Kubernetes.

Through real-world scenarios, this section demonstrates how to adapt the Nubus for Kubernetes configuration to meet different authentication needs, helping you apply these solutions directly in your own infrastructure.

6.14.1. Multi-factor authentication for Keycloak#

Keycloak provides a multi-factor authentication (MFA) option. Another name is two-factor authentication (2FA), as configured in Keycloak, but for simplicity this section uses the generic term MFA.

MFA is an authentication method that grants users access to a service after they sign in with a password and a one-time password OTP. Third-party OTP password generators randomly generate the OTP. Such password generators are, for example, FreeOTP, 2FAS or Google Authenticator.

MFA increases the protection for user data, because users need to provide two pieces for authentication:

  1. Knowledge through a password.

  2. Ownership through something in the user’s possession, such as the OTP.

MFA also increases the security of the system by avoiding account locking on known accounts because of malicious attacks.

After you activate MFA for a group of users, Keycloak asks those users for their OTP on each login. To activate or deactivate MFA for a user group, follow the instructions in the next sections

See also

Multi-factor authentication - Wikipedia

for more information about multi-factor authentication.

6.14.1.1. Activate MFA for domain administrators#

To simplify the configuration process, you need to edit your custom_values.yaml file to enable MFA, as outlined in the following steps:

  1. To activate MFA in Keycloak, add the lines in Listing 6.34 to your custom_values.yaml values file.

    The configuration uses the following values:

    Listing 6.34 Enable multi-factor authentication for domain administrators#
    nubusKeycloakBootstrap:
  bootstrap:
    twoFactorAuthentication:
      enabled: "true"
      group: "Domain Admins"

  2. To apply the configuration, follow the steps in Apply configuration.

6.14.1.2. Deactivate MFA for domain administrators#

Note

You enabled MFA through the values listed above in custom_values.yaml. However, removing these entries does not fully disable MFA, because enabling it makes persistent changes within the system. To completely deactivate MFA and revert these changes, you must perform manual steps.

To deactivate MFA, you need to remove values listed above in custom_values.yaml and remove the role 2FA role from the group in Keycloak, as outlined in the following steps:

  1. To sign in to the Keycloak Admin Console, use your web browser and navigate to the following URL scheme: https://id.$(global.domain)/admin. The value in global.domain completes the FQDN of the URL.

    Example:

    https://id.nubus.example.com/admin, where nubus.example.com is the value in global.domain.

  2. In the Keycloak Admin Console, navigate to realm nubus.

  3. Select Groups and choose Domain Admins in the list.

  4. On the tabs, navigate to Role Mappings.

  5. Next to 2FA role click the three dots and hit Unassign.

  6. Confirm the dialog by clicking Remove.

6.14.2. Configure additional LDAP mappers#

This section describes how you configure additional LDAP mappers for Keycloak. These mappers keep your OIDC token fields current by reading them directly from the directory service instead of from Keycloak’s cache.

When nubusKeycloakBootstrap.bootstrap.userFederation.ldapImportUsers is true, the default, Keycloak caches the user object from the directory service on first sign-in. User objects in the directory service have mutable attributes that may change. If these attributes change, Keycloak must read them directly from the directory service to ensure OIDC tokens contain the latest values.

You define LDAP mappers as a dictionary in the nubusKeycloakBootstrap.bootstrap.ldapMappers Helm Chart value in your custom_values.yaml file. Each key is the attribute name and the value contains the configuration for that attribute. Listing 6.35 shows an example where OXContextId is always read from the directory service but department isn’t.

Listing 6.35 Example for LDAP mapper in custom_values.yaml#
nubusKeycloakBootstrap:
   bootstrap:
     ldapMappers:
       OXContextId:
         alwaysReadFromLdap: true
       department:
         alwaysReadFromLdap: false

6.14.2.1. LDAP mapper field reference#

The mapper entry supports the following fields:

alwaysReadFromLdap

If set to true, Keycloak reads the attribute value from the directory service instead of from the cache. Use this field for user object attributes that change over time.

Type:

boolean

Default value:

true

6.14.2.2. Configuration steps for LDAP mappers#

Before you begin, make sure you have the following:

  • You understand the LDAP mapper structure shown in Listing 6.35.

  • You’ve identified which user attributes need direct reads from the directory service. These attributes should have alwaysReadFromLdap: true.

To configure LDAP mappers, use the following steps:

  1. Review the LDAP mapper structure in Listing 6.35. Open your custom_values.yaml file.

  2. Add the nubusKeycloakBootstrap.bootstrap.ldapMappers configuration under the nubusKeycloakBootstrap.bootstrap section, following the structure from the example. For each LDAP attribute you want to synchronize, complete the following:

    • Add a key with the attribute name, such as OXContextId or department.

    • For attributes that change over time, set alwaysReadFromLdap: true.

    • For attributes that remain static, set alwaysReadFromLdap: false.

    Note

    If the ldapMappers section doesn’t exist, create it. You can add multiple mappers in a single edit.

  3. Apply the configuration by following the steps in Apply configuration.

6.14.3. Audit logging for Keycloak#

Keycloak emits audit events such as user sign-ins, sign-outs, and sign-in failures through its built-in jboss-logging event listener. By default, Keycloak emits successful events at the debug log level and error events at the warn log level. Because the standard log output threshold is info, successful audit events aren’t visible unless you enable debug logging.

This section explains how to configure Keycloak to make audit events visible to centralized logging solutions without enabling full debug mode. You can adjust the log level for each event category independently to match your monitoring needs.

Use this configuration for production deployments where you need to monitor user authentication events with centralized logging.

Note

Promoting successful events to info level increases log volume because every sign-in, sign-out, and token refresh produces a log entry. In high-traffic deployments, plan your log storage capacity and retention policies accordingly.

Warning

Audit log entries include usernames and IP addresses, which are personal data under regulations such as GDPR. Apply appropriate access controls and retention policies to your log storage.

Keycloak emits the following audit events at the levels you configure:

Successful events:

LOGIN, LOGOUT, CODE_TO_TOKEN, REFRESH_TOKEN

Error events:

LOGIN_ERROR

To enable audit logging, use the following steps:

  1. Add the lines in Listing 6.36 to the nubusKeycloak section of your custom_values.yaml file.

    Listing 6.36 Configure Keycloak audit log levels#
    nubusKeycloak:
  extraEnvVars:
    - name: "KC_SPI_EVENTS_LISTENER__JBOSS_LOGGING__SUCCESS_LEVEL"
      value: "info"
    - name: "KC_SPI_EVENTS_LISTENER__JBOSS_LOGGING__ERROR_LEVEL"
      value: "warn"

  2. To apply the configuration, follow the steps in Apply configuration.

  3. Verify the configuration by reviewing the Keycloak logs for audit events. Look for LOGIN, LOGOUT, and CODE_TO_TOKEN events at the info level, and LOGIN_ERROR events at the warn level.

The configuration uses the following Helm Chart values:

KC_SPI_EVENTS_LISTENER__JBOSS_LOGGING__SUCCESS_LEVEL

Sets the log level for successful events. Use info to display sign-in and sign-out events in the standard log output.

KC_SPI_EVENTS_LISTENER__JBOSS_LOGGING__ERROR_LEVEL

Sets the log level for error events. Use warn to display sign-in failures in the standard log output.

On this page