Keycloak configuration

Keycloak uses either the default storage class in Red Hat OpenShift Container Platform, or the storage class configured in the IBM Cloud Pak® foundational services Kubernetes resource. Before installing instances, do one of the following:

• Set a default storage class by adding the storageclass.kubernetes.io/is-default-class:'true' annotation in Red Hat OpenShift Container Platform.

• Specify a storage class name for spec.storageClass in the CommonService resource.

The following are characteristics of the database that Keycloak uses:

• Requires block storage that is configured to use the XFS or ext4 file system. RWO accessMode is required. The file systems (XFS and ext4) are POSIX-compliant and fully compatible with all supported OpenShift Container Platform releases.

• Supports a volumeBindingMode of either Immediate or WaitForFirstConsumer to control volume binding and dynamic provisioning.

  Important: If your installation is in an environment with multiple availability zones, the value of volumeBindingMode must be WaitForFirstConsumer. Otherwise, the Keycloak installation will fail.

You can back up and restore Keycloak data by using the Red Hat OpenShift API for Data Protection (OADP). For more information, see Backing up and restoring IBM Cloud Pak for Integration.

The default password policy for Keycloak users in Cloud Pak for Integration is the following:

• Must be at least 15 characters long.

• Cannot contain the username.

• Cannot contain the email address.

To customize the password policy:

1. Log in to the Keycloak Admin Console. For the procedure, see Advanced Keycloak administration.

2. Change the realm to cloudpak. Click Manage realms in the navigation panel, then click cloudpak make that the current realm.

3. Click Configure > Authentication.

4. Click the Policies tab.

5. Click the Password policy sub-tab.

6. Update the password policy as needed.

7. Click Save.

For more information, see Password policy in the Red Hat documentation.

You can enable Keycloak users to reset their own passwords.

In addition to the steps in this section, make sure to update the email server settings in the "Configuring email" section, so that Keycloak can use a user's email address to reset their password.

1. Log in to the Platform UI as a user with realm management permissions. For more information, see Cloud Pak roles and permissions.

2. Click the Navigation Menu icon next to IBM Cloud Pak for Integration in the banner, then click Administration > Access control. The Keycloak access control console opens.

3. In the navigation pane, click Realm settings.

4. Click the Login tab.

5. Enable the Forgot password option.

There are two options for configuring user email verification in Keycloak:

• Enable email verification - Configure Keycloak to send emails that verify those user email addresses.

• Disable email verification - Configure Keycloak so that it automatically trusts email addresses discovered by using an identity provider or federated user store. For more information, see the documentation for configuring identity providers or federated user stores in Managing users and groups.

To enable or disable email verification:

1. Log in to the Platform UI as a user with realm management permissions. For more information, see Cloud Pak roles and permissions.

2. Click the Navigation Menu icon next to IBM Cloud Pak for Integration in the banner, then click Administration > Access control. The Keycloak access control console opens.

3. In the navigation pane, click Realm settings.

4. Click the Login tab.

5. Set the Verify email option to on if you want to enable email verification. To disable email verification, set the option to off.

To configure Keycloak to send email:

1. Log in to the Platform UI as a user with realm management permissions. For more information, see Cloud Pak roles and permissions.

2. Click the Navigation Menu icon next to IBM Cloud Pak for Integration in the banner, then click Administration > Access control. The Keycloak access control console opens.

3. In the navigation pane, click Realm settings.

4. Click the Email tab.

5. Enter your email server settings.

6. Click Save.

For more information, see Configuring email for a realm in the Red Hat documentation.

You can configure the idle timeout and maximum session length for Cloud Pak for Integration by changing Keycloak realm settings.

1. Log in to the Platform UI as a user with realm management permissions. For more information, see Cloud Pak roles and permissions.

2. Click the Navigation Menu icon next to IBM Cloud Pak for Integration in the banner, then click Administration > Access control. The Keycloak access control console opens.

3. In the navigation pane, click Realm settings.

4. Click the Sessions tab.

5. Configure timeout on the Sessions page. The SSO Session Idle setting controls how long a user can be idle before they are automatically logged out. The SSO Session Max controls the maximum length of time that a user can be logged in before they have to reauthenticate.

6. Click Save.

For more information, see User session timeouts in the Red Hat documentation.

Use the Keycloak API to perform identity and access management operations. The Keycloak realm is cloudpak.

Get the Keycloak hostname from the URL of the Red Hat Build of Keycloak console:

1. Log in to the Platform UI as a user with realm management permissions. For more information, see Cloud Pak roles and permissions.

2. Click the Navigation Menu icon next to IBM Cloud Pak for Integration in the banner, then click Administration > Access control. The Keycloak access control console opens.

3. Copy the hostname from the URL.

For more information, see API documentation in the Red Hat documentation.

Keycloak has an OpenShift route with a hostname that has the format https://keycloak-<namespace>.apps.<cluster domain>.

To customize the hostname, you must be a user with namespace admin permissions. For more information, see OpenShift roles and permissions.

1. Change the .data.keycloak_route_name parameter value in the ibm-cpp-config ConfigMap to your custom hostname:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: ibm-cpp-config
     namespace: <keycloak-namespace>
   data:
     keycloak_route_name: <hostname>

2. To apply the configuration changes, restart the operand-deployment-lifecycle-manager pod in your operator namespace:

   oc delete pods -l app.kubernetes.io/instance=operand-deployment-lifecycle-manager -n <operator namespace>

3. To confirm the new custom route, restart the Platform UI pods:

oc delete pods -l app.kubernetes.io/name=ibm-integration-platform-navigator -n <namespace_for_platform_ui>

Keycloak uses the OpenShift apps domain and the OpenShift router certificate.

To customize the certificate, you must be a user with namespace admin permissions. For more information, see OpenShift roles and permissions.

1. Generate the following custom certificates in an unencrypted PEM format:

   • tls.crt - Contains the certificate, which is valid for the specific custom hostname.

   • tls.key- Contains the private key of the certificate.

   • ca.crt - (Optional) You can specify a CA certificate, if needed, to complete the certificate chain.

2. Identify the namespace that contains the Keycloak route. For installations using A specific namespace on the cluster mode, this is the same namespace where your instances are deployed. For installations using All namespaces on the cluster mode, this is the servicesNamespace defined in the CommonService resource (which is ibm-common-services by default).

   Set this namespace as an environment variable to use in further commands:

   KEYCLOAK_NAMESPACE=<namespace>

3. Create a secret named keycloak-custom-tls-secret by using the custom certificates that you created in the first step:

   oc create secret generic keycloak-custom-tls-secret --from-file=tls.crt=tls.crt --from-file=tls.key=tls.key -n ${KEYCLOAK_NAMESPACE}

   If the optional CA certificate is needed, run the following command:

   oc create secret generic keycloak-custom-tls-secret --from-file=ca.crt=ca.crt --from-file=tls.crt=tls.crt --from-file=tls.key=tls.key -n ${KEYCLOAK_NAMESPACE}

4. To apply the configuration changes, restart the operand-deployment-lifecycle-manager pod in your operator namespace:

   oc delete pods -l app.kubernetes.io/instance=operand-deployment-lifecycle-manager -n <operator namespace>

You can add certificates to the Keycloak trust store so that Keycloak securely connects to services protected by a custom certificate authority.

To add certificates to the Keycloak trust store, you must be a user with namespace admin permissions. For more information, see OpenShift roles and permissions.

1. Identify the namespace that contains Keycloak. For installations using A specific namespace on the cluster mode, this is the same namespace where your instances are deployed. For installations using All namespaces on the cluster mode, this is the servicesNamespace defined in the CommonService resource (which is ibm-common-services by default).

   Set this namespace as an environment variable to use in further commands:

   KEYCLOAK_NAMESPACE=<namespace>

2. Create the resource with your additional certificates.

   If using Keycloak version 22 or 24, create a configmap named cs-keycloak-ca-certs with your additional certificates. Use one key for each certificate:

   oc create configmap cs-keycloak-ca-certs --from-file=cert1.pem --from-file=cert2.pem -n ${KEYCLOAK_NAMESPACE}

   If using Keycloak version 26, create a secret named cs-keycloak-ca-certs with your additional certificates. Use one key for each certificate:

   oc create secret generic cs-keycloak-ca-certs --from-file=cert1.pem --from-file=cert2.pem -n ${KEYCLOAK_NAMESPACE}

3. To apply the configuration changes, restart the cs-keycloak pods:

   oc rollout restart statefulset/cs-keycloak -n ${KEYCLOAK_NAMESPACE}

By default, Keycloak and the Cloud Native PostgreSQL instances are deployed with the starterset sizing profile. To configure the resources and storage for your Keycloak installation, update the CommonService Kubernetes resource to use a different profile. For more information, including advanced configuration, see Configuring the Cloud Pak foundational services.

1. Log into the OpenShift web console as an administrator.

2. Get the login credentials from the Keycloak secret.

   1. In the navigation pane, click Workloads > Secrets.

   2. From the Project dropdown, select the namespace that contains the Keycloak secret, which is named cs-keycloak-initial-admin:

      • For installations that use A specific namespace on the cluster mode, the secret is in the same namespace as your deployed instances.

      • For installations that use All namespaces on the cluster mode, the secret is in the servicesNamespace (ibm-common-services by default) that is defined in the CommonService resource. For more information, see OpenShift roles and permissions.

   3. From the Data section of the secret, copy the username and the Keycloak administrator password.

      Attention:

      • If you change the password for this Keycloak administrator user in the Keycloak UI, you must also update the password value in the cs-keycloak-initial-admin secret. If you do not update the password, the IBM Cloud Pak for Integration operator cannot function and instances with user interfaces have errors.
      • As stated before, do not use this Keycloak administrator password for identity and access management. The Keycloak administrator is an advanced admin user that is used by the IBM Cloud Pak for Integration operator.

3. Get the URL for logging in to the Keycloak Admin Console.

   1. In the navigation pane, click Networking > Routes.

   2. From the Project dropdown, select the namespace that contains the Keycloak route:

      • For installations that use A single namespace on the cluster mode, this is the namespace in which your instances are deployed.

      • For installations that use All namespaces on the cluster mode, this is the servicesNamespace (named ibm-common-services by default) that is defined in the CommonService resource.

   3. Copy the Keycloak URL, for example, https://keycloak-ibm-common-services.apps.ibm.com.

4. Paste the Keycloak URL in your browser to access the Keycloak Administrator console.

5. Log in to the Admin Console by using the login credentials (username and password) from step 2.

6. In the navigation panel, click Manage realms, then click cloudpak to change the realm setting from the default (master).

You can now manage advanced realm configuration.