From 48519be52b3fbf52c6dcb5d9074429ab4ae7dc8c Mon Sep 17 00:00:00 2001 From: andymunro <48995441+andymunro@users.noreply.github.com> Date: Mon, 27 Feb 2023 08:57:43 -0500 Subject: [PATCH] Eliminate guide from cross-references (#17065) Closes #17055 --- docs/guides/src/main/server/caching.adoc | 2 +- .../src/main/server/configuration-metrics.adoc | 2 +- .../src/main/server/configuration-production.adoc | 10 +++++----- docs/guides/src/main/server/configuration.adoc | 13 ++++++++----- docs/guides/src/main/server/containers.adoc | 2 +- docs/guides/src/main/server/enabletls.adoc | 2 +- docs/guides/src/main/server/hostname.adoc | 7 +++---- docs/guides/src/main/server/logging.adoc | 4 ++-- docs/guides/src/main/server/outgoinghttp.adoc | 2 +- docs/guides/src/main/server/reverseproxy.adoc | 2 +- 10 files changed, 24 insertions(+), 22 deletions(-) diff --git a/docs/guides/src/main/server/caching.adoc b/docs/guides/src/main/server/caching.adoc index ff665196fe..80aa9d6864 100644 --- a/docs/guides/src/main/server/caching.adoc +++ b/docs/guides/src/main/server/caching.adoc @@ -230,7 +230,7 @@ The current Infinispan cache implementation should be secured by various securit == Exposing metrics from caches By default, metrics from caches are not automatically exposed when the metrics are enabled. -For more details about how to enable metrics, see the <@links.server id="configuration-metrics"/> guide. +For more details about how to enable metrics, see <@links.server id="configuration-metrics"/>. To enable global metrics for all caches within the `cache-container`, you need to change your cache configuration file (e.g.: `conf/cache-ispn.xml`) to enable `statistics` at the `cache-container` level as follows: diff --git a/docs/guides/src/main/server/configuration-metrics.adoc b/docs/guides/src/main/server/configuration-metrics.adoc index a459176603..6ec7b261f5 100644 --- a/docs/guides/src/main/server/configuration-metrics.adoc +++ b/docs/guides/src/main/server/configuration-metrics.adoc @@ -72,7 +72,7 @@ The table below summarizes the available metrics groups: |A set of global and individual metrics from the HTTP endpoints |Cache -|A set of metrics from Infinispan caches. See <@links.server id="caching"/> guide for more details. +|A set of metrics from Infinispan caches. See <@links.server id="caching"/> for more details. |=== diff --git a/docs/guides/src/main/server/configuration-production.adoc b/docs/guides/src/main/server/configuration-production.adoc index 5f2f1725c4..37c414c8d1 100644 --- a/docs/guides/src/main/server/configuration-production.adoc +++ b/docs/guides/src/main/server/configuration-production.adoc @@ -14,27 +14,27 @@ This guide describes the general areas of configuration required for a productio == TLS for secure communication Keycloak continually exchanges sensitive data, which means that all communication to and from Keycloak requires a secure communication channel. To prevent several attack vectors, you enable HTTP over TLS, or HTTPS, for that channel. -To configure secure communication channels for Keycloak, see the <@links.server id="enabletls"/> and <@links.server id="outgoinghttp"/> guides. +To configure secure communication channels for Keycloak, see <@links.server id="enabletls"/> and <@links.server id="outgoinghttp"/>. == The hostname for Keycloak In a production environment, Keycloak instances usually run in a private network, but Keycloak needs to expose certain public facing endpoints to communicate with the applications to be secured. -For details on the endpoint categories and instructions on how to configure the public hostname for them, see the <@links.server id="hostname"/> guide. +For details on the endpoint categories and instructions on how to configure the public hostname for them, 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 Keycloak production environment, this component is recommended. -For details on configuring proxy communication modes in Keycloak, see the <@links.server id="reverseproxy"/> guide. That guide also recommends which paths should be hidden from public access and which paths should be exposed so that Keycloak can secure your applications. +For details on configuring proxy communication modes in Keycloak, see <@links.server id="reverseproxy"/>. That guide also recommends which paths should be hidden from public access and which paths should be exposed so that Keycloak can secure your applications. == Production grade database -The database used by Keycloak is crucial for the overall performance, availability, reliability and integrity of Keycloak. For details on how to configure a supported database, see the <@links.server id="db"/> guide. +The database used by Keycloak is crucial for the overall performance, availability, reliability and integrity of Keycloak. For details on how to configure a supported database, see <@links.server id="db"/>. == Support for Keycloak in a cluster To ensure that users can continue to log in when a Keycloak instance goes down, a typical production environment contains two or more Keycloak instances. Keycloak runs on top of JGroups and Infinispan, which provide a reliable, high-availability stack for a clustered scenario. When deployed to a cluster, the embedded Infinispan server communication should be secured. You secure this communication either by enabling authentication and encryption or by isolating the network used for cluster communication. -To find out more about using multiple nodes, the different caches and an appropriate stack for your environment, see the <@links.server id="caching"/> guide. +To find out more about using multiple nodes, the different caches and an appropriate stack for your environment, see <@links.server id="caching"/>. == Configure Keycloak Server with IPv6 or IPv4 diff --git a/docs/guides/src/main/server/configuration.adoc b/docs/guides/src/main/server/configuration.adoc index e59217a060..149afa50dd 100644 --- a/docs/guides/src/main/server/configuration.adoc +++ b/docs/guides/src/main/server/configuration.adoc @@ -49,7 +49,10 @@ Values that go into the configuration file are following the `= You can easily translate a Key/Value pair from one configuration source to the other. -You will find the relevant configuration options for a specific guide in all three formats on the table at the bottom of each guide. You can find all available options at the <@links.server id="all-config"/> guide. +At the end of each configuration guide, look for the _Relevant +options_ heading for a table with the three relevant configuration +formats. For all configuration options, see <@links.server +id="all-config"/>. The configuration source and the corresponding format you should use is use-case specific. @@ -98,7 +101,7 @@ Keycloak is packed with a CLI that helps you to configure Keycloak. To find out <@kc.start parameters="--help"/> -Alternatively, you can find all server options at the <@links.server id="all-config"/> guide. +Alternatively, you can find all server options at <@links.server id="all-config"/>. === Using raw Quarkus properties In most cases, the available configuration options should suffice to configure the server. @@ -151,7 +154,7 @@ The production mode sets the following defaults: * Hostname configuration is expected * HTTPS/TLS configuration is expected -Make sure to follow the steps outlined in the <@links.server id="configuration-production"/> guide before deploying Keycloak to production environments. +Make sure to follow the steps outlined in <@links.server id="configuration-production"/> before deploying Keycloak to production environments. By default, example configuration options for the production mode are commented out in the default `conf/keycloak.conf` file. These give you an idea about the main configuration to consider when running Keycloak in production. @@ -181,7 +184,7 @@ As you may notice, the command above shows `build options` that should be invoke For a non-optimized startup of Keycloak, this distinction has no effect, but when a build is invoked beforehand, there's only a subset of Options available to the build command. The reason is, that build options get persisted into Keycloaks classpath, so configuration for e.g. credentials like `db-password` must not get persisted for security reasons. -Build options are marked in the <@links.server id="all-config"/> guide with a tool icon. +Build options are marked in <@links.server id="all-config"/> with a tool icon. Find available build options either by looking at the https://www.keycloak.org/server/all-config?f=build[All configuration page with build options selected] or by invoking the following command: <@kc.build parameters="--help"/> @@ -196,7 +199,7 @@ After a successful build, you can start Keycloak and turn off the default startu The `--optimized` parameter tells Keycloak to assume a pre-built, already optimized Keycloak image is used. As a result, Keycloak avoids checking for and running a build directly at startup to save the time to walk through this process. -You can invoke all configuration options at startup - these are all options in the <@links.server id="all-config"/> guide that are **not** marked with a tool icon. +You can invoke all configuration options at startup; these options are the ones in <@links.server id="all-config"/> that are **not** marked with a tool icon. If a build option is found at startup with an equal value to the value used when invoking the `build`, it gets silently ignored when using the `--optimized` flag. If it has a different value than the value used when a build was invoked, a warning is shown in the logs and the previously built value is used. In order for this value to take effect, you have to run a new `build` before starting. diff --git a/docs/guides/src/main/server/containers.adoc b/docs/guides/src/main/server/containers.adoc index f45ecbedd1..1b23adc49e 100644 --- a/docs/guides/src/main/server/containers.adoc +++ b/docs/guides/src/main/server/containers.adoc @@ -119,7 +119,7 @@ podman|docker run --name mykeycloak -p 8080:8080 \ Invoking this command starts the Keycloak server in development mode. This mode should be strictly avoided in production environments because it has insecure defaults. -For more information about running Keycloak in production, take a look at the <@links.server id="configuration-production"/> guide. +For more information about running Keycloak in production, see <@links.server id="configuration-production"/>. == Running a standard keycloak container In keeping with concepts such as immutable infrastructure, containers need to be re-provisioned routinely. diff --git a/docs/guides/src/main/server/enabletls.adoc b/docs/guides/src/main/server/enabletls.adoc index 6b1bacae5d..3ebceed2c2 100644 --- a/docs/guides/src/main/server/enabletls.adoc +++ b/docs/guides/src/main/server/enabletls.adoc @@ -79,6 +79,6 @@ Authentication using mTLS is disabled by default. To enable mTLS certificate han Using the value `required` sets up Keycloak to always ask for certificates and fail if no certificate is provided in a request. By setting the value to `request`, Keycloak will also accept requests without a certificate and only validate the correctness of a certificate if it exists. -Be aware that this is the basic certificate configuration for mTLS use cases where Keycloak acts as server. When Keycloak acts as client instead, e.g. when Keycloak tries to get a token from a token endpoint of a brokered identity provider that is secured by mTLS, you need to set up the HttpClient to provide the right certificates in the keystore for the outgoing request. To configure mTLS in these scenarios, see the <@links.server id="outgoinghttp"/> guide. +Be aware that this is the basic certificate configuration for mTLS use cases where Keycloak acts as server. When Keycloak acts as client instead, e.g. when Keycloak tries to get a token from a token endpoint of a brokered identity provider that is secured by mTLS, you need to set up the HttpClient to provide the right certificates in the keystore for the outgoing request. To configure mTLS in these scenarios, see <@links.server id="outgoinghttp"/>. diff --git a/docs/guides/src/main/server/hostname.adoc b/docs/guides/src/main/server/hostname.adoc index b12976f812..9d823d12a6 100644 --- a/docs/guides/src/main/server/hostname.adoc +++ b/docs/guides/src/main/server/hostname.adoc @@ -83,13 +83,12 @@ 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 the <@links.server id="reverseproxy"/> Guide. +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"/> guide. +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 @@ -106,7 +105,7 @@ In this example, the server is running without a proxy and exposed using a URL u <@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 the <@links.server id="reverseproxy"/> guide. +see <@links.server id="reverseproxy"/>. === Forcing backend endpoints to use the same URL the server is exposed diff --git a/docs/guides/src/main/server/logging.adoc b/docs/guides/src/main/server/logging.adoc index 0bfc8f6172..1eb7606f89 100644 --- a/docs/guides/src/main/server/logging.adoc +++ b/docs/guides/src/main/server/logging.adoc @@ -172,7 +172,7 @@ To configure a different logging format for the file log handler, enter the foll <@kc.start parameters="--log-file-format="/> -Please see the <> section in this guide for more information and a table of the available pattern configuration. +See <> for more information and a table of the available pattern configuration. == Centralized logging using GELF Keycloak can send logs to a centralized log management system such as the following: @@ -491,6 +491,6 @@ nothing below the error level will be sent to your logging stack. That means tha === Configure additional key values Currently, the Keycloak configuration does not support partly dynamic configuration keys, as they are used in quarkus properties. For example, they are used when defining `quarkus.log.handler.gelf.additional-field..value`. -To add user-defined fields, you can provide these fields through a quarkus.properties file. Refer to the <@links.server id="configuration"/> guide and the _Using unsupported server options_ section. +To add user-defined fields, you can provide these fields through a quarkus.properties file. See <@links.server id="configuration"/> and the _Using raw Quarkus properties_ section. diff --git a/docs/guides/src/main/server/outgoinghttp.adoc b/docs/guides/src/main/server/outgoinghttp.adoc index 83498c42a3..7cffd1ae3f 100644 --- a/docs/guides/src/main/server/outgoinghttp.adoc +++ b/docs/guides/src/main/server/outgoinghttp.adoc @@ -120,7 +120,7 @@ In this example, the following occurs: == Configuring trusted certificates for TLS connections -Please take a look at the <@links.server id="keycloak-truststore"/> guide about how +See <@links.server id="keycloak-truststore"/> for how to configure a Keycloak Truststore so that Keycloak is able to perform outgoing requests using TLS. diff --git a/docs/guides/src/main/server/reverseproxy.adoc b/docs/guides/src/main/server/reverseproxy.adoc index a845e8b20e..f414b7877d 100644 --- a/docs/guides/src/main/server/reverseproxy.adoc +++ b/docs/guides/src/main/server/reverseproxy.adoc @@ -218,7 +218,7 @@ to load additional certificates from headers `CERT_CHAIN_0` to `CERT_CHAIN_9` if The NGINX SSL/TLS module does not expose the client certificate chain. Keycloak’s NGINX certificate lookup provider rebuilds it by using the Keycloak truststore. -If you are using this provider, please take a look at the <@links.server id="keycloak-truststore"/> guide about how +If you are using this provider, see <@links.server id="keycloak-truststore"/> for how to configure a Keycloak Truststore.