From 00b68920819afdf04bb10036aad05b8ab8c53fb0 Mon Sep 17 00:00:00 2001 From: Steve Hawkins Date: Tue, 27 May 2025 15:19:45 -0400 Subject: [PATCH 1/7] fix: adding a -- separator for spi options closes: #39063 Signed-off-by: Steve Hawkins --- core/src/main/java/org/keycloak/Config.java | 4 ++ .../guides/server/configuration-provider.adoc | 56 +++++++++++++++---- .../runtime/configuration/Configuration.java | 8 ++- .../MicroProfileConfigProvider.java | 28 +++++----- .../mappers/PropertyMappers.java | 2 +- .../configuration/test/ConfigurationTest.java | 3 +- .../it/cli/dist/StartCommandDistTest.java | 4 +- .../util/SpiProvidersSwitchingUtils.java | 6 +- 8 files changed, 74 insertions(+), 37 deletions(-) diff --git a/core/src/main/java/org/keycloak/Config.java b/core/src/main/java/org/keycloak/Config.java index c7e38fa4b320..128980cbcda1 100755 --- a/core/src/main/java/org/keycloak/Config.java +++ b/core/src/main/java/org/keycloak/Config.java @@ -235,6 +235,10 @@ public static interface Scope { Scope scope(String... scope); + /** + * @deprecated to be removed + */ + @Deprecated Set getPropertyNames(); } } diff --git a/docs/guides/server/configuration-provider.adoc b/docs/guides/server/configuration-provider.adoc index 7613b5d3fec5..211c51730934 100644 --- a/docs/guides/server/configuration-provider.adoc +++ b/docs/guides/server/configuration-provider.adoc @@ -19,6 +19,12 @@ any provider, including those you have implemented to extend the server capabili Providers can be configured by using a specific configuration format. The format consists of: [source] +---- +spi-----= +---- + +Or if there is no possibility of ambiguity between multiple providers: + ---- spi---= ---- @@ -27,7 +33,9 @@ The `` is the name of the SPI you want to configure. The `` is the id of the provider you want to configure. This is the id set to the corresponding provider factory implementation. -The `` is the actual name of the property you want to set for a given provider. +The `` is the actual name of the property you want to set for a given provider + +NOTE: the property name `enabled` is effectively reserved for enabling / disabling a provider All those names (for spi, provider, and property) should be in lower case and if the name is in camel-case such as `myKeycloakProvider`, it should include dashes (`-`) before upper-case letters as follows: `my-keycloak-provider`. @@ -35,31 +43,47 @@ Taking the `HttpClientSpi` SPI as an example, the name of the SPI is `connection [source] ---- -spi-connections-http-client-default-connection-pool-size=10 +spi-connections-http-client--default--connection-pool-size=10 ---- -== Setting a provider configuration option +=== Setting a provider configuration option Provider configuration options are provided when starting the server. See all support configuration sources and formats for options in <@links.server id="configuration"/>. For example via a command line option: .Setting the `connection-pool-size` for the `default` provider of the `connections-http-client` SPI -<@kc.start parameters="--spi-connections-http-client-default-connection-pool-size=10"/> +<@kc.start parameters="--spi-connections-http-client--default--connection-pool-size=10"/> + +== Build time options -== Configuring a single provider for an SPI +=== Configuring a single provider for an SPI Depending on the SPI, multiple provider implementations can co-exist but only one of them is going to be used at runtime. -For these SPIs, a specific provider is the primary implementation that is going to be active and used at runtime. +For these SPIs, a specific provider is the primary implementation that is going to be active and used at runtime. The format consists of: + +[source] +---- +spi---provider= +---- + +NOTE: `spi--provider=` may still be used, but the server will not properly detect when reaugmentation is needed. To configure a provider as the single provider you should run the `build` command as follows: .Marking the `mycustomprovider` provider as the single provider for the `email-template` SPI -<@kc.build parameters="--spi-email-template-provider=mycustomprovider"/> +<@kc.build parameters="--spi-email-template--provider=mycustomprovider"/> -== Configuring a default provider for an SPI +=== Configuring a default provider for an SPI Depending on the SPI, multiple provider implementations can co-exist and one is used by default. For these SPIs, a specific provider is the default implementation that is going to selected unless a specific provider -is requested. +is requested. The format consists of: + +[source] +---- +spi---provider-default= +---- + +NOTE: `spi--provider-default=` may still be used, but the server will not properly detect when reaugmentation is needed. The following logic is used to determine the default provider: @@ -70,15 +94,23 @@ The following logic is used to determine the default provider: To configure a provider as the default provider you should run the `build` command as follows: .Marking the `mycustomhash` provider as the default provider for the `password-hashing` SPI -<@kc.build parameters="--spi-password-hashing-provider-default=mycustomprovider"/> +<@kc.build parameters="--spi-password-hashing--provider-default=mycustomprovider"/> +=== Enabling and disabling a provider + +The format consists of: + +[source] +---- +spi-----enabled= +---- -== Enabling and disabling a provider +NOTE: `spi---enabled=` may still be used, but the server will not properly detect when reaugmentation is needed. To enable or disable a provider you should run the `build` command as follows: .Enabling a provider -<@kc.build parameters="--spi-email-template-mycustomprovider-enabled=true"/> +<@kc.build parameters="--spi-email-template--mycustomprovider--enabled=true"/> To disable a provider, use the same command and set the `enabled` property to `false`. diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/Configuration.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/Configuration.java index 272805f8bcc8..7ee801bb1833 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/Configuration.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/Configuration.java @@ -20,7 +20,6 @@ import static org.keycloak.quarkus.runtime.cli.Picocli.ARG_PREFIX; import java.util.Map; -import java.util.Objects; import java.util.Optional; import java.util.Properties; @@ -29,7 +28,6 @@ import io.smallrye.config.SmallRyeConfig; import org.keycloak.config.Option; -import org.keycloak.quarkus.runtime.cli.Picocli; import org.keycloak.utils.StringUtil; import static org.keycloak.quarkus.runtime.configuration.MicroProfileConfigProvider.NS_KEYCLOAK_PREFIX; @@ -178,11 +176,17 @@ public static String toCliFormat(String key) { } public static String toDashCase(String key) { + if (key == null) { + return null; + } StringBuilder sb = new StringBuilder(key.length()); boolean l = false; for (int i = 0; i < key.length(); i++) { char c = key.charAt(i); + if (c == ',') { + c = '-'; // should not happen, but was allowed by the previous logic + } if (l && Character.isUpperCase(c)) { sb.append('-'); c = Character.toLowerCase(c); diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/MicroProfileConfigProvider.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/MicroProfileConfigProvider.java index ca7cf4f3bdb7..70732a65e093 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/MicroProfileConfigProvider.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/MicroProfileConfigProvider.java @@ -19,12 +19,10 @@ import static org.keycloak.quarkus.runtime.configuration.Configuration.OPTION_PART_SEPARATOR; import static org.keycloak.quarkus.runtime.configuration.Configuration.toDashCase; -import static org.keycloak.quarkus.runtime.configuration.Configuration.toEnvVarFormat; import java.util.Set; import java.util.stream.Collectors; import java.util.stream.StreamSupport; -import org.apache.commons.lang3.ArrayUtils; import org.eclipse.microprofile.config.ConfigProvider; import org.keycloak.Config; @@ -33,6 +31,7 @@ public class MicroProfileConfigProvider implements Config.ConfigProvider { public static final String NS_KEYCLOAK = "kc"; public static final String NS_KEYCLOAK_PREFIX = NS_KEYCLOAK + "."; + public static final String SPI_PREFIX = NS_KEYCLOAK_PREFIX + "spi" + OPTION_PART_SEPARATOR; public static final String NS_QUARKUS = "quarkus"; public static final String NS_QUARKUS_PREFIX = "quarkus" + "."; @@ -58,21 +57,21 @@ public String getDefaultProvider(String spi) { @Override public Config.Scope scope(String... scope) { - return new MicroProfileScope(scope); + return new MicroProfileScope(SPI_PREFIX, scope); } public class MicroProfileScope implements Config.Scope { - private final String[] scope; private final String prefix; + private final String separatorPrefix; - public MicroProfileScope(String... scopes) { - this.scope = scopes; - StringBuilder prefix = new StringBuilder(NS_KEYCLOAK_PREFIX).append("spi"); + public MicroProfileScope(String prefix, String... scopes) { + StringBuilder prefixBuilder = new StringBuilder(prefix); for (String scope : scopes) { - prefix.append(OPTION_PART_SEPARATOR).append(scope); + prefixBuilder.append(toDashCase(scope)).append(OPTION_PART_SEPARATOR + OPTION_PART_SEPARATOR); } - this.prefix = prefix.toString(); + this.separatorPrefix = prefixBuilder.toString(); + this.prefix = separatorPrefix.replace(OPTION_PART_SEPARATOR + OPTION_PART_SEPARATOR, OPTION_PART_SEPARATOR); } @Override @@ -122,23 +121,22 @@ public Boolean getBoolean(String key, Boolean defaultValue) { @Override public Config.Scope scope(String... scope) { - return new MicroProfileScope(ArrayUtils.addAll(this.scope, scope)); + return new MicroProfileScope(prefix, scope); } @Override public Set getPropertyNames() { return StreamSupport.stream(config.getPropertyNames().spliterator(), false) - .filter(this::startWithPrefix) + .filter(key -> key.startsWith(prefix)) .collect(Collectors.toSet()); } private T getValue(String key, Class clazz, T defaultValue) { - return config.getOptionalValue(toDashCase(prefix.concat(OPTION_PART_SEPARATOR).concat(key.replace('.', '-'))), clazz).orElse(defaultValue); + String dashCase = toDashCase(key); + return config.getOptionalValue(separatorPrefix.concat(dashCase), clazz) + .or(() -> config.getOptionalValue(prefix.concat(dashCase), clazz)).orElse(defaultValue); } - private boolean startWithPrefix(String key) { - return key.startsWith(toDashCase(prefix)) || key.startsWith(toDashCase(toEnvVarFormat(prefix))); - } } } diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/PropertyMappers.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/PropertyMappers.java index a38f29a31e4d..804a1e8716e5 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/PropertyMappers.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/PropertyMappers.java @@ -97,7 +97,7 @@ public static ConfigValue getValue(ConfigSourceInterceptorContext context, Strin } public static boolean isSpiBuildTimeProperty(String name) { - return name.startsWith(KC_SPI_PREFIX) && (name.endsWith("-provider") || name.endsWith("-enabled") || name.endsWith("-provider-default")); + return name.startsWith(KC_SPI_PREFIX) && (name.endsWith("--provider") || name.endsWith("--enabled") || name.endsWith("--provider-default")); } private static boolean isKeycloakRuntime(String name, PropertyMapper mapper) { diff --git a/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/configuration/test/ConfigurationTest.java b/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/configuration/test/ConfigurationTest.java index 86671d7a49e8..f27e0ab3e078 100644 --- a/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/configuration/test/ConfigurationTest.java +++ b/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/configuration/test/ConfigurationTest.java @@ -206,11 +206,10 @@ public void testPropertyNamesFromConfig() { System.getProperties().remove("kc.spi-client-registration-openid-connect-static-jwk-url"); putEnvVar("KC_SPI_CLIENT_REGISTRATION_OPENID_CONNECT_STATIC_JWK_URL", "http://c.jwk.url/from-env"); config = initConfig("client-registration", "openid-connect"); - assertEquals(2, config.getPropertyNames().size()); // transformed name is coming from KcEnvVarConfigSource, raw env var name is coming from EnvVarConfigSource + assertEquals(1, config.getPropertyNames().size()); assertEquals("http://c.jwk.url/from-env", config.get("static-jwk-url")); } - @Test public void testPropertyMapping() { ConfigArgsConfigSource.setCliArgs("--db=mariadb", "--db-url=jdbc:mariadb://localhost/keycloak"); diff --git a/quarkus/tests/integration/src/test/java/org/keycloak/it/cli/dist/StartCommandDistTest.java b/quarkus/tests/integration/src/test/java/org/keycloak/it/cli/dist/StartCommandDistTest.java index 4461f99f9f2d..5e7421b18ae7 100644 --- a/quarkus/tests/integration/src/test/java/org/keycloak/it/cli/dist/StartCommandDistTest.java +++ b/quarkus/tests/integration/src/test/java/org/keycloak/it/cli/dist/StartCommandDistTest.java @@ -76,8 +76,8 @@ void errorSpiBuildtimeAtRuntime(KeycloakDistribution dist) { CLIResult cliResult = dist.run("build", "--db=dev-file"); cliResult.assertBuild(); - cliResult = dist.run("start", "--optimized", "--http-enabled=true", "--hostname-strict=false", "--spi-events-listener-jboss-logging-enabled=false"); - cliResult.assertError("The following build time options have values that differ from what is persisted - the new values will NOT be used until another build is run: kc.spi-events-listener-jboss-logging-enabled"); + cliResult = dist.run("start", "--optimized", "--http-enabled=true", "--hostname-strict=false", "--spi-events-listener--jboss-logging--enabled=false"); + cliResult.assertError("The following build time options have values that differ from what is persisted - the new values will NOT be used until another build is run: kc.spi-events-listener--jboss-logging--enabled"); } @DryRun diff --git a/testsuite/integration-arquillian/tests/base/src/main/java/org/keycloak/testsuite/util/SpiProvidersSwitchingUtils.java b/testsuite/integration-arquillian/tests/base/src/main/java/org/keycloak/testsuite/util/SpiProvidersSwitchingUtils.java index b0a4a5d396c3..b5f56d01b66d 100644 --- a/testsuite/integration-arquillian/tests/base/src/main/java/org/keycloak/testsuite/util/SpiProvidersSwitchingUtils.java +++ b/testsuite/integration-arquillian/tests/base/src/main/java/org/keycloak/testsuite/util/SpiProvidersSwitchingUtils.java @@ -69,14 +69,14 @@ private String getProviderPropertyNameConfig(String spiName, String providerId, @Override public void setDefaultProvider(Container container, String spiName, String providerId, String... config) { List args = new LinkedList<>(); - args.add(KEYCLOAKX_ARG_SPI_PREFIX + toDashCase(spiName) + "-provider=" + providerId); + args.add(KEYCLOAKX_ARG_SPI_PREFIX + toDashCase(spiName) + "--provider=" + providerId); if (config != null) { String optionName = null; for (String c : config) { if (optionName == null) { optionName = c; } else { - args.add(KEYCLOAKX_ARG_SPI_PREFIX + toDashCase(spiName) + "-" + providerId + "-" + optionName + "=" + c); + args.add(KEYCLOAKX_ARG_SPI_PREFIX + toDashCase(spiName) + "--" + providerId + "--" + optionName + "=" + c); optionName = null; } } @@ -197,7 +197,7 @@ public static void removeProvider(SuiteContext suiteContext, SetDefaultProvider Container container = authServerInfo.getArquillianContainer(); log.infof("Removing default provider setting for %s", spi); - + if (annotation.onlyUpdateDefault()) { spiSwitcher.unsetDefaultProvider(container, spi); } else { From 2b47b040870d10e286bdc57d8de72bbb0ad91c02 Mon Sep 17 00:00:00 2001 From: Steve Hawkins Date: Tue, 3 Jun 2025 08:26:00 -0400 Subject: [PATCH 2/7] adding a warning for ambiguous spi options also adding a note about the change Signed-off-by: Steve Hawkins # Conflicts: # docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc --- .../topics/changes/changes-26_3_0.adoc | 9 +++++++++ .../keycloak/quarkus/runtime/cli/Picocli.java | 17 ++++++++++++----- .../configuration/mappers/PropertyMappers.java | 4 ++++ .../quarkus/runtime/cli/PicocliTest.java | 7 +++++++ 4 files changed, 32 insertions(+), 5 deletions(-) diff --git a/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc b/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc index ff295e29fc73..64a32407f3aa 100644 --- a/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc +++ b/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc @@ -80,6 +80,15 @@ the user account will be updated to (un)mark the email as verified. In the future, we might evaluate changing this specific configuration to avoid automatic updates on the email verification status on federated user accounts depending on the use cases and the demand from the community. +=== Buildtime SPI Options + +SPI options ending in -enabled, -provider-default, or -provider were previously treated as buildtime. However in some instances this was not correct as a provider could have a configuration property ending in one of those suffixes as well. + +To resolve this ambiguity, and any potential ambiguity involving SPI and provider names, a new SPI option format was introduced where the scopes and suffix are separated by -- instead of -. + +An SPI property ending in -enabled, -provider-default, or -provider will only be treated as buildtime if it is using the new format, e.g. `spi-----enabled` will be recognized as a buildtime option. +Options using the legacy format and ending in ending in -enabled, -provider-default, or -provider will instead be treated as runtime and a warning will be emitted. + == Notable changes Notable changes where an internal behavior changed to prevent common misconfigurations, fix bugs or simplify running {project_name}. diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/Picocli.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/Picocli.java index c68c5778871f..e55a3427b0b0 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/Picocli.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/Picocli.java @@ -38,6 +38,7 @@ import java.util.EnumMap; import java.util.HashSet; import java.util.LinkedHashMap; +import java.util.LinkedHashSet; import java.util.List; import java.util.Map; import java.util.Optional; @@ -377,10 +378,11 @@ && isUserModifiable(Configuration.getConfigValue(key)) DisabledMappersInterceptor.disable(); // we want all properties, even disabled ones final List ignoredRunTime = new ArrayList<>(); - final Set disabledBuildTime = new HashSet<>(); - final Set disabledRunTime = new HashSet<>(); - final Set deprecatedInUse = new HashSet<>(); - final Set missingOption = new HashSet<>(); + final Set disabledBuildTime = new LinkedHashSet<>(); + final Set disabledRunTime = new LinkedHashSet<>(); + final Set deprecatedInUse = new LinkedHashSet<>(); + final Set missingOption = new LinkedHashSet<>(); + final Set ambiguousSpi = new LinkedHashSet<>(); final LinkedHashMap secondClassOptions = new LinkedHashMap<>(); final Set> disabledMappers = new HashSet<>(); @@ -402,6 +404,9 @@ && isUserModifiable(Configuration.getConfigValue(key)) if (!options.includeRuntime) { checkRuntimeSpiOptions(name, ignoredRunTime); } + if (PropertyMappers.isMaybeSpiBuildTimeProperty(name)) { + ambiguousSpi.add(name); + } PropertyMapper mapper = PropertyMappers.getMapper(name); if (mapper == null) { return; // TODO: need to look for disabled Wildcard mappers @@ -460,7 +465,9 @@ && isUserModifiable(Configuration.getConfigValue(key)) if (!deprecatedInUse.isEmpty()) { warn("The following used options or option values are DEPRECATED and will be removed or their behaviour changed in a future release:\n" + String.join("\n", deprecatedInUse) + "\nConsult the Release Notes for details.", getOutWriter()); } - + if (!ambiguousSpi.isEmpty()) { + warn("The following spi options are using the legacy format and are not being treated as build time options. Please use the new format with the appropriate -- separators to resolve this ambiguity:" + String.join("\n", ambiguousSpi)); + } secondClassOptions.forEach((key, firstClass) -> { warn("Please use the first-class option `%s` instead of `%s`".formatted(firstClass, key), getOutWriter()); }); diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/PropertyMappers.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/PropertyMappers.java index 804a1e8716e5..4a673f93bab4 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/PropertyMappers.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/PropertyMappers.java @@ -100,6 +100,10 @@ public static boolean isSpiBuildTimeProperty(String name) { return name.startsWith(KC_SPI_PREFIX) && (name.endsWith("--provider") || name.endsWith("--enabled") || name.endsWith("--provider-default")); } + public static boolean isMaybeSpiBuildTimeProperty(String name) { + return name.startsWith(KC_SPI_PREFIX) && (name.endsWith("-provider") || name.endsWith("-enabled") || name.endsWith("-provider-default") && !name.contains("--")); + } + private static boolean isKeycloakRuntime(String name, PropertyMapper mapper) { if (mapper == null) { return name.startsWith(MicroProfileConfigProvider.NS_KEYCLOAK) && !isSpiBuildTimeProperty(name); diff --git a/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/cli/PicocliTest.java b/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/cli/PicocliTest.java index e9086393c07a..fb688ef99705 100644 --- a/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/cli/PicocliTest.java +++ b/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/cli/PicocliTest.java @@ -610,6 +610,13 @@ public void derivedPropertyUsage() { assertThat(nonRunningPicocli.getOutString(), containsString("Please use the first-class option `kc.hostname` instead of `kc.spi-hostname-v2-hostname`")); } + @Test + public void testAmbiguousSpiOption() { + NonRunningPicocli nonRunningPicocli = pseudoLaunch("start-dev", "--spi-x-y-enabled=true"); + assertEquals(CommandLine.ExitCode.OK, nonRunningPicocli.exitCode); + assertThat(nonRunningPicocli.getOutString(), containsString("WARNING: The following spi options are using the legacy format and are not being treated as build time options. Please use the new format with the appropriate -- separators to resolve this ambiguity:kc.spi-x-y-enabled")); + } + @Test public void testDerivedShowConfig() { NonRunningPicocli nonRunningPicocli = build("build", "--metrics-enabled=true", "--features=user-event-metrics", "--event-metrics-user-enabled=true", "--db=dev-file"); From ae57e3188cc886e91aaf149b92440bf4671c4703 Mon Sep 17 00:00:00 2001 From: Steve Hawkins Date: Tue, 3 Jun 2025 08:00:43 -0400 Subject: [PATCH 3/7] updating docs to the new format Signed-off-by: Steve Hawkins # Conflicts: # docs/guides/high-availability/examples/generated/keycloak-ispn.yaml # docs/guides/high-availability/examples/generated/keycloak.yaml --- .../topics/authentication/password-policies.adoc | 6 +++--- .../server_admin/topics/events/admin.adoc | 4 ++-- .../server_admin/topics/events/login.adoc | 8 ++++---- .../roles-groups/proc-managing-groups.adoc | 4 ++-- .../server_admin/topics/sessions/offline.adoc | 4 ++-- .../sso-protocols/con-oidc-auth-flows.adoc | 2 +- .../server_admin/topics/sso-protocols/oidc.adoc | 2 +- .../topics/threat/auth-sessions-limit.adoc | 4 ++-- .../topics/threat/read-only-attributes.adoc | 4 ++-- .../documentation/server_admin/topics/vault.adoc | 2 +- .../server_development/topics/providers.adoc | 6 +++--- .../server_development/topics/themes.adoc | 6 +++--- .../topics/user-storage/simple-example.adoc | 2 +- .../upgrading/topics/migrate_db.adoc | 6 +++--- .../metrics-for-troubleshooting-keycloak.adoc | 2 +- docs/guides/operator/advanced-configuration.adoc | 4 ++-- docs/guides/server/configuration.adoc | 4 ++-- docs/guides/server/db.adoc | 8 ++++---- docs/guides/server/fips.adoc | 4 ++-- docs/guides/server/outgoinghttp.adoc | 4 ++-- docs/guides/server/reverseproxy.adoc | 16 ++++++++-------- 21 files changed, 51 insertions(+), 51 deletions(-) diff --git a/docs/documentation/server_admin/topics/authentication/password-policies.adoc b/docs/documentation/server_admin/topics/authentication/password-policies.adoc index e72dfba5cdf1..5e3589d0ae32 100644 --- a/docs/documentation/server_admin/topics/authentication/password-policies.adoc +++ b/docs/documentation/server_admin/topics/authentication/password-policies.adoc @@ -51,7 +51,7 @@ Supported password hashing algorithms are shown in the following table. It is highly recommended to use Argon2 when possible as it has significantly less CPU requirements compared to PBKDF2, while at the same time being more secure. -The default password hashing algorithm for the server can be configured with `--spi-password-hashing-provider-default=`. +The default password hashing algorithm for the server can be configured with `--spi-password-hashing--provider-default=`. To prevent excessive memory and CPU usage, the parallel computation of hashes by Argon2 is by default limited to the number of cores available to the JVM. To configure the Argon2 hashing provider, use its provider options. @@ -141,14 +141,14 @@ Password must not be in a blacklist file. * The value of the blacklist file must be the name of the blacklist file, for example, `100k_passwords.txt`. * Blacklist files resolve against `+${kc.home.dir}/data/password-blacklists/+` by default. Customize this path using: ** The `keycloak.password.blacklists.path` system property. -** The `blacklistsPath` property of the `passwordBlacklist` policy SPI configuration. To configure the blacklist folder using the CLI, use `--spi-password-policy-password-blacklist-blacklists-path=/path/to/blacklistsFolder`. +** The `blacklistsPath` property of the `passwordBlacklist` policy SPI configuration. To configure the blacklist folder using the CLI, use `--spi-password-policy--password-blacklist--blacklists-path=/path/to/blacklistsFolder`. .A note about False Positives The current implementation uses a BloomFilter for fast and memory efficient containment checks, such as whether a given password is contained in a blacklist, with the possibility for false positives. * By default a false positive probability of `0.01%` is used. -* To change the false positive probability by CLI configuration, use `--spi-password-policy-password-blacklist-false-positive-probability=0.00001`. +* To change the false positive probability by CLI configuration, use `--spi-password-policy--password-blacklist--false-positive-probability=0.00001`. [[maximum-authentication-age]] ===== Maximum Authentication Age diff --git a/docs/documentation/server_admin/topics/events/admin.adoc b/docs/documentation/server_admin/topics/events/admin.adoc index 73fc84912d86..0461946e3c7d 100644 --- a/docs/documentation/server_admin/topics/events/admin.adoc +++ b/docs/documentation/server_admin/topics/events/admin.adoc @@ -35,9 +35,9 @@ You can now view admin events. .Admin events image:images/admin-events.png[Admin events] -When the `Include Representation` switch is ON, it can lead to storing a lot of information in the database. You can set a maximum length of the representation by using the `--spi-events-store-jpa-max-field-length` argument. This setting is useful if you want to adhere to the underlying storage limitation. For example: +When the `Include Representation` switch is ON, it can lead to storing a lot of information in the database. You can set a maximum length of the representation by using the `--spi-events-store--jpa--max-field-length` argument. This setting is useful if you want to adhere to the underlying storage limitation. For example: [source,bash] ---- -kc.[sh|bat] --spi-events-store-jpa-max-field-length=2500 +kc.[sh|bat] --spi-events-store--jpa--max-field-length=2500 ---- \ No newline at end of file diff --git a/docs/documentation/server_admin/topics/events/login.adoc b/docs/documentation/server_admin/topics/events/login.adoc index 31038f85bd01..0d6762ed59b5 100644 --- a/docs/documentation/server_admin/topics/events/login.adoc +++ b/docs/documentation/server_admin/topics/events/login.adoc @@ -184,7 +184,7 @@ To change the log level used by the Logging Event listener, add the following: [source,bash] ---- -bin/kc.[sh|bat] start --spi-events-listener-jboss-logging-success-level=info --spi-events-listener-jboss-logging-error-level=error +bin/kc.[sh|bat] start --spi-events-listener-jboss-logging-success-level=info --spi-events-listener--jboss-logging--error-level=error ---- The valid values for log levels are `debug`, `info`, `warn`, `error`, and `fatal`. @@ -226,15 +226,15 @@ To enable the Email Listener: .Event listeners image:images/event-listeners.png[Event listeners] -You can exclude events by using the `--spi-events-listener-email-exclude-events` argument. For example: +You can exclude events by using the `--spi-events-listener--email--exclude-events` argument. For example: [source,bash] ---- -kc.[sh|bat] --spi-events-listener-email-exclude-events=UPDATE_CREDENTIAL,REMOVE_CREDENTIAL +kc.[sh|bat] --spi-events-listener--email--exclude-events=UPDATE_CREDENTIAL,REMOVE_CREDENTIAL ---- To enable optional events, use the following command: [source,bash] ---- -kc.[sh|bat] --spi-events-listener-email-include-events=USER_DISABLED_BY_TEMPORARY_LOCKOUT_ERROR,USER_DISABLED_BY_PERMANENT_LOCKOUT +kc.[sh|bat] --spi-events-listener--email--include-events=USER_DISABLED_BY_TEMPORARY_LOCKOUT_ERROR,USER_DISABLED_BY_PERMANENT_LOCKOUT ---- diff --git a/docs/documentation/server_admin/topics/roles-groups/proc-managing-groups.adoc b/docs/documentation/server_admin/topics/roles-groups/proc-managing-groups.adoc index 662271fb11e3..7a5867a51be9 100644 --- a/docs/documentation/server_admin/topics/roles-groups/proc-managing-groups.adoc +++ b/docs/documentation/server_admin/topics/roles-groups/proc-managing-groups.adoc @@ -14,11 +14,11 @@ If you have a parent group and a child group, and a user that belongs only to th The hierarchy of a group is sometimes represented using the group path. The path is the complete list of names that represents the hierarchy of a specific group, from top to bottom and separated by slashes `/` (similar to files in a File System). For example a path can be `/top/level1/level2` which means that `top` is a top level group and is parent of `level1`, which in turn is parent of `level2`. This path represents unambiguously the hierarchy for the group `level2`. -Because of historical reasons {project_name}, does not escape slashes in the group name itself. Therefore a group named `level1/group` under `top` uses the path `/top/level1/group`, which is misleading. {project_name} can be started with the option `--spi-group-jpa-escape-slashes-in-group-path` to `true` and then the slashes in the name are escaped with the character `~`. The escape char marks that the slash is part of the name and has no hierarchical meaning. The previous path example would be `/top/level1~/group` when escaped. +Because of historical reasons {project_name}, does not escape slashes in the group name itself. Therefore a group named `level1/group` under `top` uses the path `/top/level1/group`, which is misleading. {project_name} can be started with the option `--spi-group--jpa--escape-slashes-in-group-path` to `true` and then the slashes in the name are escaped with the character `~`. The escape char marks that the slash is part of the name and has no hierarchical meaning. The previous path example would be `/top/level1~/group` when escaped. [source,bash] ---- -bin/kc.[sh|bat] start --spi-group-jpa-escape-slashes-in-group-path=true +bin/kc.[sh|bat] start --spi-group--jpa--escape-slashes-in-group-path=true ---- The following example includes a top-level *Sales* group and a child *North America* subgroup. diff --git a/docs/documentation/server_admin/topics/sessions/offline.adoc b/docs/documentation/server_admin/topics/sessions/offline.adoc index f023cbb947ac..67732408db24 100644 --- a/docs/documentation/server_admin/topics/sessions/offline.adoc +++ b/docs/documentation/server_admin/topics/sessions/offline.adoc @@ -32,12 +32,12 @@ To specify the lifespan override for offline user sessions, start {project_name} [source,bash] ---- ---spi-user-sessions-infinispan-offline-session-cache-entry-lifespan-override= +--spi-user-sessions--infinispan--offline-session-cache-entry-lifespan-override= ---- Similarly for offline client sessions: [source,bash] ---- ---spi-user-sessions-infinispan-offline-client-session-cache-entry-lifespan-override= +--spi-user-sessions--infinispan--offline-client-session-cache-entry-lifespan-override= ---- diff --git a/docs/documentation/server_admin/topics/sso-protocols/con-oidc-auth-flows.adoc b/docs/documentation/server_admin/topics/sso-protocols/con-oidc-auth-flows.adoc index 5b2978d4db2a..076632f810cf 100644 --- a/docs/documentation/server_admin/topics/sso-protocols/con-oidc-auth-flows.adoc +++ b/docs/documentation/server_admin/topics/sso-protocols/con-oidc-auth-flows.adoc @@ -154,7 +154,7 @@ The CIBA grant uses the following two providers. [source,bash,subs="attributes+"] ---- -kc.[sh|bat] start --spi-ciba-auth-channel-ciba-http-auth-channel-http-authentication-channel-uri=https://backend.internal.example.com{kc_base_path} +kc.[sh|bat] start --spi-ciba-auth-channel--ciba-http-auth-channel--http-authentication-channel-uri=https://backend.internal.example.com{kc_base_path} ---- The configurable items and their description follow. diff --git a/docs/documentation/server_admin/topics/sso-protocols/oidc.adoc b/docs/documentation/server_admin/topics/sso-protocols/oidc.adoc index 309860596ad8..177b1daf65ce 100644 --- a/docs/documentation/server_admin/topics/sso-protocols/oidc.adoc +++ b/docs/documentation/server_admin/topics/sso-protocols/oidc.adoc @@ -157,7 +157,7 @@ The CIBA grant uses the following two providers. [source,bash,subs="attributes+"] ---- -kc.[sh|bat] start --spi-ciba-auth-channel-ciba-http-auth-channel-http-authentication-channel-uri=https://backend.internal.example.com{kc_base_path} +kc.[sh|bat] start --spi-ciba-auth-channel--ciba-http-auth-channel--http-authentication-channel-uri=https://backend.internal.example.com{kc_base_path} ---- The configurable items and their description follow. diff --git a/docs/documentation/server_admin/topics/threat/auth-sessions-limit.adoc b/docs/documentation/server_admin/topics/threat/auth-sessions-limit.adoc index c76dc72143f0..a7e1d4621aac 100644 --- a/docs/documentation/server_admin/topics/threat/auth-sessions-limit.adoc +++ b/docs/documentation/server_admin/topics/threat/auth-sessions-limit.adoc @@ -25,7 +25,7 @@ The following example shows how to limit the number of active `AuthenticationSes [source,bash] ---- -bin/kc.[sh|bat] start --spi-authentication-sessions-infinispan-auth-sessions-limit=100 +bin/kc.[sh|bat] start --spi-authentication-sessions--infinispan--auth-sessions-limit=100 ---- ifeval::[{project_community}==true] @@ -33,6 +33,6 @@ The equivalent command for the new map storage: [source,bash] ---- -bin/kc.[sh|bat] start --spi-authentication-sessions-map-auth-sessions-limit=100 +bin/kc.[sh|bat] start --spi-authentication-sessions--map--auth-sessions-limit=100 ---- endif::[] diff --git a/docs/documentation/server_admin/topics/threat/read-only-attributes.adoc b/docs/documentation/server_admin/topics/threat/read-only-attributes.adoc index ef762efd2598..e6c7de36b32a 100644 --- a/docs/documentation/server_admin/topics/threat/read-only-attributes.adoc +++ b/docs/documentation/server_admin/topics/threat/read-only-attributes.adoc @@ -29,11 +29,11 @@ This is the list of the read-only attributes, which are used internally by the { System administrators have a way to add additional attributes to this list. The configuration is currently available at the server level. -You can add this configuration by using the `spi-user-profile-declarative-user-profile-read-only-attributes` and `spi-user-profile-declarative-user-profile-admin-read-only-attributes` options. For example: +You can add this configuration by using the `spi-user-profile--declarative-user-profile--read-only-attributes` and `spi-user-profile--declarative-user-profile--admin-read-only-attributes` options. For example: [source,bash,options="nowrap"] ---- -kc.[sh|bat] start --spi-user-profile-declarative-user-profile-read-only-attributes=foo,bar* +kc.[sh|bat] start --spi-user-profile--declarative-user-profile--read-only-attributes=foo,bar* ---- For this example, users and administrators would not be able to update attribute `foo`. Users would not be able to edit any attributes starting with the `bar`. diff --git a/docs/documentation/server_admin/topics/vault.adoc b/docs/documentation/server_admin/topics/vault.adoc index b6b63404e51d..83e21b06c742 100644 --- a/docs/documentation/server_admin/topics/vault.adoc +++ b/docs/documentation/server_admin/topics/vault.adoc @@ -33,7 +33,7 @@ All built-in providers support the configuration of key resolvers. A key resolve [source,bash] ---- -kc.[sh|bat] start --spi-vault-file-key-resolvers=REALM_UNDERSCORE_KEY,KEY_ONLY +kc.[sh|bat] start --spi-vault--file--key-resolvers=REALM_UNDERSCORE_KEY,KEY_ONLY ---- The resolvers run in the same order you declare them in the configuration. For each resolver, {project_name} uses the last entry name the resolver produces, which combines the realm with the vault key to search for the vault's secret. If {project_name} finds a secret, it returns the secret. If not, {project_name} uses the next resolver. This search continues until {project_name} finds a non-empty secret or runs out of resolvers. If {project_name} finds no secret, {project_name} returns an empty secret. diff --git a/docs/documentation/server_development/topics/providers.adoc b/docs/documentation/server_development/topics/providers.adoc index c7b8dbd89464..e5d36452021d 100644 --- a/docs/documentation/server_development/topics/providers.adoc +++ b/docs/documentation/server_development/topics/providers.adoc @@ -91,7 +91,7 @@ For example, to configure a provider you can set options as follows: [source,bash] ---- -bin/kc.[sh|bat] --spi-theme-selector-my-theme-selector-enabled=true --spi-theme-selector-my-theme-selector-theme=my-theme +bin/kc.[sh|bat] --spi-theme-selector--my-theme-selector--enabled=true --spi-theme-selector--my-theme-selector--theme=my-theme ---- Then you can retrieve the config in the `ProviderFactory` init method: @@ -234,7 +234,7 @@ one of them needs to be specified as the default one. For example such as: [source,bash] ---- -bin/kc.[sh|bat] build --spi-hostname-provider=default +bin/kc.[sh|bat] build --spi-hostname--provider=default ---- The value `default` used as the value of `default-provider` must match the ID returned by the `ProviderFactory.getId()` of the particular provider factory implementation. @@ -293,7 +293,7 @@ For example to disable the Infinispan user cache provider use: [source,bash] ---- -bin/kc.[sh|bat] build --spi-user-cache-infinispan-enabled=false +bin/kc.[sh|bat] build --spi-user-cache--infinispan--enabled=false ---- [[_script_providers]] diff --git a/docs/documentation/server_development/topics/themes.adoc b/docs/documentation/server_development/topics/themes.adoc index da45b2432646..fc370ac57ee0 100644 --- a/docs/documentation/server_development/topics/themes.adoc +++ b/docs/documentation/server_development/topics/themes.adoc @@ -32,13 +32,13 @@ NOTE: To set the theme for the `master` Admin Console you need to set the Admin + . To see the changes to the Admin Console refresh the page. -. Change the welcome theme by using the `spi-theme-welcome-theme` option. +. Change the welcome theme by using the `spi-theme--welcome-theme` option. . For example: + [source,bash] ---- -bin/kc.[sh|bat] start --spi-theme-welcome-theme=custom-theme +bin/kc.[sh|bat] start --spi-theme--welcome-theme=custom-theme ---- [[_default-themes]] @@ -74,7 +74,7 @@ restarting {project_name}. + [source,bash] ---- -bin/kc.[sh|bat] start --spi-theme-static-max-age=-1 --spi-theme-cache-themes=false --spi-theme-cache-templates=false +bin/kc.[sh|bat] start --spi-theme--static-max-age=-1 --spi-theme--cache-themes=false --spi-theme-cache--templates=false ---- . Create a directory in the `themes` directory. diff --git a/docs/documentation/server_development/topics/user-storage/simple-example.adoc b/docs/documentation/server_development/topics/user-storage/simple-example.adoc index aef44706d9f3..aa5c70f16f79 100644 --- a/docs/documentation/server_development/topics/user-storage/simple-example.adoc +++ b/docs/documentation/server_development/topics/user-storage/simple-example.adoc @@ -213,7 +213,7 @@ For example, by running the server with the following argument: [source,bash] ---- -kc.[sh|bat] start --spi-storage-readonly-property-file-path=/other-users.properties +kc.[sh|bat] start --spi-storage--readonly-property-file--path=/other-users.properties ---- We can specify the classpath of the user property file instead of hardcoding it. Then you can retrieve the configuration in the `PropertyFileUserStorageProviderFactory.init()`: diff --git a/docs/documentation/upgrading/topics/migrate_db.adoc b/docs/documentation/upgrading/topics/migrate_db.adoc index 737bbf1cbb45..1b5c342eb614 100644 --- a/docs/documentation/upgrading/topics/migrate_db.adoc +++ b/docs/documentation/upgrading/topics/migrate_db.adoc @@ -25,7 +25,7 @@ To change the threshold, set the `index-creation-threshold` property, value for [source,bash] ---- -kc.[sh|bat] start --spi-connections-liquibase-quarkus-index-creation-threshold=300000 +kc.[sh|bat] start --spi-connections-liquibase--quarkus--index-creation-threshold=300000 ---- === Manual relational database migration @@ -35,7 +35,7 @@ default `connections-jpa` provider: [source,bash] ---- -kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-strategy=manual +kc.[sh|bat] start --spi-connections-jpa--quarkus--migration-strategy=manual ---- When you start the server with this configuration, the server checks if the database needs to be migrated. If migration is needed, the required changes are written to the `bin/keycloak-database-update.sql` SQL file. You can review and manually run these commands against the database. @@ -45,7 +45,7 @@ default `connections-jpa` provider: [source,bash] ---- -kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-export=/ +kc.[sh|bat] start --spi-connections-jpa--quarkus--migration-export=/ ---- For further details on how to apply this file to the database, see the documentation for your relational database. diff --git a/docs/guides/observability/metrics-for-troubleshooting-keycloak.adoc b/docs/guides/observability/metrics-for-troubleshooting-keycloak.adoc index 3e129850e18e..2fd4b7416af3 100644 --- a/docs/guides/observability/metrics-for-troubleshooting-keycloak.adoc +++ b/docs/guides/observability/metrics-for-troubleshooting-keycloak.adoc @@ -73,7 +73,7 @@ Possible values: -- ==== -To configure what tags are available provide a comma-separated list of tag names to the following option `spi-credential-keycloak-password-validations-counter-tags`. +To configure what tags are available provide a comma-separated list of tag names to the following option `spi-credential--keycloak-password--validations-counter-tags`. By default, all tags are enabled. The snippet below is an example of a response provided by the metric endpoint: diff --git a/docs/guides/operator/advanced-configuration.adoc b/docs/guides/operator/advanced-configuration.adoc index 953438186d61..faef511f4284 100644 --- a/docs/guides/operator/advanced-configuration.adoc +++ b/docs/guides/operator/advanced-configuration.adoc @@ -91,11 +91,11 @@ metadata: spec: ... additionalOptions: - - name: spi-connections-http-client-default-connection-pool-size + - name: spi-connections-http-client--default--connection-pool-size secret: # Secret reference name: http-client-secret # name of the Secret key: poolSize # name of the Key in the Secret - - name: spi-email-template-mycustomprovider-enabled + - name: spi-email-template--mycustomprovider--enabled value: true # plain text value ---- NOTE: The name format of options defined in this way is identical to the key format of options specified in the configuration file. diff --git a/docs/guides/server/configuration.adoc b/docs/guides/server/configuration.adoc index 5276c549ba82..4fbafae46b22 100644 --- a/docs/guides/server/configuration.adoc +++ b/docs/guides/server/configuration.adoc @@ -281,12 +281,12 @@ You can achieve most optimizations to startup and runtime behavior by using the Some of the realm capabilities allow administrators to reference system variables such as environment variables and system properties when configuring the realm and its components. -By default, {project_name} disallow using system variables but only those explicitly specified through the `spi-admin-allowed-system-variables` configuration +By default, {project_name} disallow using system variables but only those explicitly specified through the `spi-admin--allowed-system-variables` configuration option. This option allows you to specify a comma-separated list of keys that will eventually resolve to values from system variables with the same key. . Start the server and expose a set of system variables to the server runtime + - <@kc.start parameters="--spi-admin-allowed-system-variables=FOO,BAR"/> + <@kc.start parameters="--spi-admin--allowed-system-variables=FOO,BAR"/> In future releases, this capability will be removed in favor of preventing any usage of system variables in the realm configuration. diff --git a/docs/guides/server/db.adoc b/docs/guides/server/db.adoc index 7ce492535b9a..85a93d0744b5 100644 --- a/docs/guides/server/db.adoc +++ b/docs/guides/server/db.adoc @@ -308,7 +308,7 @@ Because cluster nodes can boot concurrently, they take extra time for database a The maximum timeout for this lock is 900 seconds. If a node waits on this lock for more than the timeout, the boot fails. The need to change the default value is unlikely, but you can change it by entering this command: -<@kc.start parameters="--spi-dblock-jpa-lock-wait-timeout 900"/> +<@kc.start parameters="--spi-dblock--jpa--lock-wait-timeout 900"/> == Using Database Vendors with XA transaction support {project_name} uses non-XA transactions and the appropriate database drivers by default. @@ -330,17 +330,17 @@ NOTE: Enabling XA transactions in a containerized environment does not fully sup To setup the JPA migrationStrategy (manual/update/validate) you should setup JPA provider as follows: .Setting the `migration-strategy` for the `quarkus` provider of the `connections-jpa` SPI -<@kc.start parameters="--spi-connections-jpa-quarkus-migration-strategy=manual"/> +<@kc.start parameters="--spi-connections--jpa--quarkus-migration-strategy=manual"/> If you want to get a SQL file for DB initialization, too, you have to add this additional SPI initializeEmpty (true/false): .Setting the `initialize-empty` for the `quarkus` provider of the `connections-jpa` SPI -<@kc.start parameters="--spi-connections-jpa-quarkus-initialize-empty=false"/> +<@kc.start parameters="--spi-connections--jpa--quarkus-initialize-empty=false"/> In the same way the migrationExport to point to a specific file and location: .Setting the `migration-export` for the `quarkus` provider of the `connections-jpa` SPI -<@kc.start parameters="--spi-connections-jpa-quarkus-migration-export=/"/> +<@kc.start parameters="--spi-connections--jpa--quarkus-migration-export=/"/> For more information, check the link:{upgrading_guide_link}#_migrate_db[Migrating the database] documentation. diff --git a/docs/guides/server/fips.adoc b/docs/guides/server/fips.adoc index 02433eeef797..1136f4551935 100644 --- a/docs/guides/server/fips.adoc +++ b/docs/guides/server/fips.adoc @@ -138,14 +138,14 @@ So effectively, you can use an option such as the following when starting the se [source] ---- ---spi-password-hashing-pbkdf2-sha512-max-padding-length=14 +--spi-password-hashing--pbkdf2-sha512--max-padding-length=14 ---- NOTE: Using the option above does not break FIPS compliance. However, note that longer passwords are good practice anyway. For example, passwords auto-generated by modern browsers match this requirement as they are longer than 14 characters. If you want to omit the option for max-padding-length, you can set the password policy to your realms to have passwords at least 14 characters long. NOTE: When you are migrating from {project_name} older than 24, or if you explicitly set the password policy to override the default hashing algorithm, it is possible that some of your users use an older -algorithm like `pbkdf2-sha256`. In this case, consider adding the `--spi-password-hashing-pbkdf2-sha256-max-padding-length=14` option to ensure that users having their passwords hashed with +algorithm like `pbkdf2-sha256`. In this case, consider adding the `--spi-password-hashing--pbkdf2-sha256--max-padding-length=14` option to ensure that users having their passwords hashed with the older `pbkdf2-sha256` can log in because their passwords may be shorter than 14 characters. * RSA keys of 1024 bits do not work (2048 is the minimum). This applies for keys used by the {project_name} realm itself (Realm keys from the `Keys` tab in the admin console), but also client keys and IDP keys diff --git a/docs/guides/server/outgoinghttp.adoc b/docs/guides/server/outgoinghttp.adoc index 86c1bbd86c15..f7642c0ce4c3 100644 --- a/docs/guides/server/outgoinghttp.adoc +++ b/docs/guides/server/outgoinghttp.adoc @@ -17,7 +17,7 @@ to configure a {project_name} Truststore so that {project_name} is able to perfo == Client Configuration Command The HTTP client that {project_name} uses for outgoing communication is highly configurable. To configure the {project_name} outgoing HTTP client, enter this command: -<@kc.start parameters="--spi-connections-http-client-default-="/> +<@kc.start parameters="--spi-connections-http-client--default--="/> The following are the command options: @@ -90,7 +90,7 @@ For example, consider the following regex: You apply a regex-based hostname pattern by entering this command: -<@kc.start parameters="--spi-connections-http-client-default-proxy-mappings=\'.*\\\\.(google|googleapis)\\\\.com;http://www-proxy.acme.com:8080\'"/> +<@kc.start parameters="--spi-connections-http-client--default--proxy-mappings=\'.*\\\\.(google|googleapis)\\\\.com;http://www-proxy.acme.com:8080\'"/> The backslash character `\` is escaped again because micro-profile config is used to parse the array of mappings. diff --git a/docs/guides/server/reverseproxy.adoc b/docs/guides/server/reverseproxy.adoc index 36c310df6655..150ba86761cb 100644 --- a/docs/guides/server/reverseproxy.adoc +++ b/docs/guides/server/reverseproxy.adoc @@ -84,12 +84,12 @@ From this point, it is beneficial if load balancer forwards all the next request The sticky session is not mandatory for the cluster setup, however it is good for performance for the reasons mentioned above. You need to configure your loadbalancer to stick over the AUTH_SESSION_ID cookie. The appropriate procedure to make this change depends on your loadbalancer. -If your proxy supports session affinity without processing cookies from backend nodes, you should set the `spi-sticky-session-encoder-infinispan-should-attach-route` option +If your proxy supports session affinity without processing cookies from backend nodes, you should set the `spi-sticky-session-encoder--infinispan--should-attach-route` option to `false` in order to avoid attaching the node to cookies and just rely on the reverse proxy capabilities. -<@kc.start parameters="--spi-sticky-session-encoder-infinispan-should-attach-route=false"/> +<@kc.start parameters="--spi-sticky-session-encoder--infinispan--should-attach-route=false"/> -By default, the `spi-sticky-session-encoder-infinispan-should-attach-route` option value is `true` so that the node name is attached to +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. == Exposed path recommendations @@ -169,9 +169,9 @@ Client certificate lookup via a proxy header for X.509 authentication is conside and edge TLS termination. * If passthrough is not an option, implement the following security measures: ** Configure your network so that {project_name} is isolated and can accept connections only from the proxy. -** Make sure that the proxy overwrites the header that is configured in `spi-x509cert-lookup--ssl-client-cert` option. -** Pay extra attention to the `spi-x509cert-lookup--trust-proxy-verification` setting. Make sure you enable it only if you can trust your proxy to verify the client certificate. - Setting `spi-x509cert-lookup--trust-proxy-verification=true` without the proxy verifying the client certificate chain will expose {project_name} to security vulnerability +** Make sure that the proxy overwrites the header that is configured in `spi-x509cert-lookup----ssl-client-cert` option. +** Pay extra attention to the `spi-x509cert-lookup----trust-proxy-verification` setting. Make sure you enable it only if you can trust your proxy to verify the client certificate. + Setting `spi-x509cert-lookup----trust-proxy-verification=true` without the proxy verifying the client certificate chain will expose {project_name} to security vulnerability when a forged client certificate can be used for authentication. ==== @@ -194,10 +194,10 @@ The server supports some of the most commons TLS termination proxies such as: To configure how client certificates are retrieved from the requests you need to: .Enable the corresponding proxy provider -<@kc.build parameters="--spi-x509cert-lookup-provider="/> +<@kc.build parameters="--spi-x509cert-lookup--provider="/> .Configure the HTTP headers -<@kc.start parameters="--spi-x509cert-lookup--ssl-client-cert=SSL_CLIENT_CERT --spi-x509cert-lookup--ssl-cert-chain-prefix=CERT_CHAIN --spi-x509cert-lookup--certificate-chain-length=10"/> +<@kc.start parameters="--spi-x509cert-lookup----ssl-client-cert=SSL_CLIENT_CERT --spi-x509cert-lookup----ssl-cert-chain-prefix=CERT_CHAIN --spi-x509cert-lookup--certificate-chain-length=10"/> When configuring the HTTP headers, you need to make sure the values you are using correspond to the name of the headers forwarded by the proxy with the client certificate information. From 8a66bb04ac7889ed54fe77c4dec9832171931dfd Mon Sep 17 00:00:00 2001 From: Steve Hawkins Date: Tue, 3 Jun 2025 11:57:45 -0400 Subject: [PATCH 4/7] internally using the new spi options also adding a deprecation notice Signed-off-by: Steve Hawkins --- .../topics/changes/changes-26_3_0.adoc | 4 ++ .../keycloak/quarkus/runtime/cli/Picocli.java | 2 +- .../MicroProfileConfigProvider.java | 2 +- .../mappers/CachingPropertyMappers.java | 42 ++++++++++--------- .../mappers/EventPropertyMappers.java | 6 +-- .../mappers/ExportPropertyMappers.java | 18 ++++---- .../mappers/HostnameV2PropertyMappers.java | 8 ++-- .../mappers/ImportPropertyMappers.java | 14 +++---- .../mappers/MetricsPropertyMappers.java | 4 +- .../mappers/PropertyMappers.java | 12 +++++- .../mappers/TruststorePropertyMappers.java | 2 +- .../mappers/VaultPropertyMappers.java | 8 ++-- .../src/main/resources/application.properties | 6 +-- .../quarkus/runtime/cli/PicocliTest.java | 2 +- .../configuration/test/ConfigurationTest.java | 9 ++-- 15 files changed, 76 insertions(+), 63 deletions(-) diff --git a/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc b/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc index 64a32407f3aa..7eec25097912 100644 --- a/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc +++ b/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc @@ -2,6 +2,10 @@ Breaking changes are identified as requiring changes from existing users to their configurations. +=== Scope.getPropertyNames deprecated for removal + +The `org.keycloak.Config.Scope.getPropertyNames` method has been deprecated for removal. + === local admin deprecated for removal `UrlType.LOCAL_ADMIN` and the corresponding welcome theme variable `localAdminUrl` have been deprecated for eventual removal. The default welcome resource will now simply mention localhost rather than providing a URL when an admin user has yet to be created. diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/Picocli.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/Picocli.java index e55a3427b0b0..23d530ee1b8b 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/Picocli.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/Picocli.java @@ -466,7 +466,7 @@ && isUserModifiable(Configuration.getConfigValue(key)) warn("The following used options or option values are DEPRECATED and will be removed or their behaviour changed in a future release:\n" + String.join("\n", deprecatedInUse) + "\nConsult the Release Notes for details.", getOutWriter()); } if (!ambiguousSpi.isEmpty()) { - warn("The following spi options are using the legacy format and are not being treated as build time options. Please use the new format with the appropriate -- separators to resolve this ambiguity:" + String.join("\n", ambiguousSpi)); + warn("The following spi options are using the legacy format and are not being treated as build time options. Please use the new format with the appropriate -- separators to resolve this ambiguity: " + String.join("\n", ambiguousSpi)); } secondClassOptions.forEach((key, firstClass) -> { warn("Please use the first-class option `%s` instead of `%s`".formatted(firstClass, key), getOutWriter()); diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/MicroProfileConfigProvider.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/MicroProfileConfigProvider.java index 70732a65e093..8e516dda3120 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/MicroProfileConfigProvider.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/MicroProfileConfigProvider.java @@ -127,7 +127,7 @@ public Config.Scope scope(String... scope) { @Override public Set getPropertyNames() { return StreamSupport.stream(config.getPropertyNames().spliterator(), false) - .filter(key -> key.startsWith(prefix)) + .filter(key -> key.startsWith(separatorPrefix)) .collect(Collectors.toSet()); } diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/CachingPropertyMappers.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/CachingPropertyMappers.java index 319080677701..4cf15fd6c1d1 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/CachingPropertyMappers.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/CachingPropertyMappers.java @@ -40,7 +40,7 @@ public static PropertyMapper[] getClusteringPropertyMappers() { .build(), fromOption(CachingOptions.CACHE_STACK) .isEnabled(CachingPropertyMappers::cacheSetToInfinispan, CACHE_STACK_SET_TO_ISPN) - .to("kc.spi-cache-embedded-default-stack") + .to("kc.spi-cache--embedded--default-stack") .paramLabel("stack") .build(), fromOption(CachingOptions.CACHE_CONFIG_FILE) @@ -49,10 +49,11 @@ public static PropertyMapper[] getClusteringPropertyMappers() { return "cache-local.xml"; } else if (CachingOptions.Mechanism.ispn.name().equals(value)) { return resolveConfigFile("cache-ispn.xml", null); - } else + } else { return null; + } }) - .to("kc.spi-cache-embedded-default-config-file") + .to("kc.spi-cache-embedded--default--config-file") .transformer(CachingPropertyMappers::resolveConfigFile) .validator(s -> { if (!Files.exists(Paths.get(resolveConfigFile(s, null)))) { @@ -62,72 +63,72 @@ public static PropertyMapper[] getClusteringPropertyMappers() { .paramLabel("file") .build(), fromOption(CachingOptions.CACHE_EMBEDDED_MTLS_ENABLED) - .to("kc.spi-jgroups-mtls-default-enabled") + .to("kc.spi-jgroups-mtls--default--enabled") .isEnabled(CachingPropertyMappers::getDefaultMtlsEnabled, "a TCP based cache-stack is used") .build(), fromOption(CachingOptions.CACHE_EMBEDDED_MTLS_KEYSTORE.withRuntimeSpecificDefault(getDefaultKeystorePathValue())) .paramLabel("file") - .to("kc.spi-jgroups-mtls-default-keystore-file") + .to("kc.spi-jgroups-mtls--default--keystore-file") .isEnabled(() -> Configuration.isTrue(CachingOptions.CACHE_EMBEDDED_MTLS_ENABLED), "property '%s' is enabled".formatted(CachingOptions.CACHE_EMBEDDED_MTLS_ENABLED.getKey())) .validator(value -> checkValidKeystore(value, CachingOptions.CACHE_EMBEDDED_MTLS_KEYSTORE, CachingOptions.CACHE_EMBEDDED_MTLS_KEYSTORE_PASSWORD)) .build(), fromOption(CachingOptions.CACHE_EMBEDDED_MTLS_KEYSTORE_PASSWORD) .paramLabel("password") .isMasked(true) - .to("kc.spi-jgroups-mtls-default-keystore-password") + .to("kc.spi-jgroups-mtls--default--keystore-password") .isEnabled(() -> Configuration.isTrue(CachingOptions.CACHE_EMBEDDED_MTLS_ENABLED), "property '%s' is enabled".formatted(CachingOptions.CACHE_EMBEDDED_MTLS_ENABLED.getKey())) .validator(value -> checkOptionPresent(CachingOptions.CACHE_EMBEDDED_MTLS_KEYSTORE_PASSWORD, CachingOptions.CACHE_EMBEDDED_MTLS_KEYSTORE)) .build(), fromOption(CachingOptions.CACHE_EMBEDDED_MTLS_TRUSTSTORE.withRuntimeSpecificDefault(getDefaultTruststorePathValue())) .paramLabel("file") - .to("kc.spi-jgroups-mtls-default-truststore-file") + .to("kc.spi-jgroups-mtls--default--truststore-file") .isEnabled(() -> Configuration.isTrue(CachingOptions.CACHE_EMBEDDED_MTLS_ENABLED), "property '%s' is enabled".formatted(CachingOptions.CACHE_EMBEDDED_MTLS_ENABLED.getKey())) .validator(value -> checkValidKeystore(value, CachingOptions.CACHE_EMBEDDED_MTLS_TRUSTSTORE, CachingOptions.CACHE_EMBEDDED_MTLS_TRUSTSTORE_PASSWORD)) .build(), fromOption(CachingOptions.CACHE_EMBEDDED_MTLS_TRUSTSTORE_PASSWORD) .paramLabel("password") .isMasked(true) - .to("kc.spi-jgroups-mtls-default-truststore-password") + .to("kc.spi-jgroups-mtls--default--truststore-password") .isEnabled(() -> Configuration.isTrue(CachingOptions.CACHE_EMBEDDED_MTLS_ENABLED), "property '%s' is enabled".formatted(CachingOptions.CACHE_EMBEDDED_MTLS_ENABLED.getKey())) .validator(value -> checkOptionPresent(CachingOptions.CACHE_EMBEDDED_MTLS_TRUSTSTORE_PASSWORD, CachingOptions.CACHE_EMBEDDED_MTLS_TRUSTSTORE)) .build(), fromOption(CachingOptions.CACHE_EMBEDDED_MTLS_ROTATION) .paramLabel("days") - .to("kc.spi-jgroups-mtls-default-rotation") + .to("kc.spi-jgroups-mtls--default--rotation") .isEnabled(() -> Configuration.isTrue(CachingOptions.CACHE_EMBEDDED_MTLS_ENABLED), "property '%s' is enabled".formatted(CachingOptions.CACHE_EMBEDDED_MTLS_ENABLED.getKey())) .validator(CachingPropertyMappers::validateCertificateRotationIsPositive) .build(), fromOption(CachingOptions.CACHE_REMOTE_HOST) .paramLabel("hostname") - .to("kc.spi-cache-remote-default-hostname") + .to("kc.spi-cache-remote--default--hostname") .addValidateEnabled(CachingPropertyMappers::isRemoteCacheHostEnabled, MULTI_SITE_OR_EMBEDDED_REMOTE_FEATURE_SET) .isRequired(InfinispanUtils::isRemoteInfinispan, MULTI_SITE_FEATURE_SET) .build(), fromOption(CachingOptions.CACHE_REMOTE_PORT) .isEnabled(CachingPropertyMappers::remoteHostSet, CachingPropertyMappers.REMOTE_HOST_SET) - .to("kc.spi-cache-remote-default-port") + .to("kc.spi-cache-remote--default--port") .paramLabel("port") .build(), fromOption(CachingOptions.CACHE_REMOTE_TLS_ENABLED) .isEnabled(CachingPropertyMappers::remoteHostSet, CachingPropertyMappers.REMOTE_HOST_SET) - .to("kc.spi-cache-remote-default-tls-enabled") + .to("kc.spi-cache-remote--default--tls-enabled") .build(), fromOption(CachingOptions.CACHE_REMOTE_USERNAME) .isEnabled(CachingPropertyMappers::remoteHostSet, CachingPropertyMappers.REMOTE_HOST_SET) - .to("kc.spi-cache-remote-default-username") + .to("kc.spi-cache-remote--default--username") .validator((value) -> validateCachingOptionIsPresent(CachingOptions.CACHE_REMOTE_USERNAME, CachingOptions.CACHE_REMOTE_PASSWORD)) .paramLabel("username") .build(), fromOption(CachingOptions.CACHE_REMOTE_PASSWORD) .isEnabled(CachingPropertyMappers::remoteHostSet, CachingPropertyMappers.REMOTE_HOST_SET) - .to("kc.spi-cache-remote-default-password") + .to("kc.spi-cache-remote--default--password") .validator((value) -> validateCachingOptionIsPresent(CachingOptions.CACHE_REMOTE_PASSWORD, CachingOptions.CACHE_REMOTE_USERNAME)) .paramLabel("password") .isMasked(true) .build(), fromOption(CachingOptions.CACHE_METRICS_HISTOGRAMS_ENABLED) .isEnabled(MetricsPropertyMappers::metricsEnabled, MetricsPropertyMappers.METRICS_ENABLED_MSG) - .to("kc.spi-cache-embedded-default-metrics-histograms-enabled") + .to("kc.spi-cache-embedded--default--metrics-histograms-enabled") .build() ); @@ -135,11 +136,13 @@ public static PropertyMapper[] getClusteringPropertyMappers() { List> mappers = new ArrayList<>(numMappers); mappers.addAll(staticMappers); - for (String cache : CachingOptions.LOCAL_MAX_COUNT_CACHES) + for (String cache : CachingOptions.LOCAL_MAX_COUNT_CACHES) { mappers.add(maxCountOpt(cache, () -> true, "")); + } - for (String cache : CachingOptions.CLUSTERED_MAX_COUNT_CACHES) + for (String cache : CachingOptions.CLUSTERED_MAX_COUNT_CACHES) { mappers.add(maxCountOpt(cache, InfinispanUtils::isEmbeddedInfinispan, "embedded Infinispan clusters configured")); + } return mappers.toArray(new PropertyMapper[0]); } @@ -212,7 +215,7 @@ private static PropertyMapper maxCountOpt(String cacheName, BooleanSupplier i return fromOption(CachingOptions.maxCountOption(cacheName)) .isEnabled(isEnabled, enabledWhen) .paramLabel("max-count") - .to("kc.spi-cache-embedded-default-%s-max-count".formatted(CaseFormat.LOWER_CAMEL.to(CaseFormat.LOWER_HYPHEN, cacheName))) + .to("kc.spi-cache-embedded--default--%s-max-count".formatted(CaseFormat.LOWER_CAMEL.to(CaseFormat.LOWER_HYPHEN, cacheName))) .build(); } @@ -228,8 +231,9 @@ private static void validateCachingOptionIsPresent(Option optionSet, Option option, Option requiredOption) { checkOptionPresent(option, requiredOption); - if (!new File(store).exists()) + if (!new File(store).exists()) { throw new IllegalArgumentException("The '%s' file '%s' does not exist.".formatted(option.getKey(), store)); + } } private static void checkOptionPresent(Option option, Option requiredOption) { diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/EventPropertyMappers.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/EventPropertyMappers.java index 8f0f4de24993..2dcd7ff580f7 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/EventPropertyMappers.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/EventPropertyMappers.java @@ -18,16 +18,16 @@ private EventPropertyMappers(){} public static PropertyMapper[] getMetricsPropertyMappers() { return new PropertyMapper[] { fromOption(USER_EVENT_METRICS_ENABLED) - .to("kc.spi-events-listener-micrometer-user-event-metrics-enabled") + .to("kc.spi-events-listener--micrometer-user-event-metrics--enabled") .isEnabled(EventPropertyMappers::userEventsMetricsEnabled, METRICS_ENABLED_MSG + " and feature " + Profile.Feature.USER_EVENT_METRICS.getKey() + " is enabled") .build(), fromOption(USER_EVENT_METRICS_TAGS) - .to("kc.spi-events-listener-micrometer-user-event-metrics-tags") + .to("kc.spi-events-listener--micrometer-user-event-metrics--tags") .paramLabel("tags") .isEnabled(EventPropertyMappers::userEventsMetricsTags, "user event metrics are enabled") .build(), fromOption(USER_EVENT_METRICS_EVENTS) - .to("kc.spi-events-listener-micrometer-user-event-metrics-events") + .to("kc.spi-events-listener--micrometer-user-event-metrics--events") .paramLabel("events") .isEnabled(EventPropertyMappers::userEventsMetricsTags, "user event metrics are enabled") .build(), diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/ExportPropertyMappers.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/ExportPropertyMappers.java index 3986c9a54e1c..9edbeac248ff 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/ExportPropertyMappers.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/ExportPropertyMappers.java @@ -33,7 +33,7 @@ import static org.keycloak.quarkus.runtime.configuration.mappers.PropertyMapper.fromOption; public final class ExportPropertyMappers { - private static final String EXPORTER_PROPERTY = "kc.spi-export-exporter"; + private static final String EXPORTER_PROPERTY = "kc.spi-export--exporter"; private static final String SINGLE_FILE = "singleFile"; private static final String DIR = "dir"; @@ -48,30 +48,30 @@ public static PropertyMapper[] getMappers() { .paramLabel("file") .build(), fromOption(ExportOptions.FILE) - .to("kc.spi-export-single-file-file") + .to("kc.spi-export--single-file--file") .paramLabel("file") .build(), fromOption(ExportOptions.DIR) - .to("kc.spi-export-dir-dir") + .to("kc.spi-export--dir--dir") .paramLabel("dir") .build(), fromOption(ExportOptions.REALM) - .to("kc.spi-export-single-file-realm-name") + .to("kc.spi-export--single-file--realm-name") .isEnabled(ExportPropertyMappers::isSingleFileProvider) .paramLabel("realm") .build(), fromOption(ExportOptions.REALM) - .to("kc.spi-export-dir-realm-name") + .to("kc.spi-export--dir--realm-name") .isEnabled(ExportPropertyMappers::isDirProvider) .paramLabel("realm") .build(), fromOption(ExportOptions.USERS) - .to("kc.spi-export-dir-users-export-strategy") + .to("kc.spi-export--dir--users-export-strategy") .addValidator(ExportPropertyMappers::validateUsersUsage) .paramLabel("strategy") .build(), fromOption(ExportOptions.USERS_PER_FILE) - .to("kc.spi-export-dir-users-per-file") + .to("kc.spi-export--dir--users-per-file") .isEnabled(ExportPropertyMappers::isDirProvider) .paramLabel("number") .build() @@ -121,8 +121,8 @@ private static String transformExporter(String option, ConfigSourceInterceptorCo return exporter.getValue(); } - var file = Configuration.getOptionalValue("kc.spi-export-single-file-file").map(f -> SINGLE_FILE); - var dir = Configuration.getOptionalValue("kc.spi-export-dir-dir") + var file = Configuration.getOptionalValue("kc.spi-export--single-file--file").map(f -> SINGLE_FILE); + var dir = Configuration.getOptionalValue("kc.spi-export--dir--dir") .or(() -> Configuration.getOptionalValue("kc.dir")) .map(f -> DIR); diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/HostnameV2PropertyMappers.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/HostnameV2PropertyMappers.java index d7b1a45ce81e..a8fb427bdd7c 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/HostnameV2PropertyMappers.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/HostnameV2PropertyMappers.java @@ -27,15 +27,15 @@ private HostnameV2PropertyMappers(){} public static PropertyMapper[] getHostnamePropertyMappers() { return Stream.of( fromOption(HostnameV2Options.HOSTNAME) - .to("kc.spi-hostname-v2-hostname") + .to("kc.spi-hostname--v2--hostname") .paramLabel("hostname|URL"), fromOption(HostnameV2Options.HOSTNAME_ADMIN) - .to("kc.spi-hostname-v2-hostname-admin") + .to("kc.spi-hostname--v2--hostname-admin") .paramLabel("URL"), fromOption(HostnameV2Options.HOSTNAME_BACKCHANNEL_DYNAMIC) - .to("kc.spi-hostname-v2-hostname-backchannel-dynamic"), + .to("kc.spi-hostname--v2--hostname-backchannel-dynamic"), fromOption(HostnameV2Options.HOSTNAME_STRICT) - .to("kc.spi-hostname-v2-hostname-strict"), + .to("kc.spi-hostname--v2--hostname-strict"), fromOption(HostnameV2Options.HOSTNAME_DEBUG) ) .map(b -> b.isEnabled(() -> Profile.isFeatureEnabled(Profile.Feature.HOSTNAME_V2), "hostname:v2 feature is enabled").build()) diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/ImportPropertyMappers.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/ImportPropertyMappers.java index 78d3330b1858..01bd0072d9ff 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/ImportPropertyMappers.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/ImportPropertyMappers.java @@ -31,7 +31,7 @@ import static org.keycloak.quarkus.runtime.configuration.mappers.PropertyMapper.fromOption; public final class ImportPropertyMappers { - private static final String IMPORTER_PROPERTY = "kc.spi-import-importer"; + private static final String IMPORTER_PROPERTY = "kc.spi-import--importer"; private static final String SINGLE_FILE = "singleFile"; private static final String DIR = "dir"; @@ -46,20 +46,20 @@ public static PropertyMapper[] getMappers() { .paramLabel("file") .build(), fromOption(ImportOptions.FILE) - .to("kc.spi-import-single-file-file") + .to("kc.spi-import--single-file--file") .paramLabel("file") .build(), fromOption(ImportOptions.DIR) - .to("kc.spi-import-dir-dir") + .to("kc.spi-import--dir--dir") .paramLabel("dir") .build(), fromOption(ImportOptions.OVERRIDE) - .to("kc.spi-import-single-file-strategy") + .to("kc.spi-import--single-file--strategy") .transformer(ImportPropertyMappers::transformOverride) .isEnabled(ImportPropertyMappers::isSingleFileProvider) .build(), fromOption(ImportOptions.OVERRIDE) - .to("kc.spi-import-dir-strategy") + .to("kc.spi-import--dir--strategy") .transformer(ImportPropertyMappers::transformOverride) .isEnabled(ImportPropertyMappers::isDirProvider) .build(), @@ -107,8 +107,8 @@ private static String transformImporter(String option, ConfigSourceInterceptorCo return importer.getValue(); } - var file = getOptionalValue("kc.spi-import-single-file-file").map(f -> SINGLE_FILE); - var dir = getOptionalValue("kc.spi-import-dir-dir") + var file = getOptionalValue("kc.spi-import--single-file--file").map(f -> SINGLE_FILE); + var dir = getOptionalValue("kc.spi-import--dir--dir") .or(() -> getOptionalValue("kc.dir")) .map(f -> DIR); diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/MetricsPropertyMappers.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/MetricsPropertyMappers.java index 4176cba9bdd3..3dfce14864f9 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/MetricsPropertyMappers.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/MetricsPropertyMappers.java @@ -18,12 +18,12 @@ public static PropertyMapper[] getMetricsPropertyMappers() { .to("quarkus.micrometer.enabled") .build(), fromOption(MetricsOptions.PASSWORD_VALIDATION_COUNTER_ENABLED) - .to("kc.spi-credential-keycloak-password-metrics-enabled") + .to("kc.spi-credential--keycloak-password--metrics-enabled") .isEnabled(MetricsPropertyMappers::metricsEnabled, "metrics are enabled") .build(), fromOption(MetricsOptions.INFINISPAN_METRICS_ENABLED) .mapFrom(MetricsOptions.METRICS_ENABLED) - .to("kc.spi-cache-embedded-default-metrics-enabled") + .to("kc.spi-cache-embedded--default--metrics-enabled") .isEnabled(MetricsPropertyMappers::metricsEnabled, "metrics are enabled") .build() }; diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/PropertyMappers.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/PropertyMappers.java index 4a673f93bab4..3f57e80b3da2 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/PropertyMappers.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/PropertyMappers.java @@ -101,7 +101,7 @@ public static boolean isSpiBuildTimeProperty(String name) { } public static boolean isMaybeSpiBuildTimeProperty(String name) { - return name.startsWith(KC_SPI_PREFIX) && (name.endsWith("-provider") || name.endsWith("-enabled") || name.endsWith("-provider-default") && !name.contains("--")); + return name.startsWith(KC_SPI_PREFIX) && (name.endsWith("-provider") || name.endsWith("-enabled") || name.endsWith("-provider-default")) && !name.contains("--"); } private static boolean isKeycloakRuntime(String name, PropertyMapper mapper) { @@ -403,7 +403,15 @@ private static void sanitizeMappers(Map>> private static void handleMapper(PropertyMapper mapper, BiConsumer> operation) { operation.accept(mapper.getFrom(), mapper); if (!mapper.getFrom().equals(mapper.getTo())) { - operation.accept(mapper.getTo(), mapper); + String to = mapper.getTo(); + operation.accept(to, mapper); + if (to.startsWith(KC_SPI_PREFIX)) { + if (!mapper.getTo().contains("--")) { + throw new IllegalStateException("Mapper should use the new form of the spi option: " + to); + } + String legacyTo = mapper.getTo().replace("--", "-"); + operation.accept(legacyTo, mapper); + } } } } diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/TruststorePropertyMappers.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/TruststorePropertyMappers.java index 3fddf74d5cbe..8f3231a91312 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/TruststorePropertyMappers.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/TruststorePropertyMappers.java @@ -13,7 +13,7 @@ public static PropertyMapper[] getMappers() { .build(), fromOption(TruststoreOptions.HOSTNAME_VERIFICATION_POLICY) .paramLabel(TruststoreOptions.HOSTNAME_VERIFICATION_POLICY.getKey()) - .to("kc.spi-truststore-file-hostname-verification-policy") + .to("kc.spi-truststore--file--hostname-verification-policy") .build(), }; } diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/VaultPropertyMappers.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/VaultPropertyMappers.java index 1cc4d33f574c..7f5abb83e795 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/VaultPropertyMappers.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/VaultPropertyMappers.java @@ -15,19 +15,19 @@ public static PropertyMapper[] getVaultPropertyMappers() { .paramLabel("provider") .build(), fromOption(VaultOptions.VAULT_DIR) - .to("kc.spi-vault-file-dir") + .to("kc.spi-vault--file--dir") .paramLabel("dir") .build(), fromOption(VaultOptions.VAULT_FILE) - .to("kc.spi-vault-keystore-file") + .to("kc.spi-vault--keystore--file") .paramLabel("file") .build(), fromOption(VaultOptions.VAULT_PASS) - .to("kc.spi-vault-keystore-pass") + .to("kc.spi-vault--keystore--pass") .paramLabel("pass") .build(), fromOption(VaultOptions.VAULT_TYPE) - .to("kc.spi-vault-keystore-type") + .to("kc.spi-vault--keystore--type") .paramLabel("type") .build() }; diff --git a/quarkus/runtime/src/main/resources/application.properties b/quarkus/runtime/src/main/resources/application.properties index de8fe5ecce3c..1532430b230b 100644 --- a/quarkus/runtime/src/main/resources/application.properties +++ b/quarkus/runtime/src/main/resources/application.properties @@ -71,9 +71,9 @@ quarkus.http.limits.max-header-size=65535 %dev.kc.http-enabled=true %dev.kc.hostname-strict=false %dev.kc.cache=local -%dev.kc.spi-theme-cache-themes=false -%dev.kc.spi-theme-cache-templates=false -%dev.kc.spi-theme-static-max-age=-1 +%dev.kc.spi-theme--cache-themes=false +%dev.kc.spi-theme--cache-templates=false +%dev.kc.spi-theme--static-max-age=-1 # The default configuration when running in import or export mode %nonserver.kc.http-enabled=true diff --git a/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/cli/PicocliTest.java b/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/cli/PicocliTest.java index fb688ef99705..9979766088c6 100644 --- a/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/cli/PicocliTest.java +++ b/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/cli/PicocliTest.java @@ -614,7 +614,7 @@ public void derivedPropertyUsage() { public void testAmbiguousSpiOption() { NonRunningPicocli nonRunningPicocli = pseudoLaunch("start-dev", "--spi-x-y-enabled=true"); assertEquals(CommandLine.ExitCode.OK, nonRunningPicocli.exitCode); - assertThat(nonRunningPicocli.getOutString(), containsString("WARNING: The following spi options are using the legacy format and are not being treated as build time options. Please use the new format with the appropriate -- separators to resolve this ambiguity:kc.spi-x-y-enabled")); + assertThat(nonRunningPicocli.getOutString(), containsString("The following spi options are using the legacy format and are not being treated as build time options. Please use the new format with the appropriate -- separators to resolve this ambiguity: kc.spi-x-y-enabled")); } @Test diff --git a/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/configuration/test/ConfigurationTest.java b/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/configuration/test/ConfigurationTest.java index f27e0ab3e078..86ea8d65dd87 100644 --- a/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/configuration/test/ConfigurationTest.java +++ b/quarkus/runtime/src/test/java/org/keycloak/quarkus/runtime/configuration/test/ConfigurationTest.java @@ -84,13 +84,13 @@ public void testEnvVarAvailableFromPropertyNames() { Config.Scope config = initConfig("vault", FilesPlainTextVaultProviderFactory.ID); assertEquals("/foo/bar", config.get("dir")); assertTrue(config.getPropertyNames() - .contains("kc.spi-vault-".concat(FilesPlainTextVaultProviderFactory.ID).concat("-dir"))); + .contains("kc.spi-vault--".concat(FilesPlainTextVaultProviderFactory.ID).concat("--dir"))); putEnvVar("KC_VAULT_TYPE", "JKS"); config = initConfig("vault", FilesKeystoreVaultProviderFactory.ID); assertEquals("JKS", config.get("type")); assertTrue(config.getPropertyNames() - .contains("kc.spi-vault-".concat(FilesKeystoreVaultProviderFactory.ID).concat("-type"))); + .contains("kc.spi-vault--".concat(FilesKeystoreVaultProviderFactory.ID).concat("--type"))); } @Test @@ -183,7 +183,6 @@ public void testResolveTransformedValue() { public void testPropertyNamesFromConfig() { ConfigArgsConfigSource.setCliArgs("--spi-client-registration-openid-connect-static-jwk-url=http://c.jwk.url"); Config.Scope config = initConfig("client-registration", "openid-connect"); - assertEquals(1, config.getPropertyNames().size()); assertEquals("http://c.jwk.url", config.get("static-jwk-url")); ConfigArgsConfigSource.setCliArgs("--vault-dir=secrets"); @@ -199,14 +198,12 @@ public void testPropertyNamesFromConfig() { ConfigArgsConfigSource.setCliArgs(); System.setProperty("kc.spi-client-registration-openid-connect-static-jwk-url", "http://c.jwk.url"); config = initConfig("client-registration", "openid-connect"); - assertEquals(1, config.getPropertyNames().size()); assertEquals("http://c.jwk.url", config.get("static-jwk-url")); ConfigArgsConfigSource.setCliArgs(); System.getProperties().remove("kc.spi-client-registration-openid-connect-static-jwk-url"); putEnvVar("KC_SPI_CLIENT_REGISTRATION_OPENID_CONNECT_STATIC_JWK_URL", "http://c.jwk.url/from-env"); config = initConfig("client-registration", "openid-connect"); - assertEquals(1, config.getPropertyNames().size()); assertEquals("http://c.jwk.url/from-env", config.get("static-jwk-url")); } @@ -589,5 +586,5 @@ public void testOverrideDefaultQuarkusPropertiesViaEnv() { private static Config.Scope cacheEmbeddedConfiguration() { return initConfig(CacheEmbeddedConfigProviderSpi.SPI_NAME, DefaultCacheEmbeddedConfigProviderFactory.PROVIDER_ID); - } + } } From 78aef869f898a1878470679b4f4257052f84b6ad Mon Sep 17 00:00:00 2001 From: Steven Hawkins Date: Tue, 10 Jun 2025 08:59:17 -0400 Subject: [PATCH 5/7] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Martin Bartoš Signed-off-by: Steven Hawkins --- core/src/main/java/org/keycloak/Config.java | 5 ++++- .../upgrading/topics/changes/changes-26_3_0.adoc | 11 +++++++---- .../configuration/mappers/PropertyMappers.java | 2 +- 3 files changed, 12 insertions(+), 6 deletions(-) diff --git a/core/src/main/java/org/keycloak/Config.java b/core/src/main/java/org/keycloak/Config.java index 128980cbcda1..538f571a85cb 100755 --- a/core/src/main/java/org/keycloak/Config.java +++ b/core/src/main/java/org/keycloak/Config.java @@ -236,7 +236,10 @@ public static interface Scope { Scope scope(String... scope); /** - * @deprecated to be removed + * @deprecated since 26.3.0, to be removed + * + *
Was introduced for testing purposes and was not fully / correctly implements + * across Scope implementations */ @Deprecated Set getPropertyNames(); diff --git a/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc b/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc index 7eec25097912..22357aa695a6 100644 --- a/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc +++ b/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc @@ -86,12 +86,15 @@ status on federated user accounts depending on the use cases and the demand from === Buildtime SPI Options -SPI options ending in -enabled, -provider-default, or -provider were previously treated as buildtime. However in some instances this was not correct as a provider could have a configuration property ending in one of those suffixes as well. +SPI options ending in `-enabled`, `-provider-default`, or `-provider` were previously treated as buildtime. However in some instances this was not correct as a provider could have a configuration property ending in one of those suffixes as well. -To resolve this ambiguity, and any potential ambiguity involving SPI and provider names, a new SPI option format was introduced where the scopes and suffix are separated by -- instead of -. +To resolve this ambiguity, and any potential ambiguity involving SPI and provider names, a new SPI option format was introduced where the scopes and suffix are separated by `--`(double dash) instead of `-`(dash). -An SPI property ending in -enabled, -provider-default, or -provider will only be treated as buildtime if it is using the new format, e.g. `spi-----enabled` will be recognized as a buildtime option. -Options using the legacy format and ending in ending in -enabled, -provider-default, or -provider will instead be treated as runtime and a warning will be emitted. +An SPI property ending in `-enabled`, `-provider-default`, or `-provider` will only be treated as buildtime if it is using the new format, e.g. `spi-----enabled` will be recognized as a buildtime option. + +For instance, the correct way to reference your custom email template is: `--spi-email-template--mycustomprovider--enabled` (not `--spi-email-template-mycustomprovider-enabled`). + +Options using the legacy format and ending in `-enabled`, `-provider-default`, or `-provider` will instead be treated as runtime and a warning will be emitted. == Notable changes diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/PropertyMappers.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/PropertyMappers.java index 3f57e80b3da2..cab6d42b0b27 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/PropertyMappers.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/PropertyMappers.java @@ -407,7 +407,7 @@ private static void handleMapper(PropertyMapper mapper, BiConsumer Date: Wed, 11 Jun 2025 08:52:23 -0400 Subject: [PATCH 6/7] correcting options output adding + + inlining where needed Signed-off-by: Steve Hawkins --- docs/guides/server/configuration.adoc | 2 +- docs/guides/server/fips.adoc | 2 +- docs/guides/server/reverseproxy.adoc | 6 ++--- docs/guides/templates/options.adoc | 6 ++--- docs/guides/ui-customization/themes.adoc | 6 ++--- .../ui-customization/welcome-theme.adoc | 4 ++-- .../org/keycloak/guides/maven/Options.java | 22 ++++++++++--------- 7 files changed, 25 insertions(+), 23 deletions(-) diff --git a/docs/guides/server/configuration.adoc b/docs/guides/server/configuration.adoc index 4fbafae46b22..5c74a27d4d3e 100644 --- a/docs/guides/server/configuration.adoc +++ b/docs/guides/server/configuration.adoc @@ -281,7 +281,7 @@ You can achieve most optimizations to startup and runtime behavior by using the Some of the realm capabilities allow administrators to reference system variables such as environment variables and system properties when configuring the realm and its components. -By default, {project_name} disallow using system variables but only those explicitly specified through the `spi-admin--allowed-system-variables` configuration +By default, {project_name} disallow using system variables but only those explicitly specified through the `+spi-admin--allowed-system-variables+` configuration option. This option allows you to specify a comma-separated list of keys that will eventually resolve to values from system variables with the same key. . Start the server and expose a set of system variables to the server runtime diff --git a/docs/guides/server/fips.adoc b/docs/guides/server/fips.adoc index 1136f4551935..44606cde0dbb 100644 --- a/docs/guides/server/fips.adoc +++ b/docs/guides/server/fips.adoc @@ -145,7 +145,7 @@ NOTE: Using the option above does not break FIPS compliance. However, note that requirement as they are longer than 14 characters. If you want to omit the option for max-padding-length, you can set the password policy to your realms to have passwords at least 14 characters long. NOTE: When you are migrating from {project_name} older than 24, or if you explicitly set the password policy to override the default hashing algorithm, it is possible that some of your users use an older -algorithm like `pbkdf2-sha256`. In this case, consider adding the `--spi-password-hashing--pbkdf2-sha256--max-padding-length=14` option to ensure that users having their passwords hashed with +algorithm like `pbkdf2-sha256`. In this case, consider adding the `+--spi-password-hashing--pbkdf2-sha256--max-padding-length=14+` option to ensure that users having their passwords hashed with the older `pbkdf2-sha256` can log in because their passwords may be shorter than 14 characters. * RSA keys of 1024 bits do not work (2048 is the minimum). This applies for keys used by the {project_name} realm itself (Realm keys from the `Keys` tab in the admin console), but also client keys and IDP keys diff --git a/docs/guides/server/reverseproxy.adoc b/docs/guides/server/reverseproxy.adoc index 150ba86761cb..71978efa1be7 100644 --- a/docs/guides/server/reverseproxy.adoc +++ b/docs/guides/server/reverseproxy.adoc @@ -84,12 +84,12 @@ From this point, it is beneficial if load balancer forwards all the next request The sticky session is not mandatory for the cluster setup, however it is good for performance for the reasons mentioned above. You need to configure your loadbalancer to stick over the AUTH_SESSION_ID cookie. The appropriate procedure to make this change depends on your loadbalancer. -If your proxy supports session affinity without processing cookies from backend nodes, you should set the `spi-sticky-session-encoder--infinispan--should-attach-route` option +If your proxy supports session affinity without processing cookies from backend nodes, you should set the `+spi-sticky-session-encoder--infinispan--should-attach-route+` option to `false` in order to avoid attaching the node to cookies and just rely on the reverse proxy capabilities. <@kc.start parameters="--spi-sticky-session-encoder--infinispan--should-attach-route=false"/> -By default, the `spi-sticky-session-encoder--infinispan--should-attach-route` option value is `true` so that the node name is attached to +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. == Exposed path recommendations @@ -197,7 +197,7 @@ To configure how client certificates are retrieved from the requests you need to <@kc.build parameters="--spi-x509cert-lookup--provider="/> .Configure the HTTP headers -<@kc.start parameters="--spi-x509cert-lookup----ssl-client-cert=SSL_CLIENT_CERT --spi-x509cert-lookup----ssl-cert-chain-prefix=CERT_CHAIN --spi-x509cert-lookup--certificate-chain-length=10"/> +<@kc.start parameters="--spi-x509cert-lookup----ssl-client-cert=SSL_CLIENT_CERT --spi-x509cert-lookup----ssl-cert-chain-prefix=CERT_CHAIN --spi-x509cert-lookup---certificate-chain-length=10"/> When configuring the HTTP headers, you need to make sure the values you are using correspond to the name of the headers forwarded by the proxy with the client certificate information. diff --git a/docs/guides/templates/options.adoc b/docs/guides/templates/options.adoc index f531923e8260..e53dbd5f768a 100644 --- a/docs/guides/templates/options.adoc +++ b/docs/guides/templates/options.adoc @@ -23,7 +23,7 @@ <#list options as option> | -[.options-key]#``${option.key}``# <#if buildIcon><#if option.build>[.none]#icon:tools[role=options-build]# +[.options-key]#`+${option.key}+`# <#if buildIcon><#if option.build>[.none]#icon:tools[role=options-build]# [.options-description]#${option.description}# @@ -31,8 +31,8 @@ -- <#if option.descriptionExtended?has_content>[.options-description-extended]#${option.descriptionExtended!}# -*CLI:* `${option.keyCli}` + -*Env:* `${option.keyEnv}` +*CLI:* `+${option.keyCli}+` + +*Env:* `+${option.keyEnv}+` -- <#if option.enabledWhen?has_content> diff --git a/docs/guides/ui-customization/themes.adoc b/docs/guides/ui-customization/themes.adoc index 5231885847dc..2512934318ce 100644 --- a/docs/guides/ui-customization/themes.adoc +++ b/docs/guides/ui-customization/themes.adoc @@ -36,13 +36,13 @@ NOTE: To set the theme for the `master` Admin Console you need to set the Admin + . To see the changes to the Admin Console refresh the page. -. Change the welcome theme by using the `spi-theme-welcome-theme` option. +. Change the welcome theme by using the `spi-theme--welcome-theme` option. . For example: + [source,bash] ---- -bin/kc.[sh|bat] start --spi-theme-welcome-theme=custom-theme +bin/kc.[sh|bat] start --spi-theme--welcome-theme=custom-theme ---- [[_default-themes]] @@ -79,7 +79,7 @@ restarting {project_name}. + [source,bash] ---- -bin/kc.[sh|bat] start --spi-theme-static-max-age=-1 --spi-theme-cache-themes=false --spi-theme-cache-templates=false +bin/kc.[sh|bat] start --spi-theme-static-max-age=-1 --spi-theme-cache-themes=false --spi-theme--cache-templates=false ---- . Create a directory in the `themes` directory. diff --git a/docs/guides/ui-customization/welcome-theme.adoc b/docs/guides/ui-customization/welcome-theme.adoc index 40cd61b47135..473fddfe6c2d 100644 --- a/docs/guides/ui-customization/welcome-theme.adoc +++ b/docs/guides/ui-customization/welcome-theme.adoc @@ -12,9 +12,9 @@ By default, the welcome theme is only used to create the initial temporary admin Since the welcome theme is not associated with a realm, it cannot be selected in the admin console like other themes. -To change the welcome theme, create and deploy a new welcome theme as described in <<_creating-a-theme,Creating a theme>>. Then, start the {project_name} server using the `spi-theme-welcome-theme` option. +To change the welcome theme, create and deploy a new welcome theme as described in <<_creating-a-theme,Creating a theme>>. Then, start the {project_name} server using the `spi-theme--welcome-theme` option. [source,bash] ---- -bin/kc.[sh|bat] start --spi-theme-welcome-theme=custom-theme +bin/kc.[sh|bat] start --spi-theme--welcome-theme=custom-theme ---- \ No newline at end of file diff --git a/docs/maven-plugin/src/main/java/org/keycloak/guides/maven/Options.java b/docs/maven-plugin/src/main/java/org/keycloak/guides/maven/Options.java index d699cbbfbc2b..7b19dee199c3 100644 --- a/docs/maven-plugin/src/main/java/org/keycloak/guides/maven/Options.java +++ b/docs/maven-plugin/src/main/java/org/keycloak/guides/maven/Options.java @@ -1,11 +1,9 @@ package org.keycloak.guides.maven; -import static org.aesh.readline.terminal.Key.r; import static org.keycloak.quarkus.runtime.configuration.Configuration.OPTION_PART_SEPARATOR; import static org.keycloak.quarkus.runtime.configuration.Configuration.toDashCase; import static org.keycloak.quarkus.runtime.configuration.MicroProfileConfigProvider.NS_KEYCLOAK_PREFIX; -import org.apache.commons.lang3.ArrayUtils; import org.keycloak.config.ConfigSupportLevel; import org.keycloak.config.DeprecatedMetadata; import org.keycloak.config.OptionCategory; @@ -14,7 +12,6 @@ import org.keycloak.provider.ProviderManager; import org.keycloak.provider.Spi; import org.keycloak.quarkus.runtime.Providers; -import org.keycloak.quarkus.runtime.configuration.Configuration; import org.keycloak.quarkus.runtime.configuration.mappers.PropertyMappers; import org.keycloak.utils.StringUtil; @@ -63,6 +60,10 @@ public Options() { .flatMap(Collection::stream) .forEach(option -> option.description = option.description.replaceAll("'([^ ]*)'", "`$1`")); + ArrayList booleanValues = new ArrayList<>(); + booleanValues.add("true"); + booleanValues.add("false"); + for (Spi loadSpi : providerManager.loadSpis().stream().sorted(Comparator.comparing(Spi::getName)).toList()) { for (ProviderFactory providerFactory : providerManager.load(loadSpi).stream().sorted(Comparator.comparing(ProviderFactory::getId)).toList()) { List configMetadata = providerFactory.getConfigMetadata(); @@ -71,9 +72,11 @@ public Options() { continue; } - String optionPrefix = NS_KEYCLOAK_PREFIX + String.join(OPTION_PART_SEPARATOR, ArrayUtils.insert(0, new String[] {loadSpi.getName(), providerFactory.getId()}, "spi")); + String spiKey = toDashCase(loadSpi.getName()); + String providerKey = toDashCase(providerFactory.getId()); + String optionPrefix = NS_KEYCLOAK_PREFIX + "spi" + OPTION_PART_SEPARATOR + spiKey + OPTION_PART_SEPARATOR + OPTION_PART_SEPARATOR + providerKey + OPTION_PART_SEPARATOR + OPTION_PART_SEPARATOR; List