keycloak-scim/docs/guides/server/hostname.adoc

<#import "/templates/guide.adoc" as tmpl>
<#import "/templates/kc.adoc" as kc>
<#import "/templates/links.adoc" as links>

<@tmpl.guide
title="Configuring the hostname"
summary="Learn how to configure the frontend and backchannel endpoints exposed by Keycloak."
includedOptions="hostname hostname-* proxy">

== Server Endpoints

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

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

<@kc.start parameters="--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`
* Use the standard HTTP ports (e.g.: `80` and `443`) if a `proxy` is set or use the port you set to the `hostname-port` 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:

<@kc.start parameters="--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.

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

<@kc.start parameters="--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 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.

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

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:

<@kc.start parameters="--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:

<@kc.start parameters="--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 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 <@links.server id="reverseproxy"/>.

== 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 <@links.server id="enabletls"/>.

=== 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:
<@kc.start parameters="--hostname=mykeycloak --proxy=edge"/>

=== Exposing the server without a proxy

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

.Keycloak configuration:
<@kc.start parameters="--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 <@links.server id="reverseproxy"/>.

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

.Keycloak configuration:
<@kc.start parameters="--hostname=mykeycloak --hostname-strict-backchannel=true"/>

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

.Keycloak configuration:
<@kc.start parameters="--hostname-url=https://mykeycloak:8989"/>

</@tmpl.guide>