Configuring the hostname

Learn how to configure the frontend and backchannel endpoints exposed by Keycloak.

When running Keycloak in environments such as Kubernetes, OpenShift, or on-premise, you want to protect the internal URLs from exposure to the public facing internet. Instead, You want to expose your public hostname. This guide describes how to configure Keycloak to use the right hostname for different scenarios.

Hostname Syntax:

Keycloak does not impose strict validation for the configured hostname value. Please make sure the hostname value you configure complies to the standardized hostname syntax as outlined in RFC 952, RFC 1123 and others.

Example:

LOCALHOST is a non-compliant hostname and leads to problems when the browser tries to resolve your requests. Instead, localhost will work fine.

Keycloak API Endpoint categories

As this section explains, Keycloak exposes three API endpoint categories: frontend, backend, and administrative. Each category uses a specific base URL.

Frontend Endpoints

Frontend endpoints are used to externally access Keycloak. When no hostname is set, the base URL used for the frontend is taken from the incoming request. This choice has some major disadvantages. For example, in a high availability scenario, you may have multiple Keycloak instances. The choice of URL should not depend on the instance where the request lands. The URL should be used for all instances, so they are seen as one system from the outside.

To set the hostname part of the frontend base URL, enter this command:

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

You can also set a different port if your proxy is exposing the frontend URL using a port other than the default HTTP (80) and HTTPS(443) ports. For that, set the hostname-port option.

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

Backend Endpoints

Backend endpoints are used for direct communication between Keycloak and applications. Examples of backend endpoints are the Token endpoint and the User info endpoint. Backend endpoints are also taking the base URL from the request by default. 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

When all applications connected to Keycloak communicate through the public URL, set hostname-strict-backchannel to true. Otherwise, leave this parameter as false to allow internal applications to communicate with Keycloak through an internal URL.

Administrative Endpoints

To reduce attack surface, the administration endpoints for 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 the Using a reverse proxy Guide.

Exposing the administration console using a different hostname

The administration console can be exposed using a hostname other than what you set to the frontend URLs via the hostname option. For that, you can set the hostname-admin option as follows:

bin/kc.[sh|bat] start --hostname=myurl --hostname-admin=myadminurl

When the hostname-admin option is set the URLs used by the administration console will have that hostname hardcoded in them. Otherwise, the URLs used by the administration console are going to be based on the hostname from the request.

If you don’t set this option and the administration console is accessed using a hostname other than what is set to the frontend URLs, you might get an error from the server telling you that the redirect URI used by the console is invalid. In this case, you should update the security-admin-console client to add a valid redirect URI based on the hostname you want the administration console to be accessible.

Overriding the hostname path

When running Keycloak behind a reverse proxy, you may expose Keycloak using a different context path such as myproxy.url/mykeycloak. To perform this action, you can override the hostname path to use the path defined in your reverse proxyas shown in this example:

bin/kc.[sh|bat] start --hostname=myurl --hostname-path=mykeycloak

The hostname-path configuration takes effect when a reverse proxy is enabled. For details, see the Using a reverse proxy Guide.

Accessing Keycloak in production mode using HTTP

When a hostname is set and the server is running in production mode, all the URLs generated by the server are going to use the HTTPS scheme. If you are not setting up TLS you might run into issues because some URLs generated by the server won’t work.

Keycloak follows the "secure by design" principle, so it is absolutely not recommended to access Keycloak without proper transport encryption, as this opens up multiple attack vectors.

Nevertheless there are environments, where Keycloak is deployed behind a proxy/load balancer that terminates TLS completely and the internal requests are done using the unencrypted HTTP protocol.

To be able to work with Keycloak using HTTP for these environments, there is the hidden configuration option hostname-strict-https=<true/false>. This option is set to true by default for the production mode, and false for the development mode.

When you need to access Keycloak using HTTP in production mode, for example when you use proxy=edge and you want to access the administration console internally using HTTP, you have to set hostname-strict-https=false, otherwise a blank page will show up.

Keep in mind the recommended approach is to always use HTTPS, and this still is true for external clients.

Using the hostname in development mode

You run Keycloak in development mode by using start-dev. In this mode, the hostname setting is optional. When it is omitted, the incoming request headers are used.

Example: Hostname in development mode

Keycloak configuration:
bin/kc.[sh|bat] start-dev
Invoked command:
curl GET "https://localhost:8080/realms/master/.well-known/openid-configuration" | jq .
Result:
# Frontend endpoints: request://request:request -> http://localhost:8080
# Backend endpoints: request://request:request -> http://localhost:8080

In this example of using a curl GET request, the result shows the current OpenID Discovery configuration. All base URLS are taken from the incoming request, so http://localhost:8080 is used for all endpoints.

Example Scenarios

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

Assumptions for all scenarios

  • Keycloak is set up using HTTPS certificates and Port 8443.

  • intlUrl refers to an internal IP/DNS for Keycloak.

  • myUrl refers to an exposed public URL

  • Keycloak runs in production mode using the start command.

Example 1: Hostname configuration without reverse proxy

Keycloak configuration:
bin/kc.[sh|bat] start --hostname=myurl
Invoked command:
curl GET "https://intUrl:8443/realms/master/.well-known/openid-configuration" | jq .
Result:
# Frontend Endpoints: request://myurl:request -> https://myurl:8443
# Backend Endpoints: request://request:request -> https://internal:8443

Example 2: Hostname configuration without reverse proxy - strict backchannel enabled

Keycloak configuration:
bin/kc.[sh|bat] start --hostname=myurl --hostname-strict-backchannel=true
Invoked command:
curl GET "https://intUrl:8443/realms/master/.well-known/openid-configuration" | jq .
Result:
# Frontend: request://myurl:request -> https://myurl:8443
# Backend: request://myurl:request -> https://myurl:8443

Example 3: Hostname configuration with reverse proxy

Keycloak configuration:
bin/kc.[sh|bat] start --hostname=myurl --proxy=passthrough
Invoked command:
curl GET "https://intUrl:8443/realms/master/.well-known/openid-configuration" | jq .
Result:
# Frontend Endpoints: request://myurl ->  https://myurl
# Backend Endpoints: request://request:request -> https://internal:8443

Hostname configuration with reverse proxy and different path

Keycloak configuration:
bin/kc.[sh|bat] start --hostname=myurl --proxy=passthrough --hostname-path=mykeycloak
Invoked command:
curl GET "https://intUrl:8443/realms/master/.well-known/openid-configuration" | jq .
Result:
# Frontend Endpoints: request://myurl ->  https://myurl/mykeycloak
# Backend Endpoints: request://request:request -> https://internal:8443

Relevant options

Type Default

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

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, false

true

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

false

proxy

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

Possible values are: edge,reencrypt,passthrough

CLI: --proxy

Env: KC_PROXY

edge, reencrypt, passthrough

none

On this page