[admin-v2] Polymorphism, refined OIDC Client representation #44727

vmuzikar · 2025-12-06T19:47:05Z

Closes #43290

Couple of notes:

This PR both adds polymorphism (to handle different types) as well as some refinements to the OIDC Client rep based on the previous feedback.
- We could split this into separate PRs but seemed more natural to keep it in a single one as the polymorphism required some changes to the mapping logic.
Mapstruct was removed for the following reasons:
- I didn't find a way for it to generate mappers with base representations that would be overridden in child mappers, i.e. generate a specific OIDCClientModelMapper with generic methods like toModel(BaseClientRepresentation rep) that would in fact map specific OIDCClientRepresentation.
- Mapstruct excels in use cases that don't require too many custom and explicit mappings. This is not the case here, see the WIP version with more explicit mappings for comparison.
- It implicitly maps based on property names and types by default, this can lead some unintentional mappings and is to very clear when mixed with the explicit mappings via @Mapping.
To support the polymorphism in OpenAPI spec, some custom logic needed to be added to the filter.
- It basically does 2 things for both request payloads, and responses.
  - It replaces the generic base representations with specific ones listed in oneOf.
  - It adds the discriminator field if it's missing from the schema. This might happen when the discriminator field is handled only on the Jackson level and not part of the representation itself.
- The source of truth is Jackson annotations.
- SmallRye/Quarkus plans to add a native support for this in the future:
- The biggest caveat here is testability. Before we actually try and consume the spec with e.g. some generator, we don't know if it's correct.

Follow-ups:

Client v2 SAML representation #44853

mabartos · 2025-12-09T12:35:40Z

@vmuzikar Thanks for the PR! Spotless is failing.

mabartos · 2025-12-09T12:40:44Z

@vmuzikar Could you please provide some PR description of provided changes + caveats + what's necessary to complete to mark it as ready to review? Thanks

mabartos

Just a brief look.

rest/admin-v2/api/src/main/java/org/keycloak/models/mapper/AbstractRepModelMapper.java

mabartos · 2025-12-09T14:55:11Z

rest/admin-v2/api/src/main/java/org/keycloak/services/client/ClientService.java

+    Optional<BaseClientRepresentation> getClient(RealmModel realm, String clientId, ClientProjectionOptions projectionOptions);

-    Stream<ClientRepresentation> getClients(RealmModel realm, ClientProjectionOptions projectionOptions, ClientSearchOptions searchOptions, ClientSortAndSliceOptions sortAndSliceOptions);
+    Stream<BaseClientRepresentation> getClients(RealmModel realm, ClientProjectionOptions projectionOptions, ClientSearchOptions searchOptions, ClientSortAndSliceOptions sortAndSliceOptions);

-    Stream<ClientRepresentation> deleteClients(RealmModel realm, ClientSearchOptions searchOptions);
+    Stream<BaseClientRepresentation> deleteClients(RealmModel realm, ClientSearchOptions searchOptions);


Suggested change

Optional<BaseClientRepresentation> getClient(RealmModel realm, String clientId, ClientProjectionOptions projectionOptions);

Stream<ClientRepresentation> getClients(RealmModel realm, ClientProjectionOptions projectionOptions, ClientSearchOptions searchOptions, ClientSortAndSliceOptions sortAndSliceOptions);

Stream<BaseClientRepresentation> getClients(RealmModel realm, ClientProjectionOptions projectionOptions, ClientSearchOptions searchOptions, ClientSortAndSliceOptions sortAndSliceOptions);

Stream<ClientRepresentation> deleteClients(RealmModel realm, ClientSearchOptions searchOptions);

Stream<BaseClientRepresentation> deleteClients(RealmModel realm, ClientSearchOptions searchOptions);

Optional<? extends BaseClientRepresentation> getClient(RealmModel realm, String clientId, ClientProjectionOptions projectionOptions);

Stream<? extends BaseClientRepresentation> getClients(RealmModel realm, ClientProjectionOptions projectionOptions, ClientSearchOptions searchOptions, ClientSortAndSliceOptions sortAndSliceOptions);

Stream<? extends BaseClientRepresentation> deleteClients(RealmModel realm, ClientSearchOptions searchOptions);

Wouldn't it be better to use the wildcard of the type?

We'd need to do that on the REST layer too, I believe. And there we don't want it, IMHO.

shawkins · 2025-12-11T14:17:52Z

I started on the operator controller logic again based upon this pr - a couple of additional thoughts:

specialization via subclassing will require separate controllers for each type. I don't think this will be too much of an issue as the fabric8 client scales much better now in terms of the number of connections / watches it can run concurrently. However it does complicate the logic a little, and allows for name conflicts in the Kubernetes resources (without webhooks, you can have client type x and y with the same name).
Related to this is that top-level subclassing isn't the only way to address this. Rather than protocol being a string, it could be a complex type:

clientId: foo
protocol: 
 {name: saml}

So you would still have a oneOf stucture for the supported protocols, but you'd only need a single controller for all client types.

The only big reason not to do this is if we think that the client subclass somehow changes the behavior of base client fields (even removing them).

Also the CRD generator would not understand this directly, but we of course don't have to fully rely on that for generation in the first iteration and we'll eventually have fabric8io/kubernetes-client#7220 to make whatever manipulations we need.

vmuzikar · 2025-12-11T15:22:58Z

Added some notes to the desc, fixed spotless. This should be now ready for full review. Thanks.

vmuzikar · 2025-12-11T15:29:04Z

However it does complicate the logic a little, and allows for name conflicts in the Kubernetes resources (without webhooks, you can have client type x and y with the same name).

I think that's fine if we document it properly and add some clear error handling.

So you would still have a oneOf stucture for the supported protocols, but you'd only need a single controller for all client types.

Does it mean we'd have a single Client CR?

shawkins · 2025-12-11T15:52:01Z

Does it mean we'd have a single Client CR?

Yes it does.

The other way to do this without a structural schema, and which is supported by the CRD Generator, is to add each possible protocol as sibling fields. Like ValueOrSecret, or EnvFromSource, etc. The controller then validates that only 1 is populated.

EDIT: it is possible to have a single CR even with using the full subclassing. You can have the top-level of the CR spec as the structure part of the schema (or the representations as siblings). It's just not as typical of an approach.

vmuzikar · 2025-12-11T17:18:44Z

@shawkins IMHO separate CRs are a better approach than a single one. It's better UX for the users that they see only fields relevant to given client type. If the number of types gets out of our hands, we can always introduce a different approach l ike configmaps instead of CRs.

shawkins · 2025-12-11T18:07:52Z

IMHO separate CRs are a better approach than a single one. It's better UX for the users that they see only fields relevant to given client type.

After thinking more about the controller implementation, I'd prefer a single CRD. I could confirm in the openshift console how it presents structural schema in the editor if you are open to considering it.

vmuzikar · 2025-12-12T12:52:47Z

I could confirm in the openshift console how it presents structural schema in the editor

Ok, let's explore that.

shawkins · 2025-12-12T16:12:48Z

I could confirm in the openshift console how it presents structural schema in the editor

Ok, let's explore that.

After looking more into the structural schema capabilities, I'd say they are still limited.

The validation contructs anyOf, oneOf, etc. can only references properties, and those properties must be already defined in the schema. There is also no support the concept of a descriminator.

The above prevents us from doing something that looks like this:

clientId: foo
protocol: 
 {name: saml}

Instead you still have to use sibling properties:

clientId: foo
...
saml: {}

Even saml would probably still be typed as object to allow for future field specialization - but initially it would be ackward specifying it as an empty object.

The openshift editor of course won't prevent you from entering both siblings. If you try to save it with both populated, you'll get a message like: Error "Invalid value: "": "spec" must validate one and only one schema (oneOf). Found 2 valid alternatives" for field "<nil>" - which isn't exactly helpful.

So either I'm missing something obvious or the facilties for doing this still aren't that great.

vmuzikar · 2025-12-15T07:58:26Z

@shawkins Thanks for looking into this further. Sounds like the separate CRs is the way forward then?

vmuzikar · 2025-12-15T08:05:02Z

@shawkins @mabartos @Pepo48 Wanted to ask for the review here.

shawkins · 2025-12-15T11:55:32Z

@shawkins Thanks for looking into this further. Sounds like the separate CRs is the way forward then?

Yes, we'll have to create base controller logic and run a controller per type.

shawkins

Looks good. Just a couple of thoughts / nits.

I'm also not sure we need a model mapper provider yet as it's internal, not configurable, and has no alternative implementations - but it's not a deal breaker to leave in for now.

shawkins · 2025-12-15T17:07:53Z

quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/oas/OASModelFilter.java

+        PathItem sortedPathItem = OASFactory.createPathItem();
+
+        // Add operations order: GET -> POST -> PUT -> PATCH -> DELETE -> HEAD -> OPTIONS -> TRACE
+        if (pathItem.getGET() != null) {


Just a nit: null checks don't seem to be required.

This was introduced in some previous PR, I just moved things around. Seemed safer to check for nulls just in case there are some defaults for whatever reason in the newly created path item.

shawkins · 2025-12-15T17:17:38Z

rest/admin-v2/rest/src/main/java/org/keycloak/admin/api/client/DefaultClientApi.java

-    static void validateUnknownFields(ClientRepresentation rep) {
-        if (!rep.getAdditionalFields().isEmpty()) {
+    static void validateUnknownFields(BaseClientRepresentation rep) {
+        if (rep.getAdditionalFields().keySet().stream().anyMatch(k -> !k.equals(BaseClientRepresentation.DISCRIMINATOR_FIELD))) {


If having the protocol field not be part of the schema is causing it to be parsed into the additionalFields, perhaps we should just have it as a proper field.

I'm more inclined to keep as is, not to have arbitrary discriminator fields directly in the representation. We can (and most probably will) revisit as a follow-up.

If someone uses these classes on the client side, they'll have to do something similar if they want to check for unknown fields.

Ok, created #45047 so we can address it as a follow-up if you don't mind.

vmuzikar · 2025-12-19T15:02:24Z

@shawkins Thank you for the review!

I'm also not sure we need a model mapper provider yet as it's internal, not configurable, and has no alternative implementations - but it's not a deal breaker to leave in for now.

The motivation was that I expected the client types to be extendible, so I wanted to implement it in the most generic way possible.

Closes keycloak#43290 Signed-off-by: Václav Muzikář <[email protected]>

Signed-off-by: Václav Muzikář <[email protected]>

…#44727) * [admin-v2] Polymorphism, refined OIDC Client representation Closes keycloak#43290 Signed-off-by: Václav Muzikář <[email protected]> * Remove AbstractRepModelMapper Signed-off-by: Václav Muzikář <[email protected]> --------- Signed-off-by: Václav Muzikář <[email protected]> Signed-off-by: sar <[email protected]>

vmuzikar force-pushed the client-v2-representations-2 branch 3 times, most recently from f2a27e2 to 437966d Compare December 8, 2025 07:58

mabartos reviewed Dec 9, 2025

View reviewed changes

vmuzikar force-pushed the client-v2-representations-2 branch from 437966d to d0d6d65 Compare December 10, 2025 16:16

vmuzikar mentioned this pull request Dec 11, 2025

Client v2 SAML representation #44853

Open

vmuzikar force-pushed the client-v2-representations-2 branch from 7a11367 to 4f9354c Compare December 11, 2025 15:19

vmuzikar marked this pull request as ready for review December 11, 2025 15:23

vmuzikar requested review from a team as code owners December 11, 2025 15:23

keycloak-github-bot bot added team/cloud-native labels Dec 11, 2025

vmuzikar force-pushed the client-v2-representations-2 branch from 4f9354c to 7717db7 Compare December 11, 2025 17:12

shawkins approved these changes Dec 15, 2025

View reviewed changes

vmuzikar force-pushed the client-v2-representations-2 branch from 7717db7 to ade9bd8 Compare December 19, 2025 15:03

vmuzikar enabled auto-merge (squash) December 19, 2025 15:03

vmuzikar added 2 commits December 19, 2025 16:56

[admin-v2] Polymorphism, refined OIDC Client representation

1ec199a

Closes keycloak#43290 Signed-off-by: Václav Muzikář <[email protected]>

Remove AbstractRepModelMapper

13754b1

Signed-off-by: Václav Muzikář <[email protected]>

vmuzikar force-pushed the client-v2-representations-2 branch from ade9bd8 to 13754b1 Compare December 19, 2025 15:56

vmuzikar mentioned this pull request Dec 19, 2025

Consider having the explicit discriminator field in Client v2 representations #45047

Open

vmuzikar disabled auto-merge January 6, 2026 15:15

vmuzikar enabled auto-merge (squash) January 6, 2026 15:15

shawkins self-requested a review January 6, 2026 15:15

shawkins approved these changes Jan 6, 2026

View reviewed changes

vmuzikar disabled auto-merge January 6, 2026 15:23

vmuzikar merged commit ed69f33 into keycloak:main Jan 6, 2026
86 checks passed

vmuzikar deleted the client-v2-representations-2 branch January 6, 2026 15:23

mabartos mentioned this pull request Jan 7, 2026

[admin-api-v2] Cannot list all available clients #45215

Open

2 tasks

vmuzikar mentioned this pull request Jan 9, 2026

Review test coverage for Client v2 #45277

Open

[admin-v2] Polymorphism, refined OIDC Client representation #44727

[admin-v2] Polymorphism, refined OIDC Client representation #44727

Uh oh!

Conversation

vmuzikar commented Dec 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mabartos commented Dec 9, 2025

Uh oh!

mabartos commented Dec 9, 2025

Uh oh!

mabartos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shawkins commented Dec 11, 2025

Uh oh!

vmuzikar commented Dec 11, 2025

Uh oh!

vmuzikar commented Dec 11, 2025

Uh oh!

shawkins commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vmuzikar commented Dec 11, 2025

Uh oh!

shawkins commented Dec 11, 2025

Uh oh!

vmuzikar commented Dec 12, 2025

Uh oh!

shawkins commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vmuzikar commented Dec 15, 2025

Uh oh!

vmuzikar commented Dec 15, 2025

Uh oh!

shawkins commented Dec 15, 2025

Uh oh!

shawkins left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vmuzikar commented Dec 19, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vmuzikar commented Dec 6, 2025 •

edited

Loading

shawkins commented Dec 11, 2025 •

edited

Loading

shawkins commented Dec 12, 2025 •

edited

Loading