== Breaking changes

Breaking changes are identified as those that might require changes for existing users to their configurations or applications.
In minor or patch releases, {project_name} will only introduce breaking changes to fix bugs.

=== Valid redirect URIs for clients do not accept wildcards for hostname anymore

The wildcard comparison for valid redirect URIs does not affect the hostname anymore. Previously patterns like `$$https://example.com*$$` were accepted and lead to allow unintended domains like `$$https://example.com.other.domain.com$$`. Since this release, the hostname does not accept such type of wildcard and those patterns will be managed as if the wildcard is after the hostname `$$https://example.com/*$$`. The full wildcard for the hostname `$$https://*$$` is still accepted because its interpretation cannot be misunderstood.

Note that OAuth 2.0 recommends exact string matching in the link:https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#name-protecting-redirect-based-f[Security Best Current Practice] and draft for OAuth 2.1 enforces it. {project_name} recommends to not use any wildcard valid redirect URI for clients. See link:{adminguide_link}#unspecific-redirect-uris_server_administration_guide[Unspecific redirect URIs] in the {adminguide_name} for more information.

=== Files for the Java Keystore provider should be placed inside a fixed realm directory

The Java Keystore provider allows the realm administrator to load keys from an encrypted Java keystore file instead of the {project_name}'s database. Since this release, the path of the file is restricted to be inside a folder whose name should be the realm name and, in turn, this realm folder should be inside a fixed main directory for keystores (by default the `data` directory, `${kc.home.dir}/data`). For example, for a realm called `test`, all keystore files should be located under `${kc.home.dir}/data/test`. This way, {project_name} avoids leaking information from the File System and the keys are isolated between realms.

The main keystores directory, where the different realm folders are located, can be customized using a provider startup option:

```
kc.[sh|bat] start --spi-keys--java-keystore--keystores-path /path/to/keystores
```

When a keystore is created or updated, the `keystore` configuration option is checked to be a file under the commented realm folder. If the keystore is outside its boundaries, the operation fails. This new behavior means that existing keystores continue working but cannot be updated or modified until the file is copied to an allowed path. Imports from a previous configuration, with store files outside the realm folder, will fail in the same way.

If you are using a Java Keystore file to provide keys for a realm, please copy the keystore inside the appropriate realm folder and update the `java-keystore` provider configuration accordingly.

For more information, see link:{adminguide_link}#realm_keys[Configuring realm keys] chapter in the {adminguide_name}.

== Notable changes

Notable changes may include internal behavior changes that prevent common misconfigurations, bugs that are fixed, or changes to simplify running {project_name}.
It also lists significant changes to internal APIs.

=== Maximum length of the token parameters in the OIDC token endpoint

When the OIDC token endpoint request (or OAuth2 token endpoint request) is sent, a new limit exists for the maximum length of "token" OIDC/OAuth2 parameter. The maximum length of each "normal" parameter is still 4,000 characters as in previous version.
However maximum length of the "token" parameter is increased to 20,000 characters. Also when limit for the "token" parameter is reached, the parameter will not be ignored, but request will fail.

As "token" parameter is considered a parameter containing possibly long token (for example long JWT or SAML assertion) with unbounded data (For example possibly big amount of roles inside JWT).
Applies for example for parameters like `subject_token` sent in case of the Token exchange grant.

If you want to increase or lower those numbers, start the server with the option `req-token-params-default-max-size` for the default maximum length of the
OIDC/OAuth2 token parameter or you can use something such as `req-params-max-size` for one specific parameter. For more details, see the `login-protocol` provider configuration in the link:{allproviderconfigguide_link}[{allproviderconfigguide_name}].

=== Validation of client_session_host parameter
The `client_session_host` parameter is now validated against the client's registered nodes and management URL.
This parameter is sent by clients during token refresh and is used when the `${application.session.host}` placeholder is present in a client's backchannel logout URL configuration.

It was primarily used by legacy adapters that have been removed.
This improves security by ensuring that only trusted, pre-registered hosts can be used in backchannel logout URLs.

=== Registration Access Tokens cannot be used when client is disabled

Registration Access Tokens (RAT) can no longer be used to retrieve, update, or delete a client when the client is disabled.

If you attempt to use a RAT to manage a disabled client, the request will be rejected with an HTTP 401 Unauthorized response. To manage a disabled client, you must use admin credentials instead of the client's RAT.

Note that a RAT can still be used to disable a client, but once the client is disabled, the RAT can no longer be used to enable it again or perform other operations.

