keycloak · vmuzikar · Jun 13, 2025 · May 27, 2025 · Jun 3, 2025 · Jun 3, 2025
@@ -235,6 +235,13 @@ public static interface Scope {
 
         Scope scope(String... scope);
 
+        /**
+         * @deprecated since 26.3.0, to be removed
+         *
+         * <br>Was introduced for testing purposes and was not fully / correctly implements
+         * across Scope implementations
+         */
+        @Deprecated
         Set<String> getPropertyNames();
     }
 }
@@ -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=<algorithm>`.
+The default password hashing algorithm for the server can be configured with `--spi-password-hashing--provider-default=<algorithm>`.
 
 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

@@ -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
 ----
@@ -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
 ----
@@ -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.  

@@ -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=<lifespan-in-seconds>
+--spi-user-sessions--infinispan--offline-session-cache-entry-lifespan-override=<lifespan-in-seconds>
 ----
 
 Similarly for offline client sessions:
 
 [source,bash]
 ----
---spi-user-sessions-infinispan-offline-client-session-cache-entry-lifespan-override=<lifespan-in-seconds>
+--spi-user-sessions--infinispan--offline-client-session-cache-entry-lifespan-override=<lifespan-in-seconds>
 ----
@@ -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.

@@ -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.

@@ -25,14 +25,14 @@ 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]
 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::[]
@@ -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`.

@@ -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.

@@ -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]]

@@ -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.

@@ -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()`:

@@ -3,6 +3,18 @@
 Breaking changes are identified as requiring changes from existing users to their configurations.
 In minor or patch releases we will only do breaking changes to fix bugs.
 
+=== 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 `--`(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-<spi-name>--<provider-name>--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.   
+
 === Reading information about temporarily locked users
 
 In previous releases there was an inconsistency in the REST endpoint result of getting a user (`+GET /admin/realms/{realm}/users/{user-id}+`) and searching for a user (`+GET /admin/realms/{realm}/users+`). When BruteForce is enabled and a user was temporarily locked out the former endpoint would return `enabled=false` while the latter would return `enabled=true`. If the user was updated and enabled was false due to temporary lockout then the user would be disabled permanently. Both endpoints now return `enabled=true` when a user is temporarily locked out. To check whether a user is temporarily locked out the BruteForceUserResource endpoint should be utilised (`+GET /admin/realms/{realm}/attack-detection/brute-force/users/{userId}+`).
@@ -137,6 +149,10 @@ In relation to supported Recovery codes, we deprecated the password policy `Reco
 This password policy was not related to passwords at all, but was related to recovery codes, and hence using password policy is not appropriate way for the configuration of the threshold. It is
 recommended to use the configuration option *Warning Threshold* of the *Recovery Authentication Codes* required action instead of using password policy. For more details, see the link:{adminguide_link}#_recovery-codes[Recovery codes documentation].
 
+=== Scope.getPropertyNames deprecated for removal
+
+The `org.keycloak.Config.Scope.getPropertyNames` method has been deprecated for removal.
+
 == Removed features
 
 The following features have been removed from this release.

@@ -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=<path>/<file.sql>
+kc.[sh|bat] start --spi-connections-jpa--quarkus--migration-export=<path>/<file.sql>
 ----
 
 For further details on how to apply this file to the database, see the documentation for your relational database.

@@ -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:

@@ -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.