libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases 1 Packages Activity Actions

Eliminate guide from cross-references (#17065)

Browse source 
Closes #17055
This commit is contained in:
andymunro 2023-02-27 08:57:43 -05:00 committed by GitHub
parent 3cd413dee1
commit 48519be52b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
10 changed files with 24 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/guides/src/main/server/caching.adoc
View file

@ -230,7 +230,7 @@ The current Infinispan cache implementation should be secured by various securit
== Exposing metrics from caches == Exposing metrics from caches
By default, metrics from caches are not automatically exposed when the metrics are enabled. 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: 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:

2
docs/guides/src/main/server/configuration-metrics.adoc
View file

@ -72,7 +72,7 @@ The table below summarizes the available metrics groups:
|A set of global and individual metrics from the HTTP endpoints |A set of global and individual metrics from the HTTP endpoints
|Cache |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.
|=== |===

10
docs/guides/src/main/server/configuration-production.adoc
View file

@ -14,27 +14,27 @@ This guide describes the general areas of configuration required for a productio
== TLS for secure communication == 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. 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 == 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. 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 == 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. 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 == 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 == 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. 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. 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 == Configure Keycloak Server with IPv6 or IPv4

13
docs/guides/src/main/server/configuration.adoc
View file

@ -49,7 +49,10 @@ Values that go into the configuration file are following the `<key-with-dashes>=
You can easily translate a Key/Value pair from one configuration source to the other. 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. 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"/> <@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 === Using raw Quarkus properties
In most cases, the available configuration options should suffice to configure the server. 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 * Hostname configuration is expected
* HTTPS/TLS 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. 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. 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: 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"/> <@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. 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. 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.

2
docs/guides/src/main/server/containers.adoc
View file

@ -119,7 +119,7 @@ podman|docker run --name mykeycloak -p 8080:8080 \
Invoking this command starts the Keycloak server in development mode. Invoking this command starts the Keycloak server in development mode.
This mode should be strictly avoided in production environments because it has insecure defaults. 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 == Running a standard keycloak container
In keeping with concepts such as immutable infrastructure, containers need to be re-provisioned routinely. In keeping with concepts such as immutable infrastructure, containers need to be re-provisioned routinely.

2
docs/guides/src/main/server/enabletls.adoc
View file

@ -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. 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"/>.
</@tmpl.guide> </@tmpl.guide>

7
docs/guides/src/main/server/hostname.adoc
View file

@ -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. 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. 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 == Example Scenarios
The following are more example scenarios and the corresponding commands for setting up a hostname. 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, 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"/>.
see <@links.server id="enabletls"/> guide.
=== Exposing the server behind a TLS termination proxy === 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"/> <@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, 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 === Forcing backend endpoints to use the same URL the server is exposed

4
docs/guides/src/main/server/logging.adoc
View file

@ -172,7 +172,7 @@ To configure a different logging format for the file log handler, enter the foll
<@kc.start parameters="--log-file-format=<pattern>"/> <@kc.start parameters="--log-file-format=<pattern>"/>
Please see the <<Configuring the console log format>> section in this guide for more information and a table of the available pattern configuration. See <<Configuring the console log format>> for more information and a table of the available pattern configuration.
== Centralized logging using GELF == Centralized logging using GELF
Keycloak can send logs to a centralized log management system such as the following: 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 === 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.<my-name>.value`. 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.<my-name>.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.
</@tmpl.guide> </@tmpl.guide>

2
docs/guides/src/main/server/outgoinghttp.adoc
View file

@ -120,7 +120,7 @@ In this example, the following occurs:
== Configuring trusted certificates for TLS connections == 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. to configure a Keycloak Truststore so that Keycloak is able to perform outgoing requests using TLS.
</@tmpl.guide> </@tmpl.guide>

2
docs/guides/src/main/server/reverseproxy.adoc
View file

@ -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. 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. to configure a Keycloak Truststore.
</@tmpl.guide> </@tmpl.guide>