When it comes to building Keycloak extensions it can be difficult to know what is supported and what is not.

In general if the Provider interface is in server-spi an extension can call the provider, and if the ProviderFactory interface is in server-spi-private it is supported to implement a custom provider. In many cases you're not really supposed to call providers directly, but rather through managers. Where managers don't really have a standard way to discover them. Some are available on KeycloakSession while some are not. Maybe there's also a need for a public Provider interface, and a private Provider interface?

However, which of all the other modules are supported APIs, and which are not? There's a lot of utility classes around, and wrappers like TokenManager for instance. These are hard to find, and often the APIs are not great at all.

Then comes the next question around dependencies? Should one add custom dependencies? If so how do you make sure they don't conflict with the dependency versions from the distribution? There's no really easy way to include all dependencies for Keycloak into your extension. Did anyone say a BOM?

One thing I had in mind is that we would create a new KeycloakSession interface or something that contains supported APIs to build extensions on top of. And essentially anything you can do through KeycloakSession is supported, but anything else is not supported. Want to decode a JWT for instance? Well, then call KeycloakSession.apis().jwt().decodeToken(...) or something along those lines. Everything would be discoverable through the KeycloakSession, and there would not be any static utilities, managers, or anything else dangling around.

The other thing would be to add an BOM with supported dependencies to build an extension on top of. This would be a subset of the dependencies in the distribution, and only contain dependencies you should be calling (for example not Quarkus APIs directly).

A final thing to note here is that some things in the Keycloak code base is incredibly complex to deal with as the API is not great. For example doing something as basic as generating or validating a JWS is really messy and complex.