Document how Admin REST API endpoints work with Hostname config

Closes keycloak#30537

Signed-off-by: Václav Muzikář <[email protected]>
Co-authored-by: Martin Bartoš <[email protected]>
(cherry picked from commit bce7a29)

docs/guides/server/configuration-production.adoc

@@ -23,6 +23,14 @@ In a production environment, {project_name} instances usually run in a private n
 
 For details on the endpoint categories and instructions on how to configure the public hostname for them, see <@links.server id="hostname"/>.
 
+=== Exposing the {project_name} Administration APIs and UI on a different hostname
+
+It is considered a best practice to expose the {project_name} Administration REST API and Console on a different hostname or context-path than the one used for the public frontend URLs that are used e.g. by login flows. This separation ensures that the Administration interfaces are not exposed to the public internet, which reduces the attack surface.
+
+WARNING: Access to REST APIs needs to be blocked on the reverse proxy level, if they are not intended to be publicly exposed.
+
+For details, see <@links.server id="hostname"/>.
+
 == Reverse proxy in a distributed environment
 Apart from <@links.server id="hostname"/>, production environments usually include a reverse proxy / load balancer component. It separates and unifies access to the network used by your company or organization. For a {project_name} production environment, this component is recommended.
 
@@ -64,4 +72,4 @@ For example, to change the IP stack preference to IPv4, set an environment varia
 export JAVA_OPTS_APPEND="-Djava.net.preferIPv4Stack=true"
 ----
 
-</@tmpl.guide>
+</@tmpl.guide>

docs/guides/server/hostname.adoc

@@ -73,6 +73,8 @@ This allows you to access {project_name} at `https://my.keycloak.org` and the Ad
 
 NOTE: Keep in mind that hostname and proxy options do not change the ports on which the server listens. Instead it changes only the ports of static resources like JavaScript and CSS links, OIDC well-known endpoints, redirect URIs, etc. that will be used in front of the proxy. You need to use HTTP configuration options to change the actual ports the server is listening on. Refer to the <@links.server id="all-config"/> for details.
 
+WARNING: Using the `hostname-admin` option does not prevent accessing the Administration REST API endpoints via the frontend URL specified by the `hostname` option. If you want to restrict access to the Administration REST API, you need to do it on the reverse proxy level. Administration Console implicitly accesses the API using the URL as specified by the `hostname-admin` option.
+
 == Background - server endpoints
 
 {project_name} exposes several endpoints, each with a different purpose. They are typically used for communication among applications or for managing the server. We recognize 3 main endpoint groups:
@@ -110,7 +112,7 @@ Note that `hostname` option must be set to a URL. For more information, refer to
 
 === Administration
 
-Similarly to the base frontend URL, you can also set the base URL for resources and endpoints of the administration console. The server exposes the administration console and static resources using a specific URL. This URL is used for redirect URLs, loading resources (CSS, JS), etc. It can be done by setting the `hostname-admin` option:
+Similarly to the base frontend URL, you can also set the base URL for resources and endpoints of the administration console. The server exposes the administration console and static resources using a specific URL. This URL is used for redirect URLs, loading resources (CSS, JS), Administration REST API etc. It can be done by setting the `hostname-admin` option:
 
 <@kc.start parameters="--hostname https://my.keycloak.org --hostname-admin https://admin.my.keycloak.org:8443"/>
 

docs/guides/server/reverseproxy.adoc

@@ -29,7 +29,7 @@ If this header is incorrectly configured, rogue clients can set this header and
 
 NOTE: When using the `xforwarded` setting, the `X-Forwarded-Port` takes precedence over any port included in the `X-Forwarded-Host`.
 
-== Proxy modes
+== Proxy modes (deprecated)
 NOTE: The support for setting proxy modes is deprecated and will be removed in a future {project_name} release. Consider configuring accepted reverse proxy headers instead as described in the chapter above. For migration instructions consult the https://www.keycloak.org/docs/latest/upgrading/index.html#deprecated-proxy-option[Upgrading Guide].
 
 For {project_name}, your choice of proxy modes depends on the TLS termination in your environment. The following proxy modes are available:
@@ -57,15 +57,11 @@ To select the proxy mode, enter this command:
 == Different context-path on reverse proxy
 
 {project_name} assumes it is exposed through the reverse proxy under the same context path as {project_name} is configured for. By default {project_name} is exposed through the root (`/`), which means it expects to be exposed through the reverse proxy on `/` as well.
-You can use `hostname-path` or `hostname-url` in these cases, for example using `--hostname-path=/auth` if {project_name} is exposed through the reverse proxy on `/auth`.
+You can use a full URL for the `hostname` option in these cases, for example using `--hostname=https://my.keycloak.org/auth` if {project_name} is exposed through the reverse proxy on `/auth`.
 
-Alternatively you can also change the context path of {project_name} itself to match the context path for the reverse proxy using the `http-relative-path` option, which will change the context-path of {project_name} itself to match the context path used by the reverse proxy.
-
-== Trust the proxy to set hostname
-
-By default, {project_name} needs to know under which hostname it will be called. If your reverse proxy is configured to check for the correct hostname, you can set {project_name} to accept any hostname.
+For more details on exposing {project_name} on different hostname or context-path incl. Administration REST API and Console, see <@links.server id="hostname"/>.
 
-<@kc.start parameters="--proxy-headers=forwarded|xforwarded --hostname-strict=false"/>
+Alternatively you can also change the context path of {project_name} itself to match the context path for the reverse proxy using the `http-relative-path` option, which will change the context-path of {project_name} itself to match the context path used by the reverse proxy.
 
 == Enable sticky sessions
 
@@ -103,16 +99,7 @@ to `false` in order to avoid attaching the node to cookies and just rely on the
 By default, the `spi-sticky-session-encoder-infinispan-should-attach-route` option value is `true` so that the node name is attached to
 cookies to indicate to the reverse proxy the node that subsequent requests should be sent to.
 
-=== Exposing the administration console
-
-By default, the administration console URLs are created solely based on the requests to resolve the proper scheme, host name, and port. For instance,
-if you are using the `edge` proxy mode and your proxy is misconfigured, backend requests from your TLS termination proxy are going to use plain HTTP and potentially cause the administration
-console from being accessible because URLs are going to be created using the `http` scheme and the proxy does not support plain HTTP.
-
-In order to proper expose the administration console, you should make sure that your proxy is setting the `X-Forwarded-*` headers herein mentioned in order
-to create URLs using the scheme, host name, and port, being exposed by your proxy.
-
-=== Exposed path recommendations
+== Exposed path recommendations
 When using a reverse proxy, {project_name} only requires certain paths need to be exposed.
 The following table shows the recommended paths to expose.
 
@@ -135,11 +122,6 @@ The following table shows the recommended paths to expose.
 |Yes (see note below)
 |Access to keycloak.js needed for "internal" clients, e.g. the account console
 
-|/welcome/
-| -
-|No
-|No need exists to expose the welcome page after initial installation.
-
 |/realms/
 |/realms/
 |Yes
@@ -173,7 +155,7 @@ As it's true that the `js` path is needed for internal clients like the account
 We assume you run {project_name} on the root path `/` on your reverse proxy/gateway's public API.
 If not, prefix the path with your desired one.
 
-=== Enabling client certificate lookup
+== Enabling client certificate lookup
 
 When the proxy is configured as a TLS termination proxy the client certificate information can be forwarded to the server through specific HTTP request headers and then used to authenticate
 clients. You are able to configure how the server is going to retrieve client certificate information depending on the proxy you are using.
@@ -226,7 +208,7 @@ to load additional certificates from headers `CERT_CHAIN_0` to `CERT_CHAIN_9` if
 | Enable trusting NGINX proxy certificate verification, instead of forwarding the certificate to {project_name} and verifying it in {project_name}.
 |===
 
-==== Configuring the NGINX provider
+=== Configuring the NGINX provider
 
 The NGINX SSL/TLS module does not expose the client certificate chain. {project_name}'s NGINX certificate lookup provider rebuilds it by using the {project_name} truststore.