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:
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.
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.