Skip to content

[CIMD] Stale resource audience mapper persists after allowlist tightening - #55298

Open
tnorimat wants to merge 1 commit into
keycloak:mainfrom
Hitachi:ISSUE-55131-stale-resource-aud-mapper
Open

tnorimat wants to merge 1 commit into
keycloak:mainfrom
Hitachi:ISSUE-55131-stale-resource-aud-mapper

Conversation

@tnorimat

@tnorimat tnorimat commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

closes #55131

Architecture

The root cause was that an accepted resource was recorded on the client as a persistent Audience mapper, so the grant outlived the allow list that justified it. This PR removes that persisted state instead of trying to keep it synchronized: the decision is taken again for every access token, against the current configuration.

  • The client-id-metadata-document executor no longer adds or removes protocol mappers. On an authorization request it only checks the resource parameter against its allow list.
  • A CIMD-specific TokenPostProcessor runs when an access token is built. If the token is bound to a resource (the resource parameter of the token request, otherwise the one of the authorization code or of the refresh token), it raises a new client policy event, CIMD_RESOURCE_INDICATOR.
  • The regular client policy framework selects the policies that apply to the client. Each applicable CIMD executor either rejects the resource (invalid_target) or approves it, and only an approved resource is added to aud. ResourceIndicatorsPostProcessor then resolves the resource against the audience as for any other client.

Policy applicability is deliberately left to DefaultClientPolicyManager rather than re-implemented, so conditions, negative logic, strict mode, global profiles, and multiple policies behave exactly as they do for every other client policy event. When several CIMD executors apply, all of them have to allow the resource, which is the same rule as on the authorization request.

How this resolves the issue

  • Client credentials requests: the allow list is now consulted at the token endpoint, so a removed resource is rejected when requested and is not added otherwise.
  • Authorization requests that omit resource, or name another still-allowed resource: there is no mapper left to add the removed resource, so the resulting token cannot contain it.
  • Refresh token requests: a refresh token bound to a removed resource is rejected with invalid_target.

Removing a value from the allow list takes effect on the next token request, and adding it back takes effect equally immediately, without a new authorization request. The design fails closed: if no CIMD executor applies to the client (policy disabled, client policies disabled, feature disabled), nothing approves the resource and it is not issued.

Notes

  • Behaviour change: an access token is issued for a resource only when the token request is bound to it. A token requested without any resource value no longer carries the values accepted earlier, and neither does an access token returned directly from the authorization endpoint (implicit and hybrid flows), because those are not bound to a resource value. This is described in the upgrading guide.
  • Mappers created by 26.8: Audience mappers whose name starts with cimd-resource-indicator- are removed from a client when the next access token is issued to it, in the same transaction. Their audiences are taken out of that token, unless a remaining Audience or Audience Resolve mapper adds the same value. This was chosen over a database migration so that clients imported from a 26.8 representation are covered as well. It only runs while the cimd feature is enabled, so the upgrading guide asks administrators to remove these mappers themselves if they disable the feature.
  • Offline tokens: refreshing a refresh token with the offline_access scope recreates the client session context, which dropped the resource binding. The 26.8 mapper masked this for CIMD clients, so it is fixed here in ResourceIndicatorsPostProcessor and TokenManager. This affects every user of the resource-indicators feature, not only CIMD, and has its own entry in the upgrading guide.
  • New SPI value: ClientPolicyEvent.CIMD_RESOURCE_INDICATOR is added to server-spi. A dedicated event was preferred over making ClientIdUriSchemeCondition vote on the existing token endpoint events, because that would change which executors run in existing policies that combine this condition with others. The condition's votes on existing events are unchanged.
  • Other policies and the new event: the event is delivered to every enabled policy, like any client policy event. The reject-request executor ignores it, as it already ignores AUTHORIZATION_REQUEST_REDIRECT_URI, because the event is a check made while a token is built and not a request; the token request it belongs to is still rejected on its own event. It is the only built-in executor that acts on events it does not know. The grant type is deliberately not evaluated on this event: a CIMD policy with a grant-type condition already applies to the authorization request regardless of that condition, and it has to keep checking the allow list for every grant that can issue the resource.
  • Known limitations, accepted for this fix: a value that a 26.8 mapper adds and that only another kind of mapper adds as well (for example a script mapper writing aud) is lost for that single token; and two concurrent first token requests of the same client after the upgrade can both try to delete the same mapper, in which case one of them may fail and has to be retried.
  • Tests: ClientIdMetadataDocumentTest covers the refresh token, client credentials, offline token, omitted resource, multiple policies, a reject-request policy for another grant type, and 26.8 mapper cases, including a value that an administrator-configured mapper adds as well; ResourceIndicatorsTest covers the offline token fix for a client not managed by CIMD.

@tnorimat
tnorimat requested a review from a team as a code owner November 18, 2026 08:04
Copilot AI balanced review requested due to automatic review settings November 18, 2026 08:04

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

Policy evaluation can reject valid client-credentials requests despite grant restrictions, and legacy audience cleanup can remove legitimate audiences from the first post-upgrade token.

2 open issues
What changed in this PR

This PR addresses #55131 by moving CIMD resource-audience enforcement from persistent client mappers to token issuance, so allowlist changes apply to subsequent token requests.

Changes:

  • Adds a token post-processor and policy event to validate resources and remove legacy audience mappers.
  • Preserves resource binding across offline-token refreshes.
  • Adds regression coverage and documents the behavior and upgrade implications.
File Description
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​oauth/​ResourceIndicatorsTest.java Tests resource binding across offline refreshes.
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​client/​policies/​ClientIdMetadataDocumentTest.java Tests allowlist changes, policy matching, and legacy cleanup.
services/​src/​main/​resources/​META-INF/​services/​org.keycloak.protocol.oidc.token.TokenPostProcessorFactory Registers the CIMD post-processor.
services/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​TokenManager.java Preserves the requested resource during offline refresh.
services/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​resourceindicators/​ResourceIndicatorsPostProcessor.java Recognizes refresh-token binding independently of the grant attribute.
services/​src/​main/​java/​org/​keycloak/​protocol/​oauth2/​cimd/​resourceindicators/​CimdResourceIndicatorPostProcessorFactory.java Configures post-processor ordering and feature gating.
services/​src/​main/​java/​org/​keycloak/​protocol/​oauth2/​cimd/​resourceindicators/​CimdResourceIndicatorPostProcessor.java Checks resource approval and removes legacy mappers.
services/​src/​main/​java/​org/​keycloak/​protocol/​oauth2/​cimd/​clientpolicy/​executor/​AbstractClientIdMetadataDocumentExecutorFactory.java Updates allowlist configuration help text.
services/​src/​main/​java/​org/​keycloak/​protocol/​oauth2/​cimd/​clientpolicy/​executor/​AbstractClientIdMetadataDocumentExecutor.java Replaces mapper installation with token-time validation.
services/​src/​main/​java/​org/​keycloak/​protocol/​oauth2/​cimd/​clientpolicy/​context/​CimdResourceIndicatorContext.java Carries the client, resource, and approval state.
services/​src/​main/​java/​org/​keycloak/​protocol/​oauth2/​cimd/​clientpolicy/​condition/​ClientIdUriSchemeCondition.java Handles the new event and normalizes scheme configuration.
server-spi/​src/​main/​java/​org/​keycloak/​services/​clientpolicy/​ClientPolicyEvent.java Defines the resource-validation event.
docs/​guides/​securing-apps/​mcp-authz-server.adoc Explains token-time allowlist enforcement.
docs/​documentation/​upgrading/​topics/​changes/​changes-27_0_0.adoc Documents legacy cleanup and offline-refresh changes.

Review effort: Balanced

…ning

closes keycloak#55131

Signed-off-by: Takashi Norimatsu <takashi.norimatsu.ws@hitachi.com>
@tnorimat
tnorimat force-pushed the ISSUE-55131-stale-resource-aud-mapper branch from 99b1cfa to 6653bc7 Compare November 18, 2026 08:35
Copilot AI balanced review requested due to automatic review settings November 18, 2026 08:35

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 block the change to token-time resource-audience enforcement.

No open issues 🎉

2 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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[CIMD] Stale resource audience mapper persists after allowlist tightening

2 participants