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

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

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