How to Fix “Key material not provided to setup HTTPS” Error in Keycloak

When setting up Keycloak with HTTPS, you might encounter the error: “Key material not provided to setup HTTPS. Please configure your keys/certificates or start the server in development mode.” This message typically indicates that Keycloak cannot find the necessary SSL certificates or keys to enable HTTPS. In this article, we’ll guide you through the steps to resolve this issue by properly configuring your SSL certificates or by starting the server in development mode for testing purposes.

1. Understanding the Error

Keycloak requires SSL certificates and key files to establish secure HTTPS connections. When these files are missing or misconfigured, Keycloak cannot start the HTTPS listener and throws the error mentioned above. This issue can occur if:

  • The certificate files (key material) are not provided.
  • The Keycloak server is not properly configured to use SSL certificates.
  • You are running Keycloak in a non-production environment where SSL certificates are not required.

2. Fixing the Issue: Configure SSL Certificates

To resolve this error, you need to provide the SSL certificates (key material) required by Keycloak. Follow these steps to configure HTTPS in Keycloak properly:

  1. Obtain or create an SSL certificate for your domain. If you’re testing locally or don’t want to use a certificate from a trusted CA (Certificate Authority), you can generate a self-signed certificate using OpenSSL. Here’s a command to generate a self-signed certificate:
  2. openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout keycloak.key -out keycloak.crt
  3. Move the generated certificate and key files to the appropriate directory on your server (e.g., /opt/keycloak/ssl or another directory of your choice).
  4. Edit the keycloak.conf configuration file to point to your SSL certificate and key files. Add the following lines:
  5. https.key-store-file=/opt/keycloak/ssl/keycloak.p12
  6. https.key-store-password=yourpassword
  7. https.key-store-provider=PKCS12
  8. If you’re using a self-signed certificate, make sure to disable SSL verification on clients or configure your clients to trust the certificate.
  9. Restart Keycloak to apply the changes:
  10. sudo systemctl restart keycloak

3. Option: Run Keycloak in Development Mode (for Testing Purposes)

If you don’t need to configure HTTPS in a development or test environment, you can bypass the SSL certificate configuration by starting Keycloak in development mode. This will disable HTTPS and allow you to access Keycloak over HTTP.

  1. Navigate to the Keycloak directory:
  2. cd /opt/keycloak
  3. Start Keycloak in development mode by setting the keycloak.profile environment variable to dev:
  4. ./bin/standalone.sh -Dkeycloak.profile=dev
  5. Alternatively, if you’re using Docker, you can start Keycloak in development mode with the following command:
  6. docker run -e KEYCLOAK_PROFILE=dev jboss/keycloak
  7. This will start Keycloak without requiring SSL certificates and will allow you to test it over HTTP.

4. Troubleshooting

If you continue to encounter issues after configuring the certificates or running in development mode, consider the following:

  • Double-check the file paths to ensure Keycloak is correctly pointing to the SSL certificate and key files.
  • Ensure that your firewall or security settings are not blocking the HTTPS port (usually port 443).
  • Look at the Keycloak logs for any additional error messages related to SSL configuration:
  • sudo tail -f /opt/keycloak/standalone/log/server.log
  • If you’re using a self-signed certificate, make sure your clients are configured to trust it, or disable SSL verification for testing purposes.

5. Conclusion

The “Key material not provided to setup HTTPS” error in Keycloak typically occurs when the server is not configured with the necessary SSL certificates or keys. By either providing the required certificates or running Keycloak in development mode, you can resolve this issue. For production environments, always ensure you use valid SSL certificates to secure your Keycloak server. For development and testing, running Keycloak in development mode can help bypass the need for SSL certificates temporarily.