Repository navigation
Replies: 4 comments
|
I can see a few things we can do to improve the documentation that lists features:
|
|
Created a follow-up issue for this discussion as we should really do something about it: #41383 |
|
Yeah, look what I get when I try to find information about some of the features: This is using the exact terms used to describe the feature in the list. If I expand the search by leaving out some words, I get results that tell me there simply are no real docs about the Account REST API: The Server Administration Guide mentions 'Account REST API' just once:
https://www.keycloak.org/docs/latest/server_admin/index.html#read_only_user_attributes The Keycloak Admin REST API does have its own page: I expect something similar for the Account REST API and indeed, for each feature. |
|
Searching for 'Kerberos' we only get Javadocs: |
Uh oh!
There was an error while loading. Please reload this page.
Keycloak has the concept of a 'feature'. A 'feature' in this context is a high-level module-like part of Keycloak that can be enabled or disabled.
Apparently (I am not sure how it works) this can actually result in a (slightly) different build of Keycloak being used/created depending on the enabled features. At least that is what the documentation surrounding optimizing the Keycloak build suggests to me.
Of course, the word feature is also used much more generically to describe any piece of functionality which is or might be supported by Keycloak. Such as the 'email as username' 'feature'. This makes searching the docs for the 'feature as module that can be enabled or diasbled in Keycloak' very hard. So if this was mentioned here before, I'm sorry. I tried search but the word 'feature' is simply way too common in the docs to give meaningful results.
I asked Copilot to search for me. But it cant really produce much information for me except the bits concerning the CLI flag that I linked above. Probably it has the same issue where it simply is very hard for it to distinguish between the word feature as in something the product can or cannot do, versus 'feature', the things that can be enabled/disabled using the CLI flag.
The most relevant part I have been able to find so far is the page aptly named 'Features' which has a list of supported features. But this list is just a very concise list of the name of the feature and a very short description. For example, the entry for
admin-apijust reads this:Eh that is not very helpful at all....
I have questions. Lots. Like, what happens if I disable it? Which parts of Keycloak will stop working? What does the feature entail? Where are its 'borders'? Which parts are considered part of the feature and which ones not? Or even more fundamental: what does this feature even do in the first place??
For example, kerberos:
Thats it.... I can Google what Kerberos is, but I end up watching videos trying to explain the whole protocol to me.... What I need to know is what does this feature do when enabled/disabled in Keycloak but I wont find that just searching for Kerberos and when I try something like
Keycloak feature KerberosI will just find lots of people saying that Keycloak has lots of cool features like Kerberos...IMHO if the module/feature was important enough to give it its own name and allow it to be separately enabled / disabled, it should be important enough to document it. IMHO each and every single feature in that list should have a link to a dedicated page that attempts to answer the questions admins will have when considering whether the feature should be enabled or not. Like which other features might depend on this one etc.
Now maybe all that documentation already exists. In that case we could just add links to these pages and make them more discoverable.
On a related note I think it would be wise to change the name of this concept ever so slightly to make it easier for people to search for it. So i.s.o calling them just 'Features', we could systematically and consistently call them 'Keycloak Feature Modules' for example. Yeah it sucks that the name is longer but at least now we stand a chance of using search to find info on it.
All reactions