Keycloak update leads to problems, e.g. with single sign-on (SSO)

Summary

If the edoc applications installed on edoc platform are running on a version with build no. 25.1.9 or higher, Keycloak is automatically updated to version 24 during synchronization. The update may cause problems with Kerberos authentication.

The authentication problem is caused by the fact that Keycloak 24 no longer supports outdated and insecure encryption algorithms such as RC4-HMAC. The problem mainly affects older Active Directory (AD) user accounts that still use RC4-HMAC.

You can solve the problem by switching users to the more modern and secure AES256-bit algorithm (Advanced Encryption Standard, AES) and regenerating the keytab file if necessary.

Important requirements

To resolve the problems described, you need access to various systems and knowledge.

• Access to the organization's system in edoc system control: Access to the organization's Kubernetes cluster to adjust the configurations.

• SSH access to the edoc platform server: You must have sudo permission.

• Linux shell knowledge: Sound knowledge of using the Linux command line to execute commands such as klist and ktpass.

• Administrative permissions for Active Directory: Access to the organization's Active Directory directory to edit the user accounts. If the edoc team manages the system for you as a customer, close cooperation is usually required.

• Help from IT experts for edoc-managed systems: Most changes are made in Active Directory. If the edoc team supports you as a customer, active support from you as our customer (e.g. IT administrator) is essential.

• Access to edoc system control and service user password: If the keytab file needs to be regenerated, you must have the appropriate permissions. You also need the password of the service user in Active Directory.

Solution

The first step is to update the outdated encryption in the organization's Active Directory. Then update the Kerberos tickets on the service user's client computer.

If problems continue to occur, you must check and repair the keytab file.

Step 1: Update encryption in Active Directory and Kerberos tickets

To update the outdated AES256-bit encryption:

1. Go to the server with Active Directory.

2. Open Active Directory users and computers.

3. Navigate to the affected user account of the service user.

4. Open the properties of the service user.

5. Go to the Account tab and activate the This account supports Kerberos AES 256-bit encryption option.

6. Save the changes.

How to update the Kerberos tickets on the edoc platform server:

1. Go to the edoc platform server to delete the old tickets encrypted with RC4-HMAC.

2. Open the command line and execute the command klist purge to empty the Kerberos ticket cache.

At the next login, a new Kerberos ticket with AES256-bit encryption is automatically issued, which is accepted by Keycloak 24.

If the problem has not been resolved, you must repair the keytab file on the organization's system in edoc system control.

Step 2: Repair defective or outdated "Keytab" file

If the authentication of a user still does not work, the problem is due to a faulty or outdated keytab file. The keytab file can interfere with communication between Keycloak and Active Directory.

You must first reset the password of the Keycloak service user in Active Directory in order to then regenerate the keytab file and deploy it in Kubernetes.

Proceed as follows to update the keytab file:

1. Go to the server with Active Directory.

2. Open Active Directory users and computers.

3. Reset the password of the service user in Active Directory for whom the keytab file was created. You can use the same password or a new one.

4. Generate a new keytab file with the ktpass command. Use the following pattern and replace the placeholders with your data:

   ktpass -out <file_name>.keytab -princ <ServicePrincipalName>@<REALM> -mapUser <User_name>@<DOMAIN> -pass <UserPassword> -ptype KRB5_NT_PRINCIPAL -crypto AES256-SHA1
   

5. Save the newly created keytab file locally to make this file available in your Kubernetes cluster for communication with Keycloak.

6. Go to edoc system control and open the affected system in your organization.

7. Click on Details for the system and on Configurations on the system page.

8. Click on Configure Kerberos in the Certificates section.

9. On the Configure Kerberos certificate page, upload the locally saved keytab file.

10. Save the configuration.

A corresponding task of type SyncSystemState is then automatically created in edoc system control to synchronize the new state of the system.