Skip to content

fix: adding defaults for boolean and several string values - #55168

Open
shawkins wants to merge 2 commits into
keycloak:mainfrom
shawkins:iss49038
Open

shawkins wants to merge 2 commits into
keycloak:mainfrom
shawkins:iss49038

Conversation

@shawkins

@shawkins shawkins commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

closes: #49038

Defaults were not yet added for limit / offset since there are other issues dealing with that.

@keycloak/cloud-native there are two approaches here:

  1. This PR shows a breaking change to better mimic v1 behavior. For most existing users this would follow the principle of least surprise - and presumes that the v1 defaults are good.
  2. Keep the existing v2 behavior and advertise all false booleans, and make clean-ups as needed to preserve defaults in PUT/PATCH situations. This is consistent for users who would be starting fresh with v2, but likely means that users will need to manually set for fields as the false defaults are not widely applicable.

I think we also briefly talked about one of the phases of request processing being a "defaulting service" (similar to kubernetes), but we never created anything formal for that. A more common service could be considered should we want to better capture / align the v1 and v2 logic. The approach here is to have a separate set of defaulting logic for v2.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Advertised true defaults conflict with actual omission/null behavior for enabled and several SAML settings, potentially misleading callers into disabling clients or document signing.

2 open issues
What changed in this PR

This PR adds default-value metadata to Admin API v2 client schemas to clarify nullable-field behavior for #49038. It changes schema documentation, not runtime default handling.

Changes:

  • Adds defaults for shared enabled and SAML boolean, enum, and string settings.
  • Updates the JavaScript admin client’s OpenAPI specification to match.
File Description
rest/​admin-v2/​api/​src/​main/​java/​org/​keycloak/​representations/​admin/​v2/​SAMLClientRepresentation.java Adds schema defaults for SAML configuration fields.
rest/​admin-v2/​api/​src/​main/​java/​org/​keycloak/​representations/​admin/​v2/​BaseClientRepresentation.java Adds a schema default for client enabled state.
js/​libs/​keycloak-admin-client/​openapi.json Reflects the new defaults in the client-generation specification.

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

PATCHing frontChannelLogout to null can bypass the realm’s secure-logout policy and persist true, enabling a setting the policy forbids.

3 open issues
2 resolved since last review

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

PATCH defaulting can overwrite an omitted NameID format and enable signature verification without a usable key, unexpectedly changing SAML behavior and causing requests to fail.

1 open issue
3 resolved since last review

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

SAML PUTs with required client signatures and an omitted signing certificate regenerate the certificate on every retry, violating idempotency and unexpectedly rotating trust material.

3 open issues
1 resolved since last review

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Updates can require SAML request signatures without provisioning or retaining a verification certificate, causing subsequent requests to fail signature verification.

1 open issue
3 resolved since last review

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

PUT updates can enable signature verification while removing the required certificate, breaking subsequent SAML requests, and PATCH does not reliably reset an explicitly null NameID format to the default.

2 open issues
1 resolved since last review

Review effort: Balanced

@shawkins
shawkins marked this pull request as ready for review November 16, 2026 13:33
@shawkins
shawkins requested review from a team as code owners November 16, 2026 13:33
Copilot AI balanced review requested due to automatic review settings November 16, 2026 13:33

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The new signature default breaks an existing interoperability test, and validation still accepts whitespace-only metadata URLs without a certificate, leaving request verification unusable.

2 open issues
2 resolved since last review

Review effort: Balanced

Copilot AI balanced review requested due to automatic review settings November 16, 2026 13:55

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The API guide needs to clarify that PATCHing auth.secret to null regenerates the secret for secret-authenticated OIDC clients, while auth: null makes the client public and clears its secret.

1 open issue
2 resolved since last review

Review effort: Balanced

Comment thread docs/guides/admin-api/admin-api-v2.adoc Resolved
also adding attribute name constants

closes: keycloak#49038

Signed-off-by: Steve Hawkins <shawkins@redhat.com>
Copilot AI balanced review requested due to automatic review settings November 16, 2026 14:27

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The documentation omits that secret-based OIDC PUT requests require a non-blank auth.secret, potentially misleading callers into expecting automatic secret generation when omitted or null values instead return HTTP 400.

1 open issue
1 resolved since last review

Review effort: Balanced

Comment thread docs/guides/admin-api/admin-api-v2.adoc Resolved
Clarified behavior of omitted fields in PUT requests and added requirement for auth.secret in OIDC authentication.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Signed-off-by: Steven Hawkins <shawkins@redhat.com>
Copilot AI balanced review requested due to automatic review settings November 16, 2026 14:39

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues were identified for the client-defaulting and PUT/PATCH semantics changes.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Model vs representation primitive handling

2 participants