ARD Hub Installation: Keycloak Fails to Connect to MySQL 8.0+

Products

• CA Agile Requirements Designer

Issue/Introduction

When performing a manual installation or upgrade of ARD Hub 3.6 on Windows with MySQL 8.0.x, the installation fails during the Keycloak configuration phase. Common symptoms include:

• Keycloak UI returns a 'Page Not Found' error.
• The keycloak-setup.bat script fails to populate security roles, user groups, or realms.
• Logs indicate a failure to establish a connection to the MySQL database.

Environment

• Product: CA Agile Requirements Designer (ARD) Hub 3.6
• Database: MySQL 8.0.0 or higher
• OS: Windows Server

Cause

MySQL 8.0 introduced caching_sha2_password as the default authentication mechanism. This requires the JDBC driver to retrieve the server's RSA public key to encrypt the password during the handshake. By default, the JDBC driver disables this retrieval for security reasons. When using a non-SSL connection (common in local or firewalled internal deployments), the connection is refused because the driver cannot fetch the public key.

Resolution

To resolve this, you must explicitly permit the JDBC driver to retrieve the public key or switch the MySQL user to a legacy authentication method.

Method 1: Modify the JDBC URL (Recommended)

Add the allowPublicKeyRetrieval=true and useSSL=false parameters to your JDBC connection string.

1. Stop the Apache Tomcat service.
2. Locate your ARD Hub configuration files (typically in .ard\conf).
3. Update the JDBC URL in the datasource configuration:
   • From: jdbc:mysql://<hostname>:3306/keycloak?useUnicode=true&characterEncoding=utf-8
   • To: jdbc:mysql://<hostname>:3306/keycloak?useUnicode=true&characterEncoding=utf-8&allowPublicKeyRetrieval=true&useSSL=false
4. Clear the .ard\logs directory.
5. Rebuild Keycloak:
   • Open a command prompt as Administrator.
   • Navigate to KEYCLOAK_HOME\bin.
   • Run the command: kc.bat build.
6. Start Keycloak using kc.bat start and verify there are no startup errors.
7. Run the HUB_INSTALL\keycloak\keycloak-setup.bat to populate roles.
8. Restart Apache Tomcat.

Method 2: Alter MySQL User Authentication

If you cannot modify the connection string, you can change the MySQL user to use the legacy native password plugin.

1. Log in to your MySQL instance as root.
2. Execute the following SQL command:
   sql

    

   ALTER USER 'ard_user'@'%' IDENTIFIED WITH mysql_native_password BY 'your_password';FLUSH PRIVILEGES;

3. Restart the Keycloak and Tomcat services.

Verification

1. Check the .ard\logs for any SQL Error: 90020 or connection refusal warnings.
2. Open a browser and navigate to http://<tomcat_address>:8080/ard/ui.
3. Verify you can reach the login page and authenticate successfully.