Skip to content

camel-keycloak: deprecate 11 documented headers that nothing reads - #29955

Merged
davsclaus merged 5 commits into
apache:mainfrom
Dhairya-007:fix/keycloak-deprecate-unread-headers
Nov 16, 2026
Merged

davsclaus merged 5 commits into
apache:mainfrom
Dhairya-007:fix/keycloak-deprecate-unread-headers

Conversation

@Dhairya-007

@Dhairya-007 Dhairya-007 commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Problem

KeycloakProducer reads every header it honours explicitly by constant - exchange.getIn().getHeader(KeycloakConstants.REALM_NAME, String.class) and so on. Of the 66 headers KeycloakConstants publishes with @Metadata, 11 appear nowhere in the main sources at all: not read, not written, not referenced from a test.

They are not obscure corners. Each sits beside one that does work, so the component docs read as if a whole set were supported when only part of it is:

header what actually carries the value
CamelKeycloakRoleId the role operations take CamelKeycloakRoleName
CamelKeycloakIdpId the identity provider operations take CamelKeycloakIdpAlias
CamelKeycloakResourceName, CamelKeycloakResourceType, CamelKeycloakResourceUri a ResourceRepresentation as the POJO request body
CamelKeycloakPolicyName, CamelKeycloakPolicyType a PolicyRepresentation as the POJO request body
CamelKeycloakPermissionName a PolicyRepresentation as the POJO request body
CamelKeycloakScopeName its representation as the POJO request body
CamelKeycloakCredentialType a CredentialRepresentation as the POJO request body
CamelKeycloakBatchSize nothing - see below

createResource is the clearest case. The docs offer CamelKeycloakResourceName, ...ResourceType and ...ResourceUri, and the producer does this:

if (getConfiguration().isPojoRequest()) {
    ResourceRepresentation resourceRepresentation = getPojoRequest(exchange, ResourceRepresentation.class);
    ...
} else {
    throw new IllegalArgumentException("Create resource requires POJO request with ResourceRepresentation");
}

So setting the three headers and sending the exchange fails with a message about a POJO request, with nothing to connect that to the headers the docs told you to use.

CamelKeycloakBatchSize is documented as "Batch size for bulk operations", but the bulk operations have no batching to size - bulkCreateUsers and its siblings walk the list and issue one call per element:

for (UserRepresentation user : users) {
    ...
    Response response = checkResponse(keycloakClient.realm(realmName).users().create(user), "createUser");

Fix

Deprecate the 11 constants, each with a deprecationNote naming what to use instead, the same treatment retentionPolicy got in #29709. The catalog then marks them deprecated and shows the note rather than advertising them as supported, and the constants themselves stay, so nothing stops compiling.

The alternative would be to implement them - make the create operations fall back to building the representation from headers when pojoRequest is off. That is a feature rather than a fix and I did not want to guess at the intended shape, but I am happy to do it instead if you would rather have the headers work than see them deprecated.

The regenerated keycloak.json files are included.

KeycloakProducer reads every header it honours explicitly by constant,
and 11 of the 66 headers KeycloakConstants publishes appear nowhere in
the main sources - not read, not written, not even in a test.

They are not arbitrary: each sits next to one that does work, so the
docs read as if a whole set were supported.

* CamelKeycloakRoleId - the role operations take CamelKeycloakRoleName
* CamelKeycloakIdpId - the identity provider operations take
  CamelKeycloakIdpAlias
* CamelKeycloakResourceName/Type/Uri, CamelKeycloakPolicyName/Type,
  CamelKeycloakPermissionName, CamelKeycloakScopeName,
  CamelKeycloakCredentialType - the authorization-services and
  credential operations take a representation as the POJO request body;
  createResource for instance throws "Create resource requires POJO
  request with ResourceRepresentation" when pojoRequest is off, and
  never looks at the headers
* CamelKeycloakBatchSize - the bulk operations iterate the whole list
  one element at a time; there is no batching to size

Each is deprecated with a deprecationNote naming what to use instead,
the way influxdb2's camelInfluxDB.RetentionPolicy was handled. The
constants stay, so nothing stops compiling.
@github-actions

Copy link
Copy Markdown
Contributor

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

  • First-time contributors require MANUAL approval for the GitHub Actions to run
  • You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
  • You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
  • Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

✅ Generated files are up to date

An earlier CI run reported uncommitted generated changes; the latest run no longer does.

@davsclaus davsclaus 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.

Thanks for the careful table. I grepped all 11 constants and their strings: only the declarations and the generated endpoint DSL refer to them, so the deprecation is justified. keycloak-producer.adoc already documents the POJO body for createResource, createResourcePolicy and createResourcePermission. A few notes are not quite accurate, though:

  1. PERMISSION_NAME (KeycloakConstants.java:149): createResourcePermission takes a ResourcePermissionRepresentation; only updateResourcePermission takes a PolicyRepresentation. The PR table says the same.
  2. SCOPE_NAME (:155): there are no authorization-scope operations at all. The client scope operations work without pojoRequest and take CamelKeycloakClientScopeName (see createClientScope), so the note could point there.
  3. CREDENTIAL_TYPE (:172): no credential operation takes a CredentialRepresentation body. getUserCredentials lists them, deleteUserCredential uses CamelKeycloakCredentialId, and resetUserPassword always builds a PASSWORD credential from CamelKeycloakUserPassword.
  4. KeycloakEndpointBuilderFactory (dsl/camel-endpointdsl/src/generated/...) needs regenerating so the 11 header methods get @Deprecated, as in #29709.
  5. Please add an entry to camel-4x-upgrade-guide-4_24.adoc.
  6. [Nit] The PR description cites #29667 for the influxdb precedent; that one is the kafka exactlyOnce PR. The influxdb2 deprecation was #29709.

Claude Code on behalf of davsclaus. This review was generated by an AI agent and may contain inaccuracies; please verify all suggestions before applying.

@github-actions github-actions Bot added the dsl label Nov 14, 2026

@gnodet-bot gnodet-bot 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.

The deprecation notes added to PERMISSION_NAME, SCOPE_NAME, and CREDENTIAL_TYPE contain inaccurate descriptions of how the component uses (or doesn't use) these headers. See inline comments for details.

Additionally, 11 headers are deprecated in this PR but no entry has been added to the upgrade guide (docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc or whichever is the current upgrade guide for the target release). Users of these headers need guidance on the migration path.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

🧪 CI tested the following changed modules:

  • catalog/camel-catalog
  • components/camel-keycloak
  • docs
  • dsl/camel-endpointdsl

🔁 1 test passed only after a retry on JDK 21 (1 retried attempt)

Recovered flaky tests on JDK 21 (1)
Module Test Failed attempts First failure
dsl/camel-jbang/camel-jbang-plugin-tui ArchitectureViewTest.showsGroupsWithTheirFacts 1 the first group is selected ==> expected: <group:billing> but was: <null>

ℹ️ These tests did not fail the build. Surefire retried them and they passed.
Retries are enabled project-wide by surefire.rerunFailingTestsCount in parent/pom.xml.


🔬 Scalpel shadow comparison — Scalpel: 9 of 726 tested, 24 compile-only — current: 9 all tested

Maveniverse Scalpel detected 9 affected modules (current approach: 9).

Skip-tests mode would test 9 modules (4 direct + 8 downstream), skip tests for 24 (generated code, meta-modules)

Modules Scalpel would test (9)
  • camel-jbang-mcp ← downstream of org.apache.camel:camel-catalog
  • camel-jbang-plugin-mcp ← downstream of org.apache.camel:camel-jbang-core
  • camel-jbang-plugin-tui ← downstream of org.apache.camel:camel-catalog
  • camel-jbang-plugin-validate ← downstream of org.apache.camel:camel-yaml-dsl-validator
  • camel-jbang-run ← downstream of org.apache.camel:camel-catalog
  • camel-keycloak ← components/camel-keycloak/src/generated/resources/META-INF/org/apache/camel/component/keycloak/keycloak.json, components/camel-keycloak/src/main/java/org/apache/camel/component/keycloak/KeycloakConstants.java
  • camel-launcher-container ← downstream of org.apache.camel:camel-launcher
  • camel-yaml-dsl-validator ← downstream of org.apache.camel:camel-catalog
  • camel-yaml-dsl-validator-maven-plugin ← downstream of org.apache.camel:camel-yaml-dsl-validator
Modules with tests skipped (24)
  • apache-camel
  • camel-allcomponents
  • camel-catalog-console
  • camel-catalog-maven
  • camel-catalog-suggest
  • camel-componentdsl
  • camel-endpointdsl-support
  • camel-itest
  • camel-jbang-core
  • camel-jbang-it
  • camel-jbang-main
  • camel-jbang-plugin-edit
  • camel-jbang-plugin-generate
  • camel-jbang-plugin-kubernetes
  • camel-jbang-plugin-test
  • camel-kamelet-main
  • camel-launcher
  • camel-report-maven-plugin
  • camel-route-parser
  • camel-yaml-dsl
  • camel-yaml-dsl-deserializers
  • camel-yaml-dsl-maven-plugin
  • coverage
  • dummy-component

ℹ️ Shadow mode — Scalpel observes but does not affect test execution. Learn more

All tested modules (36 modules, 6m 5s total)

Total reactor time: 6m 5s

Module Duration Status
Camel :: JBang :: MCP 59.6s SUCCESS
Camel :: YAML DSL :: Validator 30.6s SUCCESS
Camel :: JBang :: Run 28.9s SUCCESS
Camel :: JBang :: Plugin :: Validate 25.5s SUCCESS
Camel :: YAML DSL 25.3s SUCCESS
Camel :: Catalog :: Camel Catalog 25.1s SUCCESS
Camel :: JBang :: Plugin :: Kubernetes 23.5s SUCCESS
Camel :: Component DSL 19.8s SUCCESS
Camel :: Docs 16.4s SUCCESS
Camel :: JBang :: Plugin :: Testing 14.4s SUCCESS
Camel :: Kamelet Main 13.5s SUCCESS
Camel :: JBang :: Plugin :: Generate 10.5s SUCCESS
Camel :: Catalog :: Camel Report Maven Plugin 10.1s SUCCESS
Camel :: YAML DSL :: Deserializers 8.7s SUCCESS
Camel :: Assembly 8.4s SUCCESS
Camel :: Catalog :: Camel Route Parser 7.9s SUCCESS
Camel :: YAML DSL :: Validator Maven Plugin 7.3s SUCCESS
Camel :: All Components Sync point 5.9s SUCCESS
Camel :: JBang :: Plugin :: MCP 4.8s SUCCESS
Camel :: JBang :: Plugin :: Edit 3.7s SUCCESS
Camel :: YAML DSL :: Maven Plugins 3.0s SUCCESS
Camel :: Catalog :: Maven 2.4s SUCCESS
Camel :: Coverage 2.3s SUCCESS
Camel :: Catalog :: Suggest (deprecated) 1.8s SUCCESS
Camel :: Endpoint DSL :: Support 1.1s SUCCESS
Camel :: Catalog :: Dummy Component 1.0s SUCCESS
Camel :: Catalog :: Console 0.9s SUCCESS
Camel :: JBang :: Main 0.8s SUCCESS
Camel :: JBang :: Integration tests 0.8s SUCCESS
Camel :: Launcher :: Container 0.8s SUCCESS
Camel :: Endpoint DSL n/a
Camel :: Integration Tests n/a
Camel :: JBang :: Core n/a
Camel :: JBang :: Plugin :: TUI n/a
Camel :: Keycloak n/a
Camel :: Launcher n/a

Top 20 slowest modules:

  • Camel :: JBang :: MCP (59.6s)
  • Camel :: YAML DSL :: Validator (30.6s)
  • Camel :: JBang :: Run (28.9s)
  • Camel :: JBang :: Plugin :: Validate (25.5s)
  • Camel :: YAML DSL (25.3s)
  • Camel :: Catalog :: Camel Catalog (25.1s)
  • Camel :: JBang :: Plugin :: Kubernetes (23.5s)
  • Camel :: Component DSL (19.8s)
  • Camel :: Docs (16.4s)
  • Camel :: JBang :: Plugin :: Testing (14.4s)
  • Camel :: Kamelet Main (13.5s)
  • Camel :: JBang :: Plugin :: Generate (10.5s)
  • Camel :: Catalog :: Camel Report Maven Plugin (10.1s)
  • Camel :: YAML DSL :: Deserializers (8.7s)
  • Camel :: Assembly (8.4s)
  • Camel :: Catalog :: Camel Route Parser (7.9s)
  • Camel :: YAML DSL :: Validator Maven Plugin (7.3s)
  • Camel :: All Components Sync point (5.9s)
  • Camel :: JBang :: Plugin :: MCP (4.8s)
  • Camel :: JBang :: Plugin :: Edit (3.7s)

⚙️ View full build and test results

@davsclaus davsclaus 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.

Thanks, the Regen commit added @Deprecated to the 11 header methods in KeycloakEndpointBuilderFactory, so that point is done, and CI is green. The three notes and the upgrade guide from my earlier review are still open:

  1. KeycloakConstants.java:149-150 (PERMISSION_NAME): createResourcePermission takes a ResourcePermissionRepresentation; only updateResourcePermission takes a PolicyRepresentation.
  2. KeycloakConstants.java:155-156 (SCOPE_NAME): there are no authorization-scope operations. The client scope operations use CamelKeycloakClientScopeName, so the note could point there.
  3. KeycloakConstants.java:172-173 (CREDENTIAL_TYPE): no credential operation takes a CredentialRepresentation body. deleteUserCredential uses CamelKeycloakCredentialId, and resetUserPassword builds a password credential from CamelKeycloakUserPassword. After changing the notes, keycloak.json (component and catalog copy) and KeycloakEndpointBuilderFactory need regenerating once more.
  4. Please add an entry for the 11 deprecated headers to docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc.
  5. [Nit] The PR description still cites #29667 for the influxdb precedent; that one was #29709.

Claude Code on behalf of davsclaus. This review was generated by an AI agent and may contain inaccuracies; please verify all suggestions before applying.

…e entry

The three notes named the wrong reason:

- PERMISSION_NAME: createResourcePermission takes a
  ResourcePermissionRepresentation, not a PolicyRepresentation; only
  updatePermission and getPermissionById use that one, and they are keyed
  on PERMISSION_ID.
- SCOPE_NAME: there are no authorization-scope operations at all. The
  client scope operations read CLIENT_SCOPE_NAME.
- CREDENTIAL_TYPE: no credential operation takes a
  CredentialRepresentation body. getUserCredentials returns them,
  deleteUserCredential uses CREDENTIAL_ID, and resetUserPassword builds
  the representation itself from USER_PASSWORD.

Added a section to the 4.24 upgrade guide listing all eleven headers
with where each value belongs instead.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@Dhairya-007

Copy link
Copy Markdown
Contributor Author

All five done, thanks — the three notes were wrong as you and gnodet-bot describe.

  1. PERMISSION_NAME: now "createResourcePermission takes a ResourcePermissionRepresentation as the POJO request body, and the other permission operations identify the permission with CamelKeycloakPermissionId". PolicyRepresentation only shows up in updatePermission and getPermissionById, both keyed on PERMISSION_ID.
  2. SCOPE_NAME: now "there are no authorization-scope operations, and the client scope operations use CamelKeycloakClientScopeName" — the only scopeName read in the producer is from CLIENT_SCOPE_NAME.
  3. CREDENTIAL_TYPE: now "no credential operation takes a CredentialRepresentation request body. deleteUserCredential uses CamelKeycloakCredentialId, and resetUserPassword builds a password credential from CamelKeycloakUserPassword". resetUserPassword constructs the representation itself from USER_PASSWORD, and getUserCredentials only returns them.
  4. Added a === camel-keycloak section to camel-4x-upgrade-guide-4_24.adoc, as a two-column table of all eleven headers and where each value belongs instead.
  5. The PR description now cites camel-influxdb2: deprecate retentionPolicy, which has no effect #29709.

Regenerated the two keycloak.json files and the three header javadocs in KeycloakEndpointBuilderFactory.

@gnodet-bot gnodet-bot 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.

Following up on my earlier review — all previous findings have been addressed.

  • PERMISSION_NAME deprecation note — ✅ corrected: now accurately names ResourcePermissionRepresentation and CamelKeycloakPermissionId
  • SCOPE_NAME deprecation note — ✅ corrected: now says there are no authorization-scope operations and points to CamelKeycloakClientScopeName
  • CREDENTIAL_TYPE deprecation note — ✅ corrected: now explains that no credential operation takes a CredentialRepresentation body, and names the actual headers used
  • Upgrade guide entry — ✅ added: camel-4x-upgrade-guide-4_24.adoc now has a === camel-keycloak section with a two-column table of all 11 deprecated headers and their replacements
  • PR description citation — ✅ corrected: now references #29709 (the influxdb2 deprecation), not #29667

The generated files (keycloak.json × 2, KeycloakEndpointBuilderFactory.java) are consistent with the deprecations. LGTM.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

# Conflicts:
#	docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc

@davsclaus davsclaus 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.

Thanks @Dhairya-007, all the open points are in:

  • The three notes (PERMISSION_NAME, SCOPE_NAME, CREDENTIAL_TYPE) are now accurate, and keycloak.json (component and catalog copy) and KeycloakEndpointBuilderFactory are regenerated to match.
  • The upgrade guide has a table with all 11 headers and what to use instead. On this head, nothing outside KeycloakConstants and the generated files refers to any of the 11 constants.
  • The PR description now cites #29709.
  1. [Nit, optional] KeycloakConstants.java:150-151 and camel-4x-upgrade-guide-4_24.adoc:8919-8920: "the other permission operations identify the permission with CamelKeycloakPermissionId" holds for get, update and deleteResourcePermission. It does not hold for listResourcePermissions or evaluatePermission (which uses CamelKeycloakPermissionAudience, ...ResourceNames and ...Scopes). "get, update and deleteResourcePermission identify it with CamelKeycloakPermissionId" would be exact.

LGTM.

Claude Code on behalf of davsclaus. This review was generated by an AI agent and may contain inaccuracies; please verify all suggestions before applying.

@davsclaus

Copy link
Copy Markdown
Contributor

Thanks @Dhairya-007, this is approved and ready to merge, but it now conflicts with main. #29954 (camel-docker deprecations) was merged and also adds a section at the end of docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc, and #29955, #29958 and #29959 each do the same. Could you rebase on main and keep both sections? Once one of the three is merged the next one conflicts again in the same place, so rebasing all three now and merging them one at a time may need another rebase in between.

Claude Code on behalf of davsclaus

@davsclaus

Copy link
Copy Markdown
Contributor

Thanks, this is approved and green, but it now conflicts with main in docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc (other entries landed in the same place). Could you rebase on main and keep both sides of the upgrade guide? Then it can be merged.

Claude Code on behalf of davsclaus

@davsclaus

Copy link
Copy Markdown
Contributor

@Dhairya-007 thanks, this one is approved, but it now conflicts with main after today's merges of the other header PRs. Could you rebase it onto main, regenerate the generated files (catalog JSON and endpoint DSL), and force-push? We'll merge it once CI is green.

Claude Code on behalf of davsclaus

@gnodet-bot gnodet-bot 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.

Following up on my earlier review — all prior findings are addressed.

Previous findings status:

  • Inaccurate deprecationNote for PERMISSION_NAME: ✅ Fixed (now correctly references ResourcePermissionRepresentation)
  • Inaccurate deprecationNote for SCOPE_NAME: ✅ Fixed (now correctly references ClientScopeName and no auth-scope ops)
  • Inaccurate deprecationNote for CREDENTIAL_TYPE: ✅ Fixed (correctly states no CredentialRepresentation body)
  • Missing upgrade guide: ✅ Comprehensive table added to camel-4x-upgrade-guide-4_24.adoc

All 11 headers verified unused: KeycloakProducer.java reads none of them from exchange headers. @Deprecated annotations, deprecationNote values, and "deprecated": true in both catalog JSON copies are consistent for all 11 constants.

The optional PERMISSION_NAME nit from davsclaus (mentioning specific operations) is non-blocking and already noted by the maintainer who has APPROVED the PR. Ready to merge after rebase (merge conflict in the upgrade guide file).

This review was generated by an AI agent, Hermès on behalf of @gnodet.

@oscerd oscerd 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.

This is the largest of the set, so I spot-checked the claim rather than take the table on faith, and it stands up.

KeycloakProducer reads each header it honours by its constant, and the 11 flagged here are not among those reads. I checked ROLE_ID specifically: its only appearance in the main sources outside KeycloakConstants is the unrelated MISSING_ROLE_ID error-message string in the producer, not a getHeader(KeycloakConstants.ROLE_ID, ...), so the role operations really do take their id through the header the table names instead. The pattern the PR describes, a dead header sitting beside a working one so the table looks more complete than the component is, is the right thing to correct.

Each of the 11 is marked @Deprecated with a deprecationNote pointing at the header that actually carries the value, and there is an upgrade-guide entry, which is the correct path for public documented headers: keep them a cycle, mark them inert, name the replacement. The catalog, component JSON and endpoint-DSL regen are all included and CI is green, so the metadata is consistent. Good, careful cleanup.

Claude Code on behalf of oscerd

Resolves the conflict with main in the 4.24 upgrade guide (both entries kept).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Claus Ibsen <claus.ibsen@gmail.com>
@davsclaus
davsclaus merged commit b9bfe17 into apache:main Nov 16, 2026
7 checks passed
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.

5 participants