Replies: 10 comments 13 replies
-
|
I agree with this idea. Now there are parameters related to multiple standards, and also Keycloak special parameters. There are also some parameters that are used as special parameters by Keycloak but defined in some standards as a different use. |
Beta Was this translation helpful? Give feedback.
-
|
I liked the idea and I also would like to contribute to it. If you will start this and want some help I will be glad to work on it. |
Beta Was this translation helpful? Give feedback.
-
|
I'm not quite sure about this. I don't think the average developer can or should try to implement a OAuth2/OIDC library, but rather leverage existing libraries. Even doing the basic OAuth 2.0 stuff properly requires referring to the spec, and great care to implement it securely. Could you elaborate a bit on who the target audience is and how this would be helpful compared to say the specs? |
Beta Was this translation helpful? Give feedback.
-
|
In the use cases that handle sensitive data in large scale business and expose keycloak's endpoints publicly (e.g., Authorization Endpoint, Token Endpoint), the customers of such use cases require to grasp which response (including error response) is returned from each endpoint in which situation in detail in advance. To do so, we need to investigate keycloak source codes. Whenever updating keycloak, we need to do so again. Regardless of its business scale, API specification-based client application development is in common. It is easy for client application developers to develop and test their own application if they can use an Authz server's endpoint specification in OpenAPI. With endpoint specification, such development and testing can be integrated into CI/CD pipeline run automatically. Considering these points above, I think it is worthwhile to document such endpoint specification in open standard like OpenAPI. |
Beta Was this translation helpful? Give feedback.
-
|
In addition to your comment, even for Admin API could be beneficial have this documented as well to be able to use without doing this type of investigation (at Keycloak codebase). |
Beta Was this translation helpful? Give feedback.
-
|
@jairsjunior I've opened this discussion. #8898 |
Beta Was this translation helpful? Give feedback.
-
|
I'm still not 100% convinced to be honest, as we haven't had anyone ask about this as far as I remember. So, worried it's a lot of effort to add, and maintain, for very few people to use it. I could definitively be convinced if we could generate the OpenAPI spec in a nice and clean way from annotated sources rather than manually crafting it (like what we did as a temporary solution for the Account APIs). If that same approach is then extendable to all endpoints even better. |
Beta Was this translation helpful? Give feedback.
-
|
I see, I've recognized that a lot of effort might be needed to maintain the documentation in OpenAPI spec. |
Beta Was this translation helpful? Give feedback.
-
|
Copying my comment from #8898 as I understand they have similar goals, that means providing documentation to our REST endpoints. A long time ago, we had a discussion about this and the initial idea was to create the Open API descriptors first and generate our HTML documentation, and the API code. It's been a while since it was created, and I believe it's a good idea to revisit and check if we have a better approach. My 2 cents to make our goals more concrete, I would change the scope to the current proposal to focus on the OpenAPI aspects, and also start with the Admin endpoints and Account endpoints, later extend to OAuth2/OIDC, so we can start smaller. In this way, we have everyone interested to discuss REST API documentation, helping us on this. Starting with the account endpoints would make a great example to other developers on how to document our endpoints. Now speaking about the implementation details, from what I recall some time ago we used a similar approach as GitHub starting from the design and generating the specification. That's less verbose and invasive than introducing more dependencies to the Keycloak codebase, plus annotations. GitHub also provides some actions, making it helpful to validate those specs https://github.com/github/rest-api-description/actions. Not sure if things had changed and got better, but I would start from the spec rather than introducing more annotations to the codebase. |
Beta Was this translation helpful? Give feedback.
-
|
I agree with your small start plan that work on Account REST API at first. IMO, we have two options, OpenAPI spec driven as you've suggested and code driven as I've suggested. For OpenAPI spec, I expect that this option can generate REST API codes from OpenAPI spec automatically. |
Beta Was this translation helpful? Give feedback.
-
|
The openapi-generator-maven-plugin could do the work. To synchronize with the Keycloak codebase, probably we need to automate this with GH actions. I believe we need a PoC to see if those things will work in practice. |
Beta Was this translation helpful? Give feedback.
-
|
I see, is it better to wait for other contributor's opinion about whether this work would be started officially for several weeks? |
Beta Was this translation helpful? Give feedback.
-
|
@tnorimat I'd suggest approaching this topic next year, when people return from holidays. People may have a different opinion than me. |
Beta Was this translation helpful? Give feedback.
-
|
Yes, We'll wait for them coming back next year. |
Beta Was this translation helpful? Give feedback.
-
|
Any news on it? I'm checking the maven plugin that was shared at the previous messages to do a PoC. |
Beta Was this translation helpful? Give feedback.
-
|
@stianst You've suggested code to OpenAPI spec approach while here OpenAPI spec to code approach is proposed. WDYT? |
Beta Was this translation helpful? Give feedback.
-
|
Having an OpenAPI spec would also benefit the Admin UI as we could generate code based off this and it would automate the implementation of the admin client. At the same time we could revise the REST Admin endpoint to better suite the Admin UI as we need some changes in how we gather the data. |
Beta Was this translation helpful? Give feedback.
-
|
created a POC: #12313 |
Beta Was this translation helpful? Give feedback.
-
|
I think this would be incredibly useful and beneficial. For example I am trying to use keycloak for UMA authorization. But I am not using the Java adapters. So I have to create permission tickets myself. I see that this is described in the docs. But the docs mention a few cases of how to create tickets. But I have no clue what other parameters/options are accepted by the API. Generating an API spec and publishing it would make this a breeze. |
Beta Was this translation helpful? Give feedback.
-
|
The OpenAPI spec doc doesn't contain the new Organization feature (preview) added in v25.0.0 and the latest update to the docs are from |
Beta Was this translation helpful? Give feedback.
-
|
Hi @mostafa. Thanks for the help. I have a guess that it is not there because of how we are exposing the Organization API in the Admin API. The API is exposed via |
Beta Was this translation helpful? Give feedback.
-
|
Created #30832 |
Beta Was this translation helpful? Give feedback.
-
|
Would it be possible to add the token introspection endpoint to openapi spec in the near future. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
The aim of this idea is to make OpenAPI documentation for OAuth2/OIDC related endpoints (Ex. Authz Endpoint, Token Endpoint, Token Introspection Endpoint, Token Revocation Endpoint, Device Authz Endpoint, Backchannel Authn Endpoint, Logout Endpoint, UserInfo Endpoint, Pushed Authz Endpoint, etc..).
Clarifying which kind of response returns when a client sends which kind of request in detail.
Its motivation is that it makes easy for client app developers to test their app's connectivity with keycloak.
I know some of these endpoints do not follow REST API. However, regardless of being REST API or not, such endpoint's documentation is beneficial for client app developers especially.
As mentioned in #8898, OpenAPI documentation project for Account REST API has already existed.
To follow this project, OAuth2/OIDC related endpoints are also documented by OpenAPI.
I'm not sure adding OAuth2/OIDC related endpoints' documentation is added to existing project, or create its new project.
What do you think about this idea? I am willing to work on it if this idea can is accepted by keycloak community.
Beta Was this translation helpful? Give feedback.
All reactions