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.

Posted on

How to Change the Port in Keycloak: Old vs. New Versions

Keycloak typically runs on port 8080 by default, which might conflict with other services or might need to be changed for specific use cases. Changing the port can be done in both old and new versions of Keycloak, though the methods may differ slightly depending on how Keycloak is installed (standalone server vs. containerized). This article provides step-by-step instructions for changing the port in both older and newer Keycloak versions.

1. Changing the Port in Older Keycloak Versions (Pre-2020)

In older versions of Keycloak (pre-2020), the configuration of Keycloak’s HTTP and HTTPS ports is done via the standalone.xml file. This file is located in the standalone/configuration directory of your Keycloak installation.

Follow these steps to change the port in older versions:

  1. Locate the standalone.xml configuration file. Typically, it is located at: /opt/keycloak/standalone/configuration/standalone.xml
  2. Open the standalone.xml file using a text editor, such as nano:
  3. sudo nano /opt/keycloak/standalone/configuration/standalone.xml
  4. Find the section that defines the HTTP listener. This section looks like this:
  5. <http-listener name=”default” socket-binding=”http”/>
  6. Change the port by updating the <socket-binding> tag:
  7. <socket-binding name=”http” port=”9090″/>
  8. If you’re also changing the HTTPS port, locate the <https-listener> and modify it:
  9. <https-listener name=”https” socket-binding=”https”/>
  10. <socket-binding name=”https” port=”8443″/>
  11. Save the changes and restart Keycloak:
  12. sudo systemctl restart keycloak

2. Changing the Port in Newer Keycloak Versions (Post-2020)

With the newer versions of Keycloak, particularly from 2020 onwards, the configuration method has shifted. The standalone.xml file is no longer the primary configuration method. Instead, Keycloak uses environment variables and the keycloak.conf file (for standalone installations) or environment variables for containerized deployments (e.g., Docker and Kubernetes).

For new Keycloak versions, follow these steps to change the port:

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

  1. Navigate to the keycloak.conf file located in your Keycloak directory:
  2. cd /opt/keycloak/conf
  3. Edit the keycloak.conf file to include the desired HTTP and HTTPS ports. For example:
  4. http.port=9090
  5. https.port=8443
  6. Save the file and restart Keycloak to apply the changes:
  7. sudo systemctl restart keycloak

Method 2: Using Docker or Kubernetes Environment Variables

If you’re running Keycloak in a Docker container or Kubernetes pod, you can set the port by defining environment variables. Here’s how you can do it:

docker run -e KEYCLOAK_HTTP_PORT=9090 -e KEYCLOAK_HTTPS_PORT=8443 jboss/keycloak

In Kubernetes, you would set the ports in the Pod definition using environment variables or ConfigMaps. Here’s an example for setting it in a Kubernetes configuration:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: keycloak
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: keycloak
        image: jboss/keycloak
        env:
        - name: KEYCLOAK_HTTP_PORT
          value: "9090"
        - name: KEYCLOAK_HTTPS_PORT
          value: "8443"

3. Troubleshooting

If you encounter issues after changing the port, consider the following:

  • Ensure the new ports are not already in use by other services.
  • Check for firewall or security settings that might be blocking the new port.
  • Verify that Keycloak has restarted properly after the changes.

4. Conclusion

Changing the port in Keycloak varies depending on the version and installation method you’re using. In older versions, you would modify the standalone.xml file, while newer versions rely on environment variables or the keycloak.conf file. By following the appropriate method for your version, you can successfully change the port and avoid any conflicts with other services.