Search

Chapter 5. Configuring the hostname

download PDF

5.1. Server Endpoints

Red Hat build of Keycloak exposes different endpoints to talk with applications as well as to allow accessing the administration console. These endpoints can be categorized into three main groups:

  • Frontend
  • Backend
  • Administration Console

The base URL for each group has an important impact on how tokens are issued and validated, on how links are created for actions that require the user to be redirected to Red Hat build of Keycloak (for example, when resetting password through email links), and, most importantly, how applications will discover these endpoints when fetching the OpenID Connect Discovery Document from realms/{realm-name}/.well-known/openid-configuration.

5.1.1. Frontend

The frontend endpoints are those accessible through a public domain and usually related to authentication/authorization flows that happen through the front-channel. For instance, when an SPA wants to authenticate their users it redirects them to the authorization_endpoint so that users can authenticate using their browsers through the front-channel.

By default, when the hostname settings are not set, the base URL for these endpoints is based on the incoming request so that the HTTP scheme, host, port, and path, are the same from the request. The default behavior also has a direct impact on how the server is going to issue tokens given that the issuer is also based on the URL set to the frontend endpoints. If the hostname settings are not set, the token issuer will also be based on the incoming request and also lack consistency if the client is requesting tokens using different URLs.

When deploying to production you usually want a consistent URL for the frontend endpoints and the token issuer regardless of how the request is constructed. In order to achieve this consistency, you can set either the hostname or the hostname-url options.

Most of the time, it should be enough to set the hostname option in order to change only the host of the frontend URLs:

bin/kc.[sh|bat] start --hostname=<host>

When using the hostname option the server is going to resolve the HTTP scheme, port, and path, automatically so that:

  • https scheme is used unless you set hostname-strict-https=false
  • if the proxy-headers option is set, the proxy will use the default ports (i.e.: 80 and 443). If the proxy uses a different port, it needs to be specified via the hostname-url configuration option

However, if you want to set not only the host but also a scheme, port, and path, you can set the hostname-url option:

bin/kc.[sh|bat] start --hostname-url=<scheme>://<host>:<port>/<path>

This option gives you more flexibility as you can set the different parts of the URL from a single option. Note that the hostname and hostname-url are mutually exclusive.

Note

By hostname and proxy-headers configuration options you affect only the static resources URLs, redirect URIs, OIDC well-known endpoints, etc. In order to change, where/on which port the server actually listens on, you need to use the http/tls configuration options (e.g. http-host, https-port, etc.). For more details, see Configuring TLS and All configuration.

5.1.2. Backend

The backend endpoints are those accessible through a public domain or through a private network. They are used for a direct communication between the server and clients without any intermediary but plain HTTP requests. For instance, after the user is authenticated an SPA wants to exchange the code sent by the server with a set of tokens by sending a token request to token_endpoint.

By default, the URLs for backend endpoints are also based on the incoming request. To override this behavior, set the hostname-strict-backchannel configuration option by entering this command:

bin/kc.[sh|bat] start --hostname=<value> --hostname-strict-backchannel=true

By setting the hostname-strict-backchannel option, the URLs for the backend endpoints are going to be exactly the same as the frontend endpoints.

When all applications connected to Red Hat build of Keycloak communicate through the public URL, set hostname-strict-backchannel to true. Otherwise, leave this parameter as false to allow client-server communication through a private network.

5.1.3. Administration Console

The server exposes the administration console and static resources using a specific URL.

By default, the URLs for the administration console are also based on the incoming request. However, you can set a specific host or base URL if you want to restrict access to the administration console using a specific URL. Similarly to how you set the frontend URLs, you can use the hostname-admin and hostname-admin-url options to achieve that. Note that if HTTPS is enabled (http-enabled configuration option is set to false, which is the default setting for the production mode), the Red Hat build of Keycloak server automatically assumes you want to use HTTPS URLs. The admin console then tries to contact Red Hat build of Keycloak over HTTPS and HTTPS URLs are also used for its configured redirect/web origin URLs. It is not recommended for production, but you can use HTTP URL as hostname-admin-url to override this behaviour.

Most of the time, it should be enough to set the hostname-admin option in order to change only the host of the administration console URLs:

bin/kc.[sh|bat] start --hostname-admin=<host>

However, if you want to set not only the host but also a scheme, port, and path, you can set the hostname-admin-url option:

bin/kc.[sh|bat] start --hostname-admin-url=<scheme>://<host>:<port>/<path>

Note that the hostname-admin and hostname-admin-url are mutually exclusive.

To reduce attack surface, the administration endpoints for Red Hat build of Keycloak and the Admin Console should not be publicly accessible. Therefore, you can secure them by using a reverse proxy. For more information about which paths to expose using a reverse proxy, see Using a reverse proxy.

5.2. Example Scenarios

The following are more example scenarios and the corresponding commands for setting up a hostname.

Note that the start command requires setting up TLS. The corresponding options are not shown for example purposes. For more details, see Configuring TLS.

5.2.1. Exposing the server behind a TLS termination proxy

In this example, the server is running behind a TLS termination proxy and publicly available from https://mykeycloak.

Configuration:

bin/kc.[sh|bat] start --hostname=mykeycloak --http-enabled=true --proxy-headers=forwarded|xforwarded

5.2.2. Exposing the server without a proxy

In this example, the server is running without a proxy and exposed using a URL using HTTPS.

Red Hat build of Keycloak configuration:

bin/kc.[sh|bat] start --hostname-url=https://mykeycloak

It is highly recommended using a TLS termination proxy in front of the server for security and availability reasons. For more details, see Using a reverse proxy.

5.2.3. Forcing backend endpoints to use the same URL the server is exposed

In this example, backend endpoints are exposed using the same URL used by the server so that clients always fetch the same URL regardless of the origin of the request.

Red Hat build of Keycloak configuration:

bin/kc.[sh|bat] start --hostname=mykeycloak --hostname-strict-backchannel=true

5.2.4. Exposing the server using a port other than the default ports

In this example, the server is accessible using a port other than the default ports.

Red Hat build of Keycloak configuration:

bin/kc.[sh|bat] start --hostname-url=https://mykeycloak:8989

5.2.5. Exposing Red Hat build of Keycloak behind a TLS reencrypt proxy using different ports

In this example, the server is running behind a proxy and both the server and the proxy are using their own certificates, so the communication between Red Hat build of Keycloak and the proxy is encrypted. The reverse proxy uses the Forwarded header and does not set the X-Forwarded-* headers. We need to keep in mind that the proxy configuration options (as well as hostname configuration options) are not changing the ports on which the server actually is listening on (it changes only the ports of static resources like JavaScript and CSS links, OIDC well-known endpoints, redirect URIs, etc.). Therefore, we need to use HTTP configuration options to change the Red Hat build of Keycloak server to internally listen on a different port, e.g. 8543. The proxy will be listening on the port 8443 (the port visible while accessing the console via a browser). The example hostname my-keycloak.org will be used for the server and similarly the admin console will be accessible via the admin.my-keycloak.org subdomain.

Red Hat build of Keycloak configuration:

bin/kc.[sh|bat] start --proxy-headers=forwarded --https-port=8543 --hostname-url=https://my-keycloak.org:8443 --hostname-admin-url=https://admin.my-keycloak.org:8443

Warning

Usage of the proxy-headers option rely on Forwarded and X-Forwarded-* headers, respectively, that have to be set and overwritten by the reverse proxy. Misconfiguration may leave Red Hat build of Keycloak exposed to security issues. For more details, see Using a reverse proxy.

5.3. Troubleshooting

To troubleshoot the hostname configuration, you can use a dedicated debug tool which can be enabled as:

Red Hat build of Keycloak configuration:

bin/kc.[sh|bat] start --hostname=mykeycloak --hostname-debug=true

Then after Red Hat build of Keycloak started properly, open your browser and go to:

http://mykeycloak:8080/realms/<your-realm>/hostname-debug

5.4. Relevant options

Table 5.1. By default, this endpoint is disabled (--hostname-debug=false)
 Value

hostname

Hostname for the Keycloak server.

CLI: --hostname
Env: KC_HOSTNAME

 

hostname-admin

The hostname for accessing the administration console.

Use this option if you are exposing the administration console using a hostname other than the value set to the hostname option.

CLI: --hostname-admin
Env: KC_HOSTNAME_ADMIN

 

hostname-admin-url

Set the base URL for accessing the administration console, including scheme, host, port and path

CLI: --hostname-admin-url
Env: KC_HOSTNAME_ADMIN_URL

 

hostname-debug

Toggle the hostname debug page that is accessible at /realms/master/hostname-debug

CLI: --hostname-debug
Env: KC_HOSTNAME_DEBUG

true, false (default)

hostname-path

This should be set if proxy uses a different context-path for Keycloak.

CLI: --hostname-path
Env: KC_HOSTNAME_PATH

 

hostname-port

The port used by the proxy when exposing the hostname.

Set this option if the proxy uses a port other than the default HTTP and HTTPS ports.

CLI: --hostname-port
Env: KC_HOSTNAME_PORT

-1 (default)

hostname-strict

Disables dynamically resolving the hostname from request headers.

Should always be set to true in production, unless proxy verifies the Host header.

CLI: --hostname-strict
Env: KC_HOSTNAME_STRICT

true (default), false

hostname-strict-backchannel

By default backchannel URLs are dynamically resolved from request headers to allow internal and external applications.

If all applications use the public URL this option should be enabled.

CLI: --hostname-strict-backchannel
Env: KC_HOSTNAME_STRICT_BACKCHANNEL

true, false (default)

hostname-url

Set the base URL for frontend URLs, including scheme, host, port and path.

CLI: --hostname-url
Env: KC_HOSTNAME_URL

 

proxy

The proxy address forwarding mode if the server is behind a reverse proxy.

CLI: --proxy
Env: KC_PROXY

DEPRECATED. Use: proxy-headers.

none (default), edge, reencrypt, passthrough

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.