mabartos · Apr 17, 2026 · Apr 15, 2026 · Apr 15, 2026 · Apr 16, 2026
@@ -118,12 +118,6 @@ public class DatabaseOptions {
             .description("If the named datasource <datasource> should be enabled at runtime.")
             .build();
 
-    public static final Option<String> DB_POSTGRESQL_TARGET_SERVER_TYPE = new OptionBuilder<>("db-postgres-target-server-type", String.class)
-            .category(OptionCategory.DATABASE)
-            .defaultValue("primary") // cause the propertymapping logic to always advertise this property
-            .hidden()
-            .build();
-
     public static final Option<String> DB_CONNECT_TIMEOUT = new OptionBuilder<>("db-connect-timeout", String.class)
             .category(OptionCategory.DATABASE)
             .description("Sets the JDBC driver connection timeout and login timeout. " + DURATION_DESCRIPTION)
@@ -155,10 +149,6 @@ public class DatabaseOptions {
             .description("The type of the truststore file. Common values include 'JKS' (Java KeyStore) and 'PKCS12'. If not specified, it uses the driver's default.")
             .build();
 
-    public static final Option<String> DB_ORACLE_TLS_TRANSPORT = new OptionBuilder<>("db-oracle-protocol", String.class)
-            .hidden()
-            .build();
-
     public static final class Datasources {
         /**
          * Options that have their sibling for a named datasource
@@ -185,8 +175,7 @@ public static final class Datasources {
                 DB_TLS_MODE,
                 DB_TLS_TRUST_STORE_FILE,
                 DB_TLS_TRUST_STORE_PASSWORD,
-                DB_TLS_TRUST_STORE_TYPE,
-                DB_ORACLE_TLS_TRANSPORT
+                DB_TLS_TRUST_STORE_TYPE
         ).map(Option::getKey).toList();
 
         /**

diff --git a/< 8000 span aria-label="Owned by @keycloak/cloud-native-maintainers and @keycloak/maintainers (from CODEOWNERS line 39)" data-view-component="true" class="tooltipped tooltipped-se"> b/< 8000 span aria-label="Owned by @keycloak/cloud-native-maintainers and @keycloak/maintainers (from CODEOWNERS line 39)" data-view-component="true" class="tooltipped tooltipped-se">
@@ -151,7 +151,7 @@ public String toString() {
 
     public static final Option<Boolean> LOG_CONSOLE_ENABLED = new OptionBuilder<>("log-console-enabled", Boolean.class)
             .category(OptionCategory.LOGGING)
-            .hidden()
+            .synthetic()
             .build();
 
     // Console Async
@@ -170,7 +170,7 @@ public String toString() {
     // File
     public static final Option<Boolean> LOG_FILE_ENABLED = new OptionBuilder<>("log-file-enabled", Boolean.class)
             .category(OptionCategory.LOGGING)
-            .hidden()
+            .synthetic()
             .build();
 
     public static final Option<File> LOG_FILE = new OptionBuilder<>("log-file", File.class)
@@ -266,7 +266,7 @@ public String toString() {
     // Syslog
     public static final Option<Boolean> LOG_SYSLOG_ENABLED = new OptionBuilder<>("log-syslog-enabled", Boolean.class)
             .category(OptionCategory.LOGGING)
-            .hidden()
+            .synthetic()
             .build();
 
     public static final Option<String> LOG_SYSLOG_ENDPOINT = new OptionBuilder<>("log-syslog-endpoint", String.class)

@@ -20,32 +20,6 @@ public enum Headers {
             .defaultValue(Boolean.FALSE)
             .build();
 
-    public static final Option<Boolean> PROXY_FORWARDED_HOST = new OptionBuilder<>("proxy-forwarded-host", Boolean.class)
-            .category(OptionCategory.PROXY)
-            .defaultValue(Boolean.FALSE)
-            .build();
-
-    public static final Option<Boolean> PROXY_FORWARDED_HEADER_ENABLED = new OptionBuilder<>("proxy-allow-forwarded-header", Boolean.class)
-            .category(OptionCategory.PROXY)
-            .defaultValue(Boolean.FALSE)
-            .build();
-
-    public static final Option<Boolean> PROXY_X_FORWARDED_HEADER_ENABLED = new OptionBuilder<>("proxy-allow-x-forwarded-header", Boolean.class)
-            .category(OptionCategory.PROXY)
-            .defaultValue(Boolean.FALSE)
-            .build();
-
-    public static final Option<Boolean> PROXY_X_FORWARDED_PREFIX_HEADER_ENABLED = new OptionBuilder<>("proxy-allow-x-forwarded-prefix-header", Boolean.class)
-            .category(OptionCategory.PROXY)
-            .defaultValue(Boolean.FALSE)
-            .build();
-
-    public static final Option<Boolean> PROXY_TRUSTED_HEADER_ENABLED = new OptionBuilder<>("proxy-trusted-header-enabled", Boolean.class)
-            .category(OptionCategory.PROXY)
-            .defaultValue(Boolean.FALSE)
-            .hidden()
-            .build();
-
     public static final Option<List<String>> PROXY_TRUSTED_ADDRESSES = OptionBuilder.listOptionBuilder("proxy-trusted-addresses", String.class)
             .category(OptionCategory.PROXY)
             .description("A comma separated list of trusted proxy addresses. If set, then proxy headers from other addresses will be ignored. By default all addresses are trusted. A trusted proxy address is specified as an IP address (IPv4 or IPv6) or Classless Inter-Domain Routing (CIDR) notation.")

@@ -4,12 +4,6 @@
 
 public class TelemetryOptions {
 
-    public static final Option<Boolean> TELEMETRY_ENABLED = new OptionBuilder<>("telemetry-enabled", Boolean.class)
-            .category(OptionCategory.TELEMETRY)
-            .buildTime(true)
-            .hidden()
-            .build();
-
     public static final Option<String> TELEMETRY_ENDPOINT = new OptionBuilder<>("telemetry-endpoint", String.class)
             .category(OptionCategory.TELEMETRY)
             .description("OpenTelemetry endpoint to connect to.")
@@ -72,8 +66,7 @@ public class TelemetryOptions {
 
     public static final Option<List<String>> TELEMETRY_LOGS_HEADERS = OptionBuilder.listOptionBuilder("telemetry-logs-headers", String.class)
             .category(OptionCategory.TELEMETRY)
-            .hidden()
-            .description("Hidden option for OpenTelemetry headers that will be part of the exporter request. Values in format 'key1=val1,key2=val2'. Overrides the 'telemetry-logs-header-<header>' options.")
+            .synthetic()
             .build();
 
     // Telemetry Metrics
@@ -108,7 +101,6 @@ public class TelemetryOptions {
 
     public static final Option<List<String>> TELEMETRY_METRICS_HEADERS = OptionBuilder.listOptionBuilder("telemetry-metrics-headers", String.class)
             .category(OptionCategory.TELEMETRY)
-            .hidden()
-            .description("Hidden option for OpenTelemetry headers that will be part of the exporter request. Values in format 'key1=val1,key2=val2'. Overrides the 'telemetry-metrics-header-<header>' options.")
+            .synthetic()
             .build();
 }
@@ -112,8 +112,7 @@ public enum TracingCompression {
 
     public static final Option<List<String>> TRACING_HEADERS = OptionBuilder.listOptionBuilder("tracing-headers", String.class)
             .category(OptionCategory.TRACING)
-            .hidden()
-            .description("Hidden option for OpenTelemetry headers that will be part of the exporter request. Values in format 'key1=val1,key2=val2'. Overrides the 'tracing-header-<header>' options.")
+            .synthetic()
             .build();
 
 }
@@ -35,13 +35,6 @@ public class TransactionOptions {
             .defaultValue(MIGRATION_TRANSACTION_TIMEOUT)
             .build();
 
-    public static final Option<String> DB_LOCK_TIMEOUT = new OptionBuilder<>("transaction-db-lock-timeout", String.class)
-            .category(OptionCategory.TRANSACTION)
-            .description("Hidden option to map transaction-setup-timeout to db lock timeout.")
-            .buildTime(false)
-            .hidden()
-            .build();
-
     public static String getNamedTxXADatasource(String namedProperty) {
         if ("<default>".equals(namedProperty)) {
             return TRANSACTION_XA_ENABLED.getKey();

@@ -36,6 +36,8 @@
 import static java.util.Arrays.asList;
 
 public final class Database {
+
+    public final static String ORACLE_URL_PREFIX = "jdbc:oracle:thin:@";
 
     private static final Map<String, Vendor> DATABASES = new HashMap<>();
 
@@ -210,8 +212,7 @@ private String escapeReplacements(String snippet) {
                 "oracle.jdbc.driver.OracleDriver",
                 "org.hibernate.dialect.OracleDialect",
                 // default URL looks like this: "jdbc:oracle:thin:@//${kc.db-url-host:localhost}:${kc.db-url-port:1521}/${kc.db-url-database:keycloak}"
-                (namedProperty, alias) -> "jdbc:oracle:thin:%s//%s:%s/%s".formatted(
-                        getProperty(DatabaseOptions.DB_ORACLE_TLS_TRANSPORT, namedProperty, "@"),
+                (namedProperty, alias) -> ORACLE_URL_PREFIX + "//%s:%s/%s".formatted(
                         getProperty(DatabaseOptions.DB_URL_HOST, namedProperty, "localhost"),
                         getProperty(DatabaseOptions.DB_URL_PORT, namedProperty, "1521"),
                         getProperty(DatabaseOptions.DB_URL_DATABASE, namedProperty, "keycloak")),

@@ -40,7 +40,7 @@ public int handleParseException(ParameterException ex, String[] args) {
 
             final BooleanSupplier isUnknownOption = () -> mapper == null || !(cmd.getCommand() instanceof AbstractCommand);
 
-            if (mapper == null && disabled.isPresent()) {
+            if (mapper == null && disabled.filter(m -> !m.getOption().isHidden()).isPresent()) {
                 var enabledWhen = disabled
                         .flatMap(PropertyMapper::getEnabledWhen)
                         .map(desc -> format(". %s", desc))

@@ -32,7 +32,6 @@
 import org.jboss.logging.Logger;
 
 import static org.keycloak.config.DatabaseOptions.DB;
-import static org.keycloak.config.DatabaseOptions.DB_ORACLE_TLS_TRANSPORT;
 import static org.keycloak.config.DatabaseOptions.DB_POOL_INITIAL_SIZE;
 import static org.keycloak.config.DatabaseOptions.DB_POOL_MAX_SIZE;
 import static org.keycloak.config.DatabaseOptions.DB_TLS_MODE;
@@ -163,8 +162,6 @@ public List<PropertyMapper<?>> getPropertyMappers() {
                 // Database TLS configuration
                 fromOption(DB_TLS_MODE)
                         .paramLabel("mode")
-                        .transformer(DatabasePropertyMappers::transformOracleProtocol)
-                        .to(NS_KEYCLOAK_PREFIX + DB_ORACLE_TLS_TRANSPORT.getKey())
                         .build(),
                 fromOption(DB_TLS_TRUST_STORE_FILE)
                         .paramLabel("path")
@@ -220,7 +217,7 @@ public List<PropertyMapper<?>> getPropertyMappers() {
         // finally add mappers that aren't intended to work with other datasources
         // - also this usage of isEnabled won't work correctly with wildcard mappers
         result.addAll(List.of(
-                fromOption(DatabaseOptions.DB_POSTGRESQL_TARGET_SERVER_TYPE)
+                fromOption(SYNTHETIC_RUNTIME_DB_OPTION).mapFrom(DB, (name, value, context) -> "primary")
                         .to(PG_TARGET_SERVER_TYPE)
                         .isEnabled(DatabasePropertyMappers::isPostgresqlTargetServerTypeEnabled)
                         .build(),
@@ -381,6 +378,11 @@ private static String getDatabaseUrl(String name, String value, ConfigSourceInte
                 url += urlProps;
             }
             url = amendH2(url);
+        } else if (Database.getVendor(value).filter(Vendor.ORACLE::equals).isPresent()) {
+            var tlsMode = getDatabaseTlsMode(name);
+            if (tlsMode != DatabaseOptions.DatabaseTlsMode.DISABLED) {
+                url = Database.ORACLE_URL_PREFIX + "tcps:" + url.substring(Database.ORACLE_URL_PREFIX.length());
+            }
         }
         return url;
     }
@@ -496,11 +498,6 @@ private static String transformDatasourceTo(String to) {
         }
     }
 
-    private static String transformOracleProtocol(String datasource, String value, ConfigSourceInterceptorContext configSourceInterceptorContext) {
-        var tlsMode = DatabaseOptions.DatabaseTlsMode.fromCliValue(value);
-        return tlsMode != DatabaseOptions.DatabaseTlsMode.DISABLED ? "@tcps:" : "@";
-    }
-
     private static PropertyMapper<?> setTlsJdbcProperty(String jdbcPropertyKey, Map<Database.Vendor, String> vendorValues) {
         return fromOption(SYNTHETIC_RUNTIME_DB_OPTION)
                 .mapFrom(DB)

@@ -104,7 +104,7 @@ public void validateConfig(Picocli picocli) {
             .category(OptionCategory.EXPORT)
             .description("Placeholder for determining export mode")
             .buildTime(false)
-            .hidden()
+            .synthetic()
             .build();
 
     private static boolean isSingleFileProvider() {

@@ -82,7 +82,7 @@ public void validateConfig(Picocli picocli) {
             .category(OptionCategory.IMPORT)
             .description("Placeholder for determining import mode")
             .buildTime(false)
-            .hidden()
+            .synthetic()
             .build();
 
     private static boolean isSingleFileProvider() {

@@ -256,7 +256,7 @@ public OptionCategory getCategory() {
     }
 
     public boolean isHidden() {
-        return this.option.isHidden() || this.getDescription() == null;
+        return this.option.isHidden();
     }
 
     public boolean isBuildTime() {
@@ -590,6 +590,9 @@ public PropertyMapper<T> build() {
             if (Objects.equals(option.getKey(), mapFrom)) {
                 opt = option.toBuilder().synthetic().build();
             }
+            if (this.description == null && !opt.isHidden()) {
+                throw new AssertionError("Non-hidden options require a description");
+            }
             if (option.getKey().contains(WildcardOptionsUtil.WILDCARD_START)) {
                 return new WildcardPropertyMapper<>(opt, to, enabled, enabledWhen, mapper, mapFrom, parentMapper, paramLabel, isMasked, validator, description, isRequired, requiredWhen, wildcardKeysTransformer, wildcardMapFrom);
             }

@@ -323,10 +323,31 @@ public void sanitizeDisabledMappers(AbstractCommand command) {
 
             sanitizeMappers(buildTimeMappers, disabledBuildTimeMappers, command);
             sanitizeMappers(runtimeTimeMappers, disabledRuntimeMappers, command);
-
-            entrySet().stream().filter(e -> e.getValue().size() > 1).findFirst().ifPresent(e -> {
-                throw new PropertyException(String.format("Duplicated mapper for key '%s'.", e.getKey()));
+
+            // enforce single mappings - by dropping multiple mapping synthetics
+            entrySet().stream().forEach(e -> {
+                if (e.getValue().size() <= 1) {
+                    return;
+                }
+                if (e.getKey().startsWith(MicroProfileConfigProvider.NS_KEYCLOAK_PREFIX)) {
+                    PropertyMapper<?> canonicalMapper = null;
+                    for (PropertyMapper<?> mapper : e.getValue()) {
+                        if (canonicalMapper != null) {
+                            if (mapper.option.isSynthetic()) {
+                                continue;
+                            }
+                            if (!canonicalMapper.option.isSynthetic()) {
+                                throw new PropertyException(String.format("Duplicated mapper for key '%s'.", e.getKey()));                    
+                            }
+                        }
+                        canonicalMapper = mapper;
+                    }
+                    e.setValue(List.of(canonicalMapper));
+                } else {
+                    throw new PropertyException(String.format("Duplicated mapper for key '%s'.", e.getKey()));
+                }
             });
+
         }
 
         public Map<OptionCategory, List<PropertyMapper<?>>> getRuntimeMappers() {
@@ -359,10 +380,7 @@ private static void sanitizeMappers(Map<OptionCategory, List<PropertyMapper<?>>>
         }
 
         private static void handleMapper(PropertyMapper<?> mapper, BiConsumer<String, PropertyMapper<?>> operation) {
-            // skip accounting for the from if it is a synthetic option
-            if (!mapper.getOption().isSynthetic()) {
-                operation.accept(mapper.getFrom(), mapper);
-            }
+            operation.accept(mapper.getFrom(), mapper);
             if (!mapper.getFrom().equals(mapper.getTo())) {
                 String to = mapper.getTo();
                 operation.accept(to, mapper);

@@ -2,6 +2,7 @@
 
 import java.util.List;
 
+import org.keycloak.config.Option;
 import org.keycloak.config.ProxyOptions;
 import org.keycloak.quarkus.runtime.cli.PropertyException;
 import org.keycloak.quarkus.runtime.configuration.Configuration;
@@ -15,6 +16,7 @@ final class ProxyPropertyMappers implements PropertyMapperGrouping{
 
     @Override
     public List<PropertyMapper<?>> getPropertyMappers() {
+        Option<?> syntheticOption = ProxyOptions.PROXY_HEADERS.toBuilder().synthetic().build();
         return List.of(
                 fromOption(ProxyOptions.PROXY_HEADERS)
                         .to("quarkus.http.proxy.proxy-address-forwarding")
@@ -29,23 +31,23 @@ public List<PropertyMapper<?>> getPropertyMappers() {
                             }
                         })
                         .build(),
-                fromOption(ProxyOptions.PROXY_FORWARDED_HOST)
+                fromOption(syntheticOption)
                         .to("quarkus.http.proxy.enable-forwarded-host")
                         .mapFrom(ProxyOptions.PROXY_HEADERS, (v, c) -> proxyEnabled(null, v, c))
                         .build(),
-                fromOption(ProxyOptions.PROXY_FORWARDED_HEADER_ENABLED)
+                fromOption(syntheticOption)
                         .to("quarkus.http.proxy.allow-forwarded")
                         .mapFrom(ProxyOptions.PROXY_HEADERS, (v, c) -> proxyEnabled(ProxyOptions.Headers.forwarded, v, c))
                         .build(),
-                fromOption(ProxyOptions.PROXY_X_FORWARDED_HEADER_ENABLED)
+                fromOption(syntheticOption)
                         .to("quarkus.http.proxy.allow-x-forwarded")
                         .mapFrom(ProxyOptions.PROXY_HEADERS, (v, c) -> proxyEnabled(ProxyOptions.Headers.xforwarded, v, c))
                         .build(),
-                fromOption(ProxyOptions.PROXY_X_FORWARDED_PREFIX_HEADER_ENABLED)
+                fromOption(syntheticOption)
                         .to("quarkus.http.proxy.enable-forwarded-prefix")
                         .mapFrom(ProxyOptions.PROXY_HEADERS, (v, c) -> proxyEnabled(ProxyOptions.Headers.xforwarded, v, c))
                         .build(),
-                fromOption(ProxyOptions.PROXY_TRUSTED_HEADER_ENABLED)
+                fromOption(syntheticOption)
                         .to("quarkus.http.proxy.enable-trusted-proxy-header")
                         .mapFrom(ProxyOptions.PROXY_HEADERS, (v, c) -> proxyEnabled(null, v, c))
                         .build(),