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 custom 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. For more information, see Configuring the Cloud Pak foundational services.

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.

You can backup and restore Keycloak data using the export and import features of Keycloak.

For more information, see Importing and exporting realms.

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. Access the Keycloak Administration console. For more information on accessing this Administration console, see Advanced Keycloak administration.

2. Select cloudpak from the realm selector.

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.

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 for Integration roles and permissions.

2. In the navigation pane, click Administration > Access control to open the "Access control" console.

3. Click Configure > 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 for Integration roles and permissions.

2. In the navigation pane, click Administration > Access control to open the "Access control" console.

3. Click Configure > 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 for Integration roles and permissions.

2. In the navigation pane, click Administration > Access control to open the "Access control" console.

3. Click Configure > 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.

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 for Integration roles and permissions.

2. In the navigation pane, click Administration > Access control to open the "Access control" console.

3. Click Configure > 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.

Use the Keycloak API to perform identity and access management operations. You get the Keycloak hostname from the URL of the "Access control" console. The Keycloak realm is cloudpak.

To get the URL of the "Access control" console:

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

2. In the navigation pane, click Administration > Access control,

For more information, see API documentation.

The Keycloak service has an OpenShift route that uses the OpenShift apps domain and the OpenShift router certificate.

To customize the hostname and 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 route. For installations using A single namespace of 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 update the hostname, 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>

5. 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 single namespace of 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 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}

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

   oc rollout restart statefulset/cs-keycloak

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

1. Get the cs-keycloak Route (which is the URL to access the Administrator console), the username, and the Keycloak administrator password from the secret named cs-keycloak-initial-admin. For installations that use A single namespace of the cluster mode, the secret is in the same namespace as your deployed instances. For installations that use All namespaces on the cluster mode, these are in the servicesNamespace (ibm-common-services by default) that is defined in the CommonService resource. For more information, see OpenShift Roles and permissions.

2. After logging in to the Administrator console, select the cloudpak realm from the realm selector to manage advanced realm configuration.