From 700b86fad85c17d90cc133013e5704e760f30686 Mon Sep 17 00:00:00 2001 From: Steven Hawkins Date: Tue, 14 Oct 2025 08:01:08 -0400 Subject: [PATCH] fix: refining https-protocols documentation (#43420) closes: #43164 Signed-off-by: Steve Hawkins --- docs/guides/server/enabletls.adoc | 2 +- .../src/main/java/org/keycloak/config/HttpOptions.java | 6 ++++-- .../help/HelpCommandDistTest.testStartDevHelp.approved.txt | 4 +++- .../HelpCommandDistTest.testStartDevHelpAll.approved.txt | 4 +++- .../cli/help/HelpCommandDistTest.testStartHelp.approved.txt | 4 +++- .../help/HelpCommandDistTest.testStartHelpAll.approved.txt | 4 +++- .../HelpCommandDistTest.testStartOptimizedHelp.approved.txt | 4 +++- ...lpCommandDistTest.testStartOptimizedHelpAll.approved.txt | 4 +++- ...ndDistTest.testUpdateCompatibilityCheckHelp.approved.txt | 4 +++- ...istTest.testUpdateCompatibilityCheckHelpAll.approved.txt | 4 +++- ...istTest.testUpdateCompatibilityMetadataHelp.approved.txt | 4 +++- ...Test.testUpdateCompatibilityMetadataHelpAll.approved.txt | 4 +++- 12 files changed, 35 insertions(+), 13 deletions(-) diff --git a/docs/guides/server/enabletls.adoc b/docs/guides/server/enabletls.adoc index 875f021733c..0a3ad4ec0f5 100644 --- a/docs/guides/server/enabletls.adoc +++ b/docs/guides/server/enabletls.adoc @@ -52,7 +52,7 @@ However, as a temporary work-around, you can enable deprecated protocols by runn <@kc.start parameters="--https-protocols=[,]"/> -To also allow TLSv1.2, use a command such as the following: `kc.sh start --https-protocols=TLSv1.3,TLSv1.2`. +For example to only enable TLSv1.3, use a command such as the following: `kc.sh start --https-protocols=TLSv1.3`. == Switching the HTTPS port {project_name} listens for HTTPS traffic on port `8443`. To change this port, use the following command: diff --git a/quarkus/config-api/src/main/java/org/keycloak/config/HttpOptions.java b/quarkus/config-api/src/main/java/org/keycloak/config/HttpOptions.java index 9b0258c232d..474b69ac5e3 100644 --- a/quarkus/config-api/src/main/java/org/keycloak/config/HttpOptions.java +++ b/quarkus/config-api/src/main/java/org/keycloak/config/HttpOptions.java @@ -61,8 +61,10 @@ public class HttpOptions { public static final Option> HTTPS_PROTOCOLS = OptionBuilder.listOptionBuilder("https-protocols", String.class) .category(OptionCategory.HTTP) - .description("The list of protocols to explicitly enable.") - .defaultValue(Arrays.asList("TLSv1.3,TLSv1.2")) + .description("The list of protocols to explicitly enable. If a value is not supported by the JRE / security configuration, it will be silently ignored.") + .expectedValues(Arrays.asList("TLSv1.3", "TLSv1.2")) + .strictExpectedValues(false) + .defaultValue(Arrays.asList("TLSv1.3", "TLSv1.2")) .build(); public static final Option HTTPS_CERTIFICATES_RELOAD_PERIOD = new OptionBuilder<>("https-certificates-reload-period", String.class) diff --git a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartDevHelp.approved.txt b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartDevHelp.approved.txt index ccb426fa33b..67c04c0731e 100644 --- a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartDevHelp.approved.txt +++ b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartDevHelp.approved.txt @@ -257,7 +257,9 @@ HTTP(S): no value is set, it defaults to 'BCFKS'. --https-port The used HTTPS port. Default: 8443. --https-protocols - The list of protocols to explicitly enable. Default: TLSv1.3,TLSv1.2. + The list of protocols to explicitly enable. If a value is not supported by the + JRE / security configuration, it will be silently ignored. Possible values + are: TLSv1.3, TLSv1.2, or a custom one. Default: TLSv1.3,TLSv1.2. --https-trust-store-file The trust store which holds the certificate information of the certificates to trust. diff --git a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartDevHelpAll.approved.txt b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartDevHelpAll.approved.txt index 9f3d92a5f3c..57a7a1fd8e3 100644 --- a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartDevHelpAll.approved.txt +++ b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartDevHelpAll.approved.txt @@ -336,7 +336,9 @@ HTTP(S): no value is set, it defaults to 'BCFKS'. --https-port The used HTTPS port. Default: 8443. --https-protocols - The list of protocols to explicitly enable. Default: TLSv1.3,TLSv1.2. + The list of protocols to explicitly enable. If a value is not supported by the + JRE / security configuration, it will be silently ignored. Possible values + are: TLSv1.3, TLSv1.2, or a custom one. Default: TLSv1.3,TLSv1.2. --https-trust-store-file The trust store which holds the certificate information of the certificates to trust. diff --git a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartHelp.approved.txt b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartHelp.approved.txt index 73a0e17777c..d49057b46a5 100644 --- a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartHelp.approved.txt +++ b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartHelp.approved.txt @@ -305,7 +305,9 @@ HTTP(S): no value is set, it defaults to 'BCFKS'. --https-port The used HTTPS port. Default: 8443. --https-protocols - The list of protocols to explicitly enable. Default: TLSv1.3,TLSv1.2. + The list of protocols to explicitly enable. If a value is not supported by the + JRE / security configuration, it will be silently ignored. Possible values + are: TLSv1.3, TLSv1.2, or a custom one. Default: TLSv1.3,TLSv1.2. --https-trust-store-file The trust store which holds the certificate information of the certificates to trust. diff --git a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartHelpAll.approved.txt b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartHelpAll.approved.txt index 8819a82977b..d0e5d18c4d4 100644 --- a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartHelpAll.approved.txt +++ b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartHelpAll.approved.txt @@ -337,7 +337,9 @@ HTTP(S): no value is set, it defaults to 'BCFKS'. --https-port The used HTTPS port. Default: 8443. --https-protocols - The list of protocols to explicitly enable. Default: TLSv1.3,TLSv1.2. + The list of protocols to explicitly enable. If a value is not supported by the + JRE / security configuration, it will be silently ignored. Possible values + are: TLSv1.3, TLSv1.2, or a custom one. Default: TLSv1.3,TLSv1.2. --https-trust-store-file The trust store which holds the certificate information of the certificates to trust. diff --git a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartOptimizedHelp.approved.txt b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartOptimizedHelp.approved.txt index 07c71817c60..a6721e478e4 100644 --- a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartOptimizedHelp.approved.txt +++ b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartOptimizedHelp.approved.txt @@ -271,7 +271,9 @@ HTTP(S): no value is set, it defaults to 'BCFKS'. --https-port The used HTTPS port. Default: 8443. --https-protocols - The list of protocols to explicitly enable. Default: TLSv1.3,TLSv1.2. + The list of protocols to explicitly enable. If a value is not supported by the + JRE / security configuration, it will be silently ignored. Possible values + are: TLSv1.3, TLSv1.2, or a custom one. Default: TLSv1.3,TLSv1.2. --https-trust-store-file The trust store which holds the certificate information of the certificates to trust. diff --git a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartOptimizedHelpAll.approved.txt b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartOptimizedHelpAll.approved.txt index 747736384f1..2938418dbb4 100644 --- a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartOptimizedHelpAll.approved.txt +++ b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartOptimizedHelpAll.approved.txt @@ -303,7 +303,9 @@ HTTP(S): no value is set, it defaults to 'BCFKS'. --https-port The used HTTPS port. Default: 8443. --https-protocols - The list of protocols to explicitly enable. Default: TLSv1.3,TLSv1.2. + The list of protocols to explicitly enable. If a value is not supported by the + JRE / security configuration, it will be silently ignored. Possible values + are: TLSv1.3, TLSv1.2, or a custom one. Default: TLSv1.3,TLSv1.2. --https-trust-store-file The trust store which holds the certificate information of the certificates to trust. diff --git a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityCheckHelp.approved.txt b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityCheckHelp.approved.txt index 95f14e35746..b7b72da62e5 100644 --- a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityCheckHelp.approved.txt +++ b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityCheckHelp.approved.txt @@ -304,7 +304,9 @@ HTTP(S): no value is set, it defaults to 'BCFKS'. --https-port The used HTTPS port. Default: 8443. --https-protocols - The list of protocols to explicitly enable. Default: TLSv1.3,TLSv1.2. + The list of protocols to explicitly enable. If a value is not supported by the + JRE / security configuration, it will be silently ignored. Possible values + are: TLSv1.3, TLSv1.2, or a custom one. Default: TLSv1.3,TLSv1.2. --https-trust-store-file The trust store which holds the certificate information of the certificates to trust. diff --git a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityCheckHelpAll.approved.txt b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityCheckHelpAll.approved.txt index c0d8b2afd55..11391b86a25 100644 --- a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityCheckHelpAll.approved.txt +++ b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityCheckHelpAll.approved.txt @@ -336,7 +336,9 @@ HTTP(S): no value is set, it defaults to 'BCFKS'. --https-port The used HTTPS port. Default: 8443. --https-protocols - The list of protocols to explicitly enable. Default: TLSv1.3,TLSv1.2. + The list of protocols to explicitly enable. If a value is not supported by the + JRE / security configuration, it will be silently ignored. Possible values + are: TLSv1.3, TLSv1.2, or a custom one. Default: TLSv1.3,TLSv1.2. --https-trust-store-file The trust store which holds the certificate information of the certificates to trust. diff --git a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityMetadataHelp.approved.txt b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityMetadataHelp.approved.txt index 1e5452f2053..a5662bde1d8 100644 --- a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityMetadataHelp.approved.txt +++ b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityMetadataHelp.approved.txt @@ -302,7 +302,9 @@ HTTP(S): no value is set, it defaults to 'BCFKS'. --https-port The used HTTPS port. Default: 8443. --https-protocols - The list of protocols to explicitly enable. Default: TLSv1.3,TLSv1.2. + The list of protocols to explicitly enable. If a value is not supported by the + JRE / security configuration, it will be silently ignored. Possible values + are: TLSv1.3, TLSv1.2, or a custom one. Default: TLSv1.3,TLSv1.2. --https-trust-store-file The trust store which holds the certificate information of the certificates to trust. diff --git a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityMetadataHelpAll.approved.txt b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityMetadataHelpAll.approved.txt index e2773835d29..9b2f02d9b73 100644 --- a/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityMetadataHelpAll.approved.txt +++ b/quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testUpdateCompatibilityMetadataHelpAll.approved.txt @@ -334,7 +334,9 @@ HTTP(S): no value is set, it defaults to 'BCFKS'. --https-port The used HTTPS port. Default: 8443. --https-protocols - The list of protocols to explicitly enable. Default: TLSv1.3,TLSv1.2. + The list of protocols to explicitly enable. If a value is not supported by the + JRE / security configuration, it will be silently ignored. Possible values + are: TLSv1.3, TLSv1.2, or a custom one. Default: TLSv1.3,TLSv1.2. --https-trust-store-file The trust store which holds the certificate information of the certificates to trust.