Discourage obtaining the KeycloakSession by means other than when creating a provider

[pedroigor]

Description

In order to avoid coupling extensions with technologies from the underlying stack used by the server and not fully-supported we need a consistent and supported mechanism to obtain the KeycloakSession when developing custom extensions.

Extensions should favor obtaining the session whenever they are creating Provider instances from their corresponding ProviderFactory and any other mechanism to do that should not be supported or exposed.

As an example, the fact we currently support CDI does not mean that Keycloak supports CDI so using its APIs should be discouraged. A similar approach was taken when removing JAX-RS injection points from our REST layer for JAX-RS specific beans such as the request and response objects.

The main goal here is long-term maintainability and backward compatibility.

Discussion

#28182

Motivation

The main goal here is long-term maintainability and backward compatibility.

Details

No response

[pedroigor]

We probably want to make more explicit in our docs the technologies we support too:

• JAX-RS and how much of its API we support. For instance, mapping annotations.
• Hibernate. For instance, mapping annotations, ÈntityManager (or parts of it)
• ?

[shawkins]

JAX-RS and how much of its API we support. For instance, mapping annotations.

This is the existing doc note:

keycloak/docs/documentation/server_development/topics/extensions.adoc

Line 34 in d1549a0

NOTE: While it is possible to install other JAX-RS components via the providers extension mechanism, such as filters and interceptors, these are not officially supported.