Posted on

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.

Posted on

Configuring Proxy Mode in Keycloak: Old vs. New Versions

Keycloak offers a “Proxy Mode” configuration for environments where Keycloak is behind a reverse proxy. This configuration ensures that Keycloak can work correctly when it’s behind a load balancer or proxy, by properly handling forwarded headers and request information. However, the method to configure Proxy Mode has changed slightly between older and newer versions of Keycloak. In this article, we will walk through how to configure Proxy Mode in both old and new versions of Keycloak.

1. Proxy Mode in Older Keycloak Versions (Pre-2020)

In older versions of Keycloak (pre-2020), enabling Proxy Mode was done through the standalone.xml configuration file. This file is part of the Keycloak standalone server configuration, and you would need to edit it to enable the proxy mode and configure related settings.

To enable Proxy Mode in older versions, follow these steps:

  1. Navigate to the Keycloak configuration directory:
  2. cd /opt/keycloak/standalone/configuration
  3. Open the standalone.xml file in a text editor:
  4. sudo nano standalone.xml
  5. Locate the <http-listener> section for the HTTP and HTTPS listeners.
  6. Find the section that configures proxy-related settings:
  7. <proxy-mode>…
  8. Set the proxy-mode tag to one of the following values:
    • off: No proxy is being used.
    • edge: The reverse proxy is at the edge (directly connected to the client).
    • reencrypt: The reverse proxy decrypts the traffic and forwards it to Keycloak in plaintext.
    • passthrough: The reverse proxy forwards traffic without modifying it.
  9. <proxy-mode>edge</proxy-mode>
  10. Save the changes and restart Keycloak:
  11. sudo systemctl restart keycloak

2. Proxy Mode in Newer Keycloak Versions (Post-2020)

In newer versions of Keycloak (post-2020), the Proxy Mode configuration has shifted to a more modern approach, relying on the keycloak.conf file or environment variables, especially for containerized environments. The reverse proxy is still supported, but Keycloak now uses the keycloak.conf file or Docker/Kubernetes environment variables to handle Proxy Mode configuration.

Method 1: Using keycloak.conf (Non-Containerized Setup)

In newer Keycloak versions, to enable Proxy Mode, you can modify the keycloak.conf configuration file. Here’s how to do it:

  1. Navigate to the Keycloak configuration directory:
  2. cd /opt/keycloak/conf
  3. Edit the keycloak.conf file:
  4. sudo nano keycloak.conf
  5. Add the following line to enable Proxy Mode:
  6. proxy.mode=edge
  7. Save the file and restart Keycloak:
  8. sudo systemctl restart keycloak

Method 2: Using Docker or Kubernetes Environment Variables

If you’re running Keycloak in a Docker or Kubernetes setup, Proxy Mode can be enabled via environment variables. Here’s an example of how to enable Proxy Mode in a Docker container:

docker run -e KEYCLOAK_PROXY_MODE=edge jboss/keycloak

For Kubernetes, the proxy mode can be configured by setting the environment variable in the Pod definition:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: keycloak
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: keycloak
        image: jboss/keycloak
        env:
        - name: KEYCLOAK_PROXY_MODE
          value: "edge"

3. Proxy Mode Configuration Options

Keycloak offers several proxy modes, each suitable for different reverse proxy setups:

  • off: No proxy is in use. Keycloak assumes it is directly accessed by clients without any proxy in between.
  • edge: The reverse proxy is located at the edge of the network, directly connected to clients. This is a common setup for environments where Keycloak is exposed to the internet.
  • reencrypt: The reverse proxy decrypts HTTPS traffic and forwards it to Keycloak over HTTP. This is typically used when a proxy terminates SSL/TLS connections.
  • passthrough: The reverse proxy forwards traffic without decrypting it. This setup is used when SSL/TLS termination is handled outside of the reverse proxy, often at a hardware load balancer.

4. Troubleshooting

If you encounter issues with Proxy Mode in Keycloak, consider the following:

  • Ensure that your reverse proxy is correctly forwarding headers like X-Forwarded-For and X-Forwarded-Proto to Keycloak.
  • Check Keycloak logs for any proxy-related errors, especially related to HTTPS or header forwarding.
  • Ensure your reverse proxy configuration is compatible with the Keycloak version you’re using.

5. Conclusion

Configuring Proxy Mode in Keycloak is essential for ensuring that Keycloak functions correctly in environments where it’s behind a reverse proxy. The configuration method has changed slightly between older and newer versions, with older versions relying on the standalone.xml file and newer versions using the keycloak.conf file or environment variables. By following the appropriate method for your Keycloak version, you can enable and configure Proxy Mode to work seamlessly in your infrastructure.