keycloak-scim/docs/documentation/upgrading/topics/keycloak/changes-21_0_0.adoc

= Keycloak uses Micrometer for metrics

Keycloak provides an optional a metrics endpoint which exports metrics in the Prometheus format.
In this release the implementation to provide this data switched from SmallRye to Micrometer, which is the https://quarkus.io/guides/micrometer[recommended metrics library for Quarkus].

Due to this change, metrics have been renamed.
The following table shows some examples.

Before upgrading it is recommended to review all metrics returned from the endpoint before and after the change, and update their usage in dashboards and alerts.

.Examples of changed metrics names
|===
|Old metric name |New metric name

|`base_gc_total`
|`jvm_gc_pause_seconds_count`

|`base_gc_time_total_seconds`
|`jvm_gc_pause_seconds_sum`

|`base_thread_count`
|`jvm_threads_live_threads`

|`vendor_agroal_*`
|`agroal_*`

|===

= Deprecated RSA_SHA1 and DSA_SHA1 algorithms for SAML

Algorithms `RSA_SHA1` and `DSA_SHA1`, which can be configured as `Signature algorithms` on SAML adapters, clients and identity providers are deprecated. We recommend to use safer
alternatives based on `SHA256` or `SHA512`. Also, verifying signatures on signed SAML documents or assertions with these
algorithms do not work on Java 17 or higher. If you use this algorithm and the other party consuming your SAML documents is running on Java 17 or higher, verifying signatures will not work.

The possible workaround is to remove algorithms such as `++http://www.w3.org/2000/09/xmldsig#rsa-sha1++` or `++http://www.w3.org/2000/09/xmldsig#dsa-sha1++` from the list
of "disallowed algorithms" configured on property `jdk.xml.dsig.secureValidationPolicy` in the file `$JAVA_HOME/conf/security/java.security`.

= SAML SP metadata changes

In this version, Keycloak will refuse to decrypt assertions encrypted using
a realm key generated for signing purpose. This change means all encrypted
communication from IDP to SP (where Keycloak acts as the SP) will stop working.

There are two ways to make this work:

- either update the IDP configuration with the metadata generated by a newer
version of Keycloak,
- or run Keycloak in backward compatibility mode that will make Keycloak
work with the metadata generated by older Keycloak versions. This mode can be
enabled using `-Dkeycloak.saml.deprecated.encryption=true` flag. Note this
backward compatibility mode is planned to be removed in Keycloak 24.

= Deprecated methods from user session provider were removed

In Keycloak 13 there was introduced `UserLoginFailureProvider` and some methods from 
`UserSessionProvider` were moved there. The methods in `UserSessionProvider` were deprecated 
and now has been removed. Javadoc of these methods contained a corresponding replacement 
(see Javadoc of Keycloak 20 release).

= Custom themes using old admin console won't work

The old admin console, which was deprecated in previous versions, was finally removed. This also means that your custom themes, which were using it as parent theme or importing from it, won't work.
It is highly recommended to not deploy such themes at all as extending old admin console is not applicable anymore and there can be issues in Keycloak (at least warnings or errors in the logs) with
such themes deployed.

= Curl has been removed from the container

The https://quay.io/repository/keycloak/keycloak?tab=info[Keycloak Container Image] has been modified to enhance security. As a result, `+curl+` and other CLI tools have been removed, which you may have been using in your customized image. See the updated https://www.keycloak.org/server/containers[container guide] for information on how to handle this change.