reverse proxy Archives - Page 3 of 5 - Innovations in IT, Leadership, and Digital Strategy

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:

Navigate to the Keycloak configuration directory:
cd /opt/keycloak/standalone/configuration
Open the standalone.xml file in a text editor:
sudo nano standalone.xml
Locate the <http-listener> section for the HTTP and HTTPS listeners.
Find the section that configures proxy-related settings:
<proxy-mode>…
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.
<proxy-mode>edge</proxy-mode>
Save the changes and restart Keycloak:
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:

Navigate to the Keycloak configuration directory:
cd /opt/keycloak/conf
Edit the keycloak.conf file:
sudo nano keycloak.conf
Add the following line to enable Proxy Mode:
proxy.mode=edge
Save the file and restart Keycloak:
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.

Running Keycloak behind an NGINX reverse proxy is a common practice to enhance security, improve load balancing, and simplify routing. This setup keeps the Keycloak server behind a proxy, handling external HTTP/S traffic and forwarding requests to Keycloak.

1. Why Use a Reverse Proxy with Keycloak?

Using NGINX as a reverse proxy for Keycloak offers several benefits:

Security: Hides the actual Keycloak server from external exposure.
SSL Termination: NGINX can handle SSL encryption, improving performance and security.
Load Balancing: Allows multiple Keycloak instances for scalability.
Routing: Can route traffic based on domains or other factors.

2. Prerequisites

Keycloak: Keycloak should already be installed and running on a server (e.g., on port 8080).
NGINX: NGINX installed on a server that will act as the reverse proxy.
SSL Certificate: Optional, but recommended for securing the connection (e.g., using Let’s Encrypt).

3. Configuring NGINX as a Reverse Proxy

Step 1: Update the NGINX Configuration

Edit the NGINX configuration file to add a reverse proxy for Keycloak. You can use the default configuration file or create a new one under /etc/nginx/sites-available/.

sudo nano /etc/nginx/sites-available/keycloak

Add the following configuration to proxy requests to your Keycloak server:

server {
    listen 80;
    server_name keycloak.example.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_redirect off;
    }
}

This configuration ensures that all traffic to keycloak.example.com is forwarded to the Keycloak server running on localhost:8080.

Step 2: Enable SSL (Optional but Recommended)

If you want to secure the connection with SSL, modify the server block to use HTTPS:

server {
    listen 443 ssl;
    server_name keycloak.example.com;

    ssl_certificate /etc/ssl/certs/your_certificate.crt;
    ssl_certificate_key /etc/ssl/private/your_certificate.key;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_redirect off;
    }
}

If you are using Let’s Encrypt, you can automate SSL certificate management using Certbot.

Step 3: Enable and Test the Configuration

After making changes, test the NGINX configuration for syntax errors:

sudo nginx -t

If there are no errors, reload NGINX to apply the changes:

sudo systemctl reload nginx

4. Configuring Keycloak for Proxy Mode

In Keycloak, you need to configure it to run behind a proxy to ensure correct URL handling. Edit the Keycloak configuration file standalone.xml (or standalone-ha.xml) located in the keycloak/standalone/configuration directory:

Can’t find standalone.xml

Configuring Proxy Mode in Keycloak: Old vs. New Versions

sudo nano /opt/keycloak/standalone/configuration/standalone.xml

Find the http configuration and add the following lines to enable proxy mode:

<http-listener name="default" socket-binding="http" proxy-address-forwarding="true"/>

This configuration tells Keycloak to respect the proxy headers sent by NGINX.

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

5. Restart Keycloak

After configuring Keycloak for proxy mode, restart Keycloak:

sudo systemctl restart keycloak

6. Verify the Setup

Now, visit https://keycloak.example.com in your browser. You should be able to access the Keycloak admin console and login page via the reverse proxy. Make sure that all features are working as expected and that the URL is correctly rewritten.

7. Troubleshooting

If the setup doesn’t work as expected, check the following:

Ensure that the NGINX server can reach the Keycloak instance on the specified port (8080).
Make sure the proxy headers are correctly passed to Keycloak.
Check Keycloak’s logs for any errors related to proxy settings.
Verify the SSL certificate if you’re using HTTPS.
Key material not provided to setup HTTPS

8. Conclusion

Running Keycloak behind an NGINX reverse proxy is a powerful way to improve the security and scalability of your identity management solution. By following these steps, you can set up Keycloak with SSL support and load balancing, while ensuring it’s securely accessible through a single endpoint.