diff --git a/docs/documentation/pom.xml b/docs/documentation/pom.xml index e7a4ed9ff0..a29f0e5d39 100644 --- a/docs/documentation/pom.xml +++ b/docs/documentation/pom.xml @@ -20,7 +20,6 @@ keycloak-images UTF-8 - 1.5.5 3.0.0 3.0.2 3.0.1 @@ -132,7 +131,6 @@ org.asciidoctor asciidoctor-maven-plugin - ${version.plugin.asciidoctor} asciidoc-to-html @@ -144,9 +142,8 @@ ${basedir}/target/sources ${masterFile}.adoc html5 - coderay - + coderay ./ left left @@ -166,6 +163,11 @@ + + + WARN + + diff --git a/docs/documentation/release_notes/topics/18_0_0.adoc b/docs/documentation/release_notes/topics/18_0_0.adoc index a9ca945e12..2a14c9af77 100644 --- a/docs/documentation/release_notes/topics/18_0_0.adoc +++ b/docs/documentation/release_notes/topics/18_0_0.adoc @@ -95,7 +95,7 @@ The {project_name} Quarkus distribution now supports importing your realms direc The {project_name} Quarkus distribution now initially supports logging to a File and logging structured data using JSON. -For more information on the improvements, check the corresponding https://www.keycloak.org/server/logging[guide]. +For more information on the improvements, check the corresponding https://www.keycloak.org/server/logging[Logging] {section}. === Environment variable expansion for values in keycloak.conf diff --git a/docs/documentation/release_notes/topics/19_0_0.adoc b/docs/documentation/release_notes/topics/19_0_0.adoc index b96cc51c8d..bbdfcbc3dd 100644 --- a/docs/documentation/release_notes/topics/19_0_0.adoc +++ b/docs/documentation/release_notes/topics/19_0_0.adoc @@ -92,4 +92,4 @@ See also the https://kubernetes.io/docs/tasks/run-application/configure-pdb/[Kub Starting with version 19, Keycloak supports sending logs using GELF to centralized logging solutions like ELK, EFK or Graylog out of the box. -You can find the documentation and examples to get you up and running quickly in the https://www.keycloak.org/server/logging#_centralized_logging_using_gelf[logging guide] +You can find the documentation and examples to get you up and running quickly in the https://www.keycloak.org/server/logging#_centralized_logging_using_gelf[logging] {section}. diff --git a/docs/documentation/release_notes/topics/20_0_0.adoc b/docs/documentation/release_notes/topics/20_0_0.adoc index c1fc63a836..5629fa8fc8 100644 --- a/docs/documentation/release_notes/topics/20_0_0.adoc +++ b/docs/documentation/release_notes/topics/20_0_0.adoc @@ -35,7 +35,7 @@ Console: * `hostname-url` * `hostname-admin-url` -More details can be found at the https://www.keycloak.org/server/hostname[Configuring the Hostname Guide]. +More details can be found at the https://www.keycloak.org/server/hostname[Configuring the Hostname] {section}. = Improvements to `kc.bat` when running Keycloak on Windows diff --git a/docs/documentation/release_notes/topics/21_0_0.adoc b/docs/documentation/release_notes/topics/21_0_0.adoc index 520812b262..91ae7084fd 100644 --- a/docs/documentation/release_notes/topics/21_0_0.adoc +++ b/docs/documentation/release_notes/topics/21_0_0.adoc @@ -61,7 +61,7 @@ should be replaced with the `CLIENT_ID` searchable field used with the operators = FIPS 140-2 preview support FIPS 140-2 support in Keycloak, which was experimental in the previous release, is now promoted to preview. There were many fixes and improvements to create this preview version. -For the details, see the https://www.keycloak.org/guides#server[FIPS documentation]. Feedback is welcome! +For the details, see the https://www.keycloak.org/server/fips[FIPS documentation]. Feedback is welcome! Thanks again to https://github.com/david-rh[David Anderson], https://github.com/sudeepd[Sudeep Das] and https://github.com/isaacjensen[Isaac Jensen] for their huge help with this feature. @@ -72,7 +72,7 @@ In addition to recognize the non-standard `X-Forwarded-*` to fetch information added by proxies that would otherwise be altered or lost when proxy servers are involved in the path of the request, Keycloak can now leverage the standard `Forwarded` header for the same purpose. -For more details, see the https://www.keycloak.org/server/reverseproxy[Using a reverse proxy] guide. +For more details, see the https://www.keycloak.org/server/reverseproxy[Using a reverse proxy] {section}. Please, make sure your proxy is also overriding the `Forwarded` header when making requests to Keycloak nodes. @@ -82,7 +82,7 @@ To enhance security, the https://quay.io/repository/keycloak/keycloak?tab=info[K The change to UBI9 will not have any impact on most users. In rare cases the glibc error https://github.com/keycloak/keycloak/issues/17290[CPU does not support x86-64-v2] may appear. `+x86-64-v2+` has been available from processors since 2009. You're most likely to encounter this issue when your virtualization environment is misconfigured. -The change from `+-minimal+` to `+-micro+` has more potential impact. Users making simple customizations to the image won't notice any difference, however any user that installs RPMs will need to change how they do that. The https://www.keycloak.org/server/containers[container guide] has been updated to show you how. +The change from `+-minimal+` to `+-micro+` has more potential impact. Users making simple customizations to the image won't notice any difference, however any user that installs RPMs will need to change how they do that. The https://www.keycloak.org/server/containers[Running Keycloak in a container] {section} has been updated to show you how. As a result of these changes, there has been an 82% reduction in known CVEs affecting the Keycloak Container Image! diff --git a/docs/documentation/securing_apps/topics/docker/docker-overview.adoc b/docs/documentation/securing_apps/topics/docker/docker-overview.adoc index fd04d4b2b9..32f1a3fb7d 100644 --- a/docs/documentation/securing_apps/topics/docker/docker-overview.adoc +++ b/docs/documentation/securing_apps/topics/docker/docker-overview.adoc @@ -1,7 +1,7 @@ == Configuring a Docker registry to use {project_name} -NOTE: Docker authentication is disabled by default. To enable see the https://www.keycloak.org/server/features[Enabling and disabling features] guide. +NOTE: Docker authentication is disabled by default. To enable see the https://www.keycloak.org/server/features[Enabling and disabling features] {section}. This section describes how you can configure a Docker registry to use {project_name} as its authentication server. diff --git a/docs/documentation/securing_apps/topics/oidc/fapi-support.adoc b/docs/documentation/securing_apps/topics/oidc/fapi-support.adoc index 69e183d53e..cab00ee94e 100644 --- a/docs/documentation/securing_apps/topics/oidc/fapi-support.adoc +++ b/docs/documentation/securing_apps/topics/oidc/fapi-support.adoc @@ -39,4 +39,4 @@ in the more strict way to enforce some of the requirements. Especially: As confidential information is being exchanged, all interactions shall be encrypted with TLS (HTTPS). Moreover, there are some requirements in the FAPI specification for the cipher suites and TLS protocol versions used. To match these requirements, you can consider configure allowed ciphers. This configuration can be done by setting the `https-protocols` and `https-cipher-suites` options. {project_name} uses `TLSv1.3` by default and hence it is possibly not needed to change the default settings. However it -may be needed to adjust ciphers if you need to fall back to lower TLS version for some reason. For more details, see https://www.keycloak.org/server/enabletls[Configuring TLS] guide. +may be needed to adjust ciphers if you need to fall back to lower TLS version for some reason. For more details, see https://www.keycloak.org/server/enabletls[Configuring TLS] {section}. diff --git a/docs/documentation/securing_apps/topics/token-exchange/token-exchange.adoc b/docs/documentation/securing_apps/topics/token-exchange/token-exchange.adoc index b106f4f66f..e2cff86c56 100644 --- a/docs/documentation/securing_apps/topics/token-exchange/token-exchange.adoc +++ b/docs/documentation/securing_apps/topics/token-exchange/token-exchange.adoc @@ -10,7 +10,7 @@ include::../templates/techpreview.adoc[] [NOTE] ==== To use more than the <<_internal-token-to-internal-token-exchange,Internal Token to Internal Token Exchange>> flow, also enable the `admin_fine_grained_authz` feature. -For details, see the https://www.keycloak.org/server/features[Enabling and disabling features] guide. +For details, see the https://www.keycloak.org/server/features[Enabling and disabling features] {section}. ==== === How token exchange works diff --git a/docs/documentation/server_admin/topics/authentication/webauthn.adoc b/docs/documentation/server_admin/topics/authentication/webauthn.adoc index 6d61404ec2..162a927c5d 100644 --- a/docs/documentation/server_admin/topics/authentication/webauthn.adoc +++ b/docs/documentation/server_admin/topics/authentication/webauthn.adoc @@ -151,7 +151,7 @@ The configurable items and their description are as follows: ==== Attestation statement verification -When registering a WebAuthn authenticator, {project_name} verifies the trustworthiness of the attestation statement generated by the WebAuthn authenticator. {project_name} requires the trust anchor's certificates imported into the [truststore](https://www.keycloak.org/server/keycloak-truststore). +When registering a WebAuthn authenticator, {project_name} verifies the trustworthiness of the attestation statement generated by the WebAuthn authenticator. {project_name} requires the trust anchor's certificates imported into the https://www.keycloak.org/server/keycloak-truststore[truststore]. To omit this validation, disable this truststore or set the WebAuthn policy's configuration item "Attestation Conveyance Preference" to "none". diff --git a/docs/documentation/server_admin/topics/realms/keys.adoc b/docs/documentation/server_admin/topics/realms/keys.adoc index 682d29bbc3..bf8a996ca3 100644 --- a/docs/documentation/server_admin/topics/realms/keys.adoc +++ b/docs/documentation/server_admin/topics/realms/keys.adoc @@ -67,7 +67,7 @@ A list of *Active* keys appears. The certificate appears in text form. . Save the certificate to a file and enclose it in these lines. + -[Source,Bash,Subs=+Attributes] +[source,bash,subs=+attributes] ---- ----Begin Certificate---- @@ -77,19 +77,19 @@ The certificate appears in text form. . Remove the current RSA public key certificate from the keystore. + -[Source,Bash,Subs=+Attributes] +[source,bash,subs=+attributes] ---- keytool -delete -keystore .jks -storepass -alias ---- . Import the new certificate into the keystore + -[Source,Bash,Subs=+Attributes] +[source,bash,subs=+attributes] ---- keytool -importcert -file domain.crt -keystore .jks -storepass -alias ---- . Rebuild the application. + -[Source,Bash,Subs=+Attributes] +[source,bash,subs=+attributes] ---- mvn clean install wildfly:deploy ---- diff --git a/docs/documentation/server_admin/topics/sso-protocols/con-sso-docker.adoc b/docs/documentation/server_admin/topics/sso-protocols/con-sso-docker.adoc index 885a75a41f..a8f54894ad 100644 --- a/docs/documentation/server_admin/topics/sso-protocols/con-sso-docker.adoc +++ b/docs/documentation/server_admin/topics/sso-protocols/con-sso-docker.adoc @@ -6,7 +6,7 @@ [NOTE] ==== -Docker authentication is disabled by default. To enable docker authentication, see the https://www.keycloak.org/server/features[Enabling and disabling features] guide. +Docker authentication is disabled by default. To enable docker authentication, see the https://www.keycloak.org/server/features[Enabling and disabling features] {section}. ==== [role="_abstract"] link:https://docs.docker.com/registry/spec/auth/[Docker Registry V2 Authentication] is a protocol, similar to OIDC, that authenticates users against Docker registries. {project_name}'s implementation of this protocol lets Docker clients use a {project_name} authentication server authenticate against a registry. This protocol uses standard token and signature mechanisms but it does deviate from a true OIDC implementation. It deviates by using a very specific JSON format for requests and responses as well as mapping repository names and permissions to the OAuth scope mechanism. diff --git a/docs/documentation/server_admin/topics/sso-protocols/docker.adoc b/docs/documentation/server_admin/topics/sso-protocols/docker.adoc index 1f16df23fa..c21d547df5 100644 --- a/docs/documentation/server_admin/topics/sso-protocols/docker.adoc +++ b/docs/documentation/server_admin/topics/sso-protocols/docker.adoc @@ -2,7 +2,7 @@ === Docker Registry v2 Authentication -NOTE: Docker authentication is disabled by default. To enable see the https://www.keycloak.org/server/features[Enabling and disabling features] guide. +NOTE: Docker authentication is disabled by default. To enable see the https://www.keycloak.org/server/features[Enabling and disabling features] {section}. link:https://docs.docker.com/registry/spec/auth/[Docker Registry V2 Authentication] is an OIDC-Like protocol used to authenticate users against a Docker registry. {project_name}'s implementation of this protocol allows for a {project_name} authentication server to be used by a Docker client to authenticate against a registry. While this protocol uses fairly standard token and signature mechanisms, it has a few wrinkles that prevent it from being treated as a true OIDC implementation. The largest deviations include a very specific JSON format for requests and responses as well as the ability to understand how to map repository names and permissions to the OAuth scope mechanism. diff --git a/docs/documentation/server_admin/topics/user-federation/ldap.adoc b/docs/documentation/server_admin/topics/user-federation/ldap.adoc index f767e39f9b..aab2149c1f 100644 --- a/docs/documentation/server_admin/topics/user-federation/ldap.adoc +++ b/docs/documentation/server_admin/topics/user-federation/ldap.adoc @@ -76,7 +76,7 @@ Hover the mouse pointer over the tooltips in the Admin Console to see more detai When you configure a secure connection URL to your LDAP store (for example,`ldaps://myhost.com:636`), {project_name} uses SSL to communicate with the LDAP server. Configure a truststore on the {project_name} server side so that {project_name} can trust the SSL connection to LDAP. -Configure the global truststore for {project_name} with the Truststore SPI. For more information about configuring the global truststore, see the [Configuring a Truststore](https://www.keycloak.org/server/keycloak-truststore) guide. If you do not configure the Truststore SPI, the truststore falls back to the default mechanism provided by Java, which can be the file supplied by the `javax.net.ssl.trustStore` system property or the cacerts file from the JDK if the system property is unset. +Configure the global truststore for {project_name} with the Truststore SPI. For more information about configuring the global truststore, see the https://www.keycloak.org/server/keycloak-truststore[Configuring a Truststore] {section}. If you do not configure the Truststore SPI, the truststore falls back to the default mechanism provided by Java, which can be the file supplied by the `javax.net.ssl.trustStore` system property or the cacerts file from the JDK if the system property is unset. The `Use Truststore SPI` configuration property, in the LDAP federation provider configuration, controls the truststore SPI. By default, {project_name} sets the property to `Only for ldaps`, which is adequate for most deployments. {project_name} uses the Truststore SPI if the connection URL to LDAP starts with `ldaps` only. diff --git a/docs/documentation/server_development/topics/providers.adoc b/docs/documentation/server_development/topics/providers.adoc index 94461ec1c1..1eb3ddcb3a 100644 --- a/docs/documentation/server_development/topics/providers.adoc +++ b/docs/documentation/server_development/topics/providers.adoc @@ -85,7 +85,7 @@ Example service configuration file (`META-INF/services/org.keycloak.theme.ThemeS org.acme.provider.MyThemeSelectorProviderFactory ---- -To configure your provider, see the link:https://www.keycloak.org/server/configuration-provider[Configuring Providers] guide. +To configure your provider, see the link:https://www.keycloak.org/server/configuration-provider[Configuring Providers] {section}. For example, to configure a provider you can set options as follows: @@ -127,7 +127,7 @@ public class MyThemeSelectorProvider implements ThemeSelectorProvider { As mentioned above, it is recommended that your `ProviderFactory` implementations use unique ID. However at the same time, it can be useful to override one of the {project_name} built-in providers. The recommended way for this is still ProviderFactory implementation with unique ID and then for instance set the default provider as -specified in the link:https://www.keycloak.org/server/configuration-provider[Configuring Providers] guide. On the other hand, this may not be always possible. +specified in the link:https://www.keycloak.org/server/configuration-provider[Configuring Providers] {section}. On the other hand, this may not be always possible. For instance when you need some customizations to default OpenID Connect protocol behaviour and you want to override default {project_name} implementation of `OIDCLoginProtocolFactory` you need to preserve same providerId. As for example admin console, OIDC protocol well-known endpoint and various other things rely on diff --git a/docs/documentation/topics/templates/deprecated.adoc b/docs/documentation/topics/templates/deprecated.adoc index 526bef6c6f..8de595737e 100644 --- a/docs/documentation/topics/templates/deprecated.adoc +++ b/docs/documentation/topics/templates/deprecated.adoc @@ -7,6 +7,6 @@ To enable start the server with ifdef::tech_feature_setting[] `{tech_feature_setting}` endif::[] -. For more details see the https://www.keycloak.org/server/features[Enabling and disabling features] guide. +. For more details see the https://www.keycloak.org/server/features[Enabling and disabling features] {section}. ==== endif::[] diff --git a/docs/documentation/topics/templates/document-attributes.adoc b/docs/documentation/topics/templates/document-attributes.adoc index 5f5897fc46..7f292091d1 100644 --- a/docs/documentation/topics/templates/document-attributes.adoc +++ b/docs/documentation/topics/templates/document-attributes.adoc @@ -114,3 +114,6 @@ :subsystem_infinispan_xml_urn: urn:jboss:domain:infinispan:12.0 :subsystem_datasources_xml_urn: urn:jboss:domain:datasources:6.0 :saml_adapter_xsd_urn: https://www.keycloak.org/schema/keycloak_saml_adapter_1_10.xsd + +:section: guide +:sections: guides