How to enable SSL Load Balancer or Reverse Proxy in front of RH-SSO/Keycloak

Updated -

Red Hat Single Sign-On (RH-SSO) is not set up by default to handle SSL/HTTPS. It is highly recommended that you either enable SSL on the Red Hat Single Sign-On server itself or on a reverse proxy in front of the Red Hat Single Sign-On server.

For enabling SSL on the RH-SSO server itself, follow the documentation on Setting up HTTPS/SSL as under the Network Setup chapter.

For Setting Up with a Load Balancer or Reverse Proxy, the usual setup is to have a frontend proxy sitting on a public network that load balances and forwards requests to backend RH-SSO server instance(s) located in a private network.
Several things need to be considered, such as identifying the clients IP addresses that are forwarded to and processed by the RH-SSO server instance(s).

This is a general set of steps:

  1. Configure your reverse proxy or loadbalancer to:
    1. Properly set X-Forwarded-For and X-Forwarded-Proto HTTP headers.
    2. Preserve the original Host HTTP header (on Apache HTTPD this is done with directive ProxyPreserveHost On).

  2. Configure RH-SSO:

    1. Configure the authentication server to read the client’s IP address from X-Forwarded-For header

      • For http proxy forwarding, set proxy-address-forwarding="true" in the http-listener or https-listener element as under the undertow subsystem configuration.

      To set using jboss-cli.sh, the command for https is:

      /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=proxy-address-forwarding, value=true)

      For http is:

      /subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=proxy-address-forwarding, value=true)

      • If you're using the AJP protocol for Apache HTTPD + mod-cluster, then you have to add a specific filter for it in the undertow config (See documentation below).
    2. If the listening port of the reverse proxy doesn't match the port of the RH-SSO server (8443 for https, or 8080 for http by default):
      • Configure a redirect-socket for specifying to what port the HTTP/HTTPS traffic is going to be redirected. It must have a unique name, for example: proxy-https.
      • Add a new socket-binding element to the socket-binding-group element using the unique name it last step, proxy-https.

  3. Verify Configuration

    1. Go to http[s]://{reverse-proxy}/auth/realms/master/.well-known/openid-configuration. For example if the reverse proxy address is https://acme.com/ then open the URL https://acme.com/auth/realms/master/.well-known/openid-configuration.
      • This returns a JSON document listing the end points for RH-SSO. Make sure the endpoints starts with the address (scheme, domain and port) of your reverse proxy or load balancer.
      • If the these values are incorrect, forwarding the original Host header and X-Forwarded-Proto headers may be incorrect.

    2. Verify RH-SSO sees the correct source IP address. Go to the admin console, then attempt to login with an invalid username, and you'll see a warning in server.log like:

      [org.keycloak.events] type=LOGIN_ERROR, realmId=master, clientId=security-admin-console, userId=8f20d7ba-4974-4811-a695-242c8fbd1bf8, ipAddress=X.X.X.X,...
      • The ipAddress=X.X.X.X part should be the address of the machine attempting the login.
      • If the address is incorrect, the X-Forwarder-For or proxy-address-forwarding="true" setting in undertow is not correct..

Note To help with verification, you can configure RH-SSO to dump the paired http requests and responses. See Configure Request logging / RequestDumping handler in JBoss EAP 7

For a detailed explanation of each step, see Setting Up a Load Balancer or Proxy.

Comments