Thank you for this contribution. This moves around quite some bits of the code. I also read your comment in the parent issue:

this might be a breaking change in the API and require changes in the admin UI to separate those two endpoints.

Could you please

• summarize how the API behavior changed due to this PR, and
• share the overall idea of the refactoring you did?

This would help me a lot when reviewing this. Thanks!

Sorry, I've updated the PR description now to give more details about this.

I had a look at this PR and I still need to understand more of the AUTHZ stuff and how the URLs and UI work together. I agree that the current API has its flaws and it should be changed. Still I'm not sure how, although I know we should deprecate some of the usages.

I found that the Java Admin CLI offers a little bit different APIs to this, as the types are named there, and they return different representations: https://github.com/keycloak/keycloak/blob/3f6925143aa8a3e61c30782029ca5ea781d60ce0/integration/admin-client-jee/src/main/java/org/keycloak/admin/client/resource/PoliciesResource.java

Again, I need more time to look at this.

Rebased onto current main so I can use this patch in my build.

I found that the Java Admin CLI offers a little bit different APIs to this, as the types are named there, and they return different representations: https://github.com/keycloak/keycloak/blob/3f6925143aa8a3e61c30782029ca5ea781d60ce0/integration/admin-client-jee/src/main/java/org/keycloak/admin/client/resource/PoliciesResource.java

@ahus1 @999eagle FTR, originally we did not have specific endpoints for each permission or policy type but only a generic API to handle all of them using a generic representation. At that time we also did not have OpenAPI support and we did not change the Authorization API to fit into it.

Having a proper OpenAPI is even more tricky if you consider that each policy type has its own representation to make it easier to manage those different policies. Are we changing this here?

@pedroigor I have not changed how policies themselves are represented and how the representations of different types of policies are documented in the OpenAPI spec as that would be (as you already said yourself) quite tricky. Policies are still documented to be returned as the generic representation.

This is basically the smallest possible API change to be able to at least document all the policy-related API endpoints (not including the specific bodies returned of course). The only thing this should change is to separate the existing API endpoint /admin/realms/{realm}/clients/{client-uuid}/authz/resource-server/policy/{type} (where {type} can actually be either a type or an id which already returns different sub-services depending on which one it is) into two separate endpoints /admin/realms/{realm}/clients/{client-uuid}/authz/resource-server/policy/by-type/{policy-type} and /admin/realms/{realm}/clients/{client-uuid}/authz/resource-server/policy/by-id/{policy-id} that always return the same type of sub-service (PolicyTypeService and PolicyResourceService respectively).

@pedroigor @ahus1 ping
did you have any time to review this yet?

rebased onto current main again.

rebased again to be able to use this. also pinging @ahus1 @pedroigor again, did you have time to review this?

@999eagle - sorry for the long time I kept you waiting on this PR. I appreciate all the enhancements you provided in the previous PRs by adding the missing annotations to Keycloak's code.

This one is IMHO different as it adds new API methods that allow for documentation, while it keeps the old API that is then still undocumented. In addition to that, I struggle with the policy endpoints as I'm not familiar with this area of the code.

The newly added API is then still incomplete in at least two ways:

• The responses are not documented in the API description (you mention that above, but I didn't check the results).
• The Java admin client's API description still uses the old API. While the backend is dynamic, the client is explicitly typed - see

  keycloak/integration/admin-client-jee/src/main/java/org/keycloak/admin/client/resource/PoliciesResource.java

  Lines 81 to 107 in 3f69251

  	@Path("role")
  	RolePoliciesResource role();
  	@Path("user")
  	UserPoliciesResource user();
  	@Path("js")
  	JSPoliciesResource js();
  	@Path("time")
  	TimePoliciesResource time();
  	@Path("aggregate")
  	AggregatePoliciesResource aggregate();
  	@Path("client")
  	ClientPoliciesResource client();
  	@Path("group")
  	GroupPoliciesResource group();
  	@Path("client-scope")
  	ClientScopePoliciesResource clientScope();
  	@Path("regex")
  	RegexPoliciesResource regex();
  	}

This week I stumbled across a similar problem that we don't document some of the Realm Admin endpoints that are dynamically added - see

This indicates to me that we should look for a different approach to solve this. Even if we redesign this API, the other Realm Admin endpoint will still give us a headache.

We could reach out to the https://github.com/smallrye/smallrye-open-api project to ask if there is an annotation we could add to indicate different possible subresoures or return types. IMHO in the case of the Realm Admin Subresources it won't help us much as those classes live in a different Maven module and are not known there at compile time, although it would help us here.

I searched the OpenAPI ecosystem, and found several tools which claim to merge OpenAPI specs. See https://github.com/robertmassaioli/openapi-merge?tab=readme-ov-file for one example. There also seems to be a Java Maven plugin, although it might be less popular: https://github.com/kpramesh2212/openapi-merger-plugin/tree/main/openapi-merger-maven-plugin

So I'd suggest a new Proof-of-concept: As the OpenAPI annotations in the Java Code don't seem to be a good fit here, create a manual OpenAPI spec for those parts and merge it with the automatically created spec. I would assume you could do that even locally without changing the Keycloak code, at least in the proof-of-concept mode.

If that proves to work, the next challenge would be to automate that in the Keycloak build: The Node plugin might not be a good fit in the Java build, and the Java Maven plugin doesn't seem to be popular and I didn't find something the main OpenAPI/Swagger project for that (might need to look again). So we would rather look into build our own Maven plugin which is then maintained in the Keycloak repository.

A possible future enhancement would then to migrate the manually created OpenAPI spec to something that is at least half-automated, or we can stick with merging an automatically generated and a second manually maintained file.

I know this is very different from what you originally suggested. I'd be happy to hear your thoughts on this about the possible advantages and disadvantages you see.