Keycloak User Federation using LDAP over SSL

This feature is supported from GV Essentials version 4.5.51

The CLI sections are exclusive to Helm and Air-gapped systems - these steps are not required for clusters connected to Rancher. There are no line breaks in the commands, unless otherwise noted.

1. Get CA certificate from customer

The customer is asked to provide the CA certificate that was used to sign the end-entity certificate of the LDAP server. We are adding this Keycloak’s trust store to make sure the LDAP server’s certificate validates successfully. The provided CA certificate must be an X.509 v3 certificate in the ASCII PEM format (Base64-encoded). The file extension is usually .crt or .cer or .pem. Its content looks like this:

-----BEGIN CERTIFICATE-----
MIIGBTCCA+2gAwIBAgIUaIGnTiJx27iBiIF+4jIkb7o5miswDQYJKoZIhvcNAQEL
...
-----END CERTIFICATE-----

Optional Checks

1. The following command confirms that the cert is in the expected format and that it is, in fact, a CA certificate. Validity is not checked here.

# openssl x509 -in /path/to/ca.crt -text -noout | grep CA

                    CA:TRUE

1. The next command validates the LDAP server’s certificate against the provided CA certificate in the customer’s environment, where the LDAP server is accessible on port 636:

# echo "q" | openssl s_client -connect dc.mycompany.com:636 -CAfile /path/to/ca.crt | grep -i verif

depth=1 C = IE, ST = Ireland, L = Cork, O = MyCompany Ltd, CN = mycompany.com, emailAddress = [e-mail]
verify return:1
depth=0 CN = mycompany.com
verify return:1
DONE
Verification: OK
Verify return code: 0 (ok)

2. Create JKS truststore file

This command will create a JKS truststore file (ca.jks) and add the certificate (ca.crt) to it, protecting it with a password (STR0ngPA55). # keytool -importcert -file ca.crt -keystore ca.jks -alias rootca -storepass STR0ngPA55 -noprompt

3. Encode truststore file with Base64

# base64 -w 0 ca.jks

MIIHggIBAzCCBywGCSqGSIb3DQEHAaCCBx0EggcZMIIHFTCCBxEGCSqGSIb3DQEHBqCCBwIwggb+A(...)

4. Push trust store file to Keycloak

Rancher

Apps > Installed Apps > gv-essentials > Keycloak:

• Leave the Keycloak URL settings field unchanged.

• Check Enable Keycloak for LDAP over SSL.

• Enter password for truststore.

• Paste value from Step 3 into the Base64 .jks file field.

• Click Upgrade in bottom right corner.

CLI

• Set KUBECONFIG environment variable: # export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

• Save the truststore file with base64 encoding to a variable: # export cert=$(base64 -w 0 ca.jks)

• Print the variable and confirm it has the right value: # echo "$cert"

  MIIHggIBAzCCBywGCSqGSIb3DQEHAaCCBx0EggcZMIIHFTCCBxEGCSqGSIb3DQEHBqCCBwIwggb+A(...)

• Upgrade or reinstall the gv-essentials chart, adding new values while reusing existing ones: # helm upgrade --install gv-essentials gv_stable/gv-essentials --wait --debug --timeout=10m0s --kubeconfig /etc/rancher/k3s/k3s.yaml --reuse-values --set keycloak.ldaps.enabled=true --set keycloak.ldaps.truststorecert="$cert" --set keycloak.ldaps.truststorepass="STR0ngPA55"

5. Restart Keycloak

This ensures the new truststore is loaded.

Rancher

Workloads > StatefulSets > gv-keycloak:

• Choose the Redeploy option.

CLI

# kubectl rollout restart statefulset gv-keycloak

6. Configure User federation in Keycloak correctly

Enable StartTLS: OFF (default) - This must be turned OFF - communication will regardless be encrypted.

Use Truststore SPI: Always (default) - This ensures that the imported certificate store is used to validate the LDAP server’s certificate.

For further information, see here.

7. Test connectivity, credentials, and user sync

Use the Test connection and Test authentication buttons to make sure both connection and authentication to the LDAP server is successful.

Ideally, both tests return success. (The exact same message is printed for both the connection and the authentication test.)

8. Troubleshooting

Below is an example of a message seen on the Keycloak side (web) and its counterpart in the logs of the Keycloak service (pods named gv-keycloak-…).

1.

2024-07-16 09:17:02,557 ERROR [org.keycloak.services] (executor-thread-6) KC-SERVICES0055: Error when authenticating to LDAP: Cannot invoke "org.keycloak.truststore.TruststoreProvider.getSSLSocketFactory()" because "provider" is null: java.lang.NullPointerException: Cannot invoke "org.keycloak.truststore.TruststoreProvider.getSSLSocketFactory()" because "provider" is null

Keycloak is trying to read trust store to validate a certificate, but the trust store has not been loaded, it could be missing from inside the Keycloak pod (/opt/keycloak/certs/rootCA.jks)

• Trust store has not been installed via the GetVisibility Essentials Helm chart?

  • Redo step 4.

• Keycloak has not been restarted after installing certificate?

  • Redo step 5.