Repository navigation
Document provided ProtocolMapper implementations - #47331
Conversation
d2b346a to
c88f534
Compare
c88f534 to
01e6548
Compare
|
Updated so that we now have a ProtocolMapper index table at the start of the page, grouped by protocol, which then links to the detailed configuration summary found later in the page. |
|
Putting on the head of a technical write: Who is the intended reader of the document: If it is a regular admin that would configure Keycloak, we usually avoid internal tech speak like SPIs, and focus on the configuration and the behavior one can achieve. The almost only place where we talk about SPIs is the server developer guide - https://www.keycloak.org/docs/latest/server_development/index.html So I ask: Please state the audience in this issue, and possibly in a comment in the index.adoc so people know who they are writing for. The "Keycloak Admin API Guide" is a completely new "book". As someone involved with downstream docs I ask: Will this guide be available downstream? |
The intended audience of the document is both an Admin and a Developer. Currently there is no way for Keycloak admins or developers to know what
Unfortunately the latter is necessary in order to determine what config properties an implementation expects if they want to define things decoratively in a realm JSON or use an admin client/REST APIs. The idea of this document is to document the implementations available and the expected configuration, to save both admins and developers having to go through this exercise. I mentioned SPIs as I wanted it to be clear to developers that they can provide their own implementation if an existing one does not match their requirements. I should maybe make this more explicit. WDYT to having a sub-section of the introduction aimed specifically at developers that explains this?
The plan was to start with upstream and evaluate downstream later. We had discussed that this book may contain additional guides in the future for other components whose capabilities/config we do not currently document, e.g. |
| available in `ProtocolMapperRepresentation.config` for each `ProtocolMapper` implementation. | ||
|
|
||
| [discrete] | ||
| == Index |
There was a problem hiding this comment.
Maybe Overview would be better than Index?
| <#assign mappers = ctx.protocolMappers.getMappersByProtocol(["openid-connect", "oid4vc", "saml", "docker-v2"]) /> | ||
| <#list mappers as protocol, categoryMap> | ||
|
|
||
| === ${protocol} |
There was a problem hiding this comment.
| === ${protocol} | |
| == ${protocol} |
Protocol ends up as h3, which is the same as mapper names:
As people can provide their own implementations, I'd rather provide an API endpoint that provides the metadata and displays it in the admin UI. The functionality where to find it is then documented in the server administration guide. That at least my opinion. If you start a new book here, that will have some knock-on efforts to publish that downstream, so I wouldn't start it unless there is a lot more content to come. |
| When creating a `ProtocolMapperRepresentation`, the `config` field is a key-value map whose available entries | ||
| depend on the specific mapper type. This page serves as a reference for the expected configuration options | ||
| available in `ProtocolMapperRepresentation.config` for each `ProtocolMapper` implementation. | ||
|
|
There was a problem hiding this comment.
Would be good to include an example here
There was a problem hiding this comment.
Updated to include two examples 1) raw JSON payload 2) Java admin client ProtocolMapperRepresentation.
There was a problem hiding this comment.
Looks very good to me; I've added a few small suggestions
Whole point here is to not have to use the Admin UI to use the Admin APIs. Once we have the pattern for this it will be relatively easy to add for other things like client scopes, identity providers, user federation, etc.. We should also move the Admin API documentation link to this section rather than https://www.keycloak.org/documentation. Once we have sufficient enough stuff in this guide we can consider publishing it downstream, but for now I would consider this upstream only. Just to add, with fairly little effort @ryanemerson has been able to quickly generated fairly good documentation around protocol mappers, which is a lot better way to discover protocol mappers as well as understanding how to create protocol mappers through the Admin APIs than what folks currently have to do with using the Admin UI and reverse engineering the JSON from there. |
|
Ok, then let's process, I will not block it. |
0073d95 to
dcc1f6d
Compare
|
All comments addressed. Once this PR is merged I will create a PR for the website as we need to add the new guide section: |
| |=== | ||
| </#if> | ||
|
|
||
| ''' |
There was a problem hiding this comment.
I'd remove this; the headers and tables creates a natural break; there's no need for the horizontal lines:
| grouped by the associated protocol. | ||
|
|
||
|
|
||
| .ProtocolMapper Overview |
There was a problem hiding this comment.
I'd remove the footer on this table as well:
|
|
||
| |=== | ||
|
|
||
| ''' |
There was a problem hiding this comment.
I'd remove this; headers and tables create a natural break anyways, this just looks messy ;)
Closes keycloak#47330 Signed-off-by: Ryan Emerson <remerson@ibm.com> Co-authored-by: Stian Thorgersen <stianst@gmail.com>
7d86942 to
578db40
Compare
Closes keycloak#47330 Signed-off-by: Ryan Emerson <remerson@ibm.com> Co-authored-by: Stian Thorgersen <stianst@gmail.com>
Closes #47330
Website sample:
