Repository navigation
Conversation
Contributor
There was a problem hiding this comment.
🟡 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
force-pushed
the
ISSUE-55131-stale-resource-aud-mapper
branch
from
November 18, 2026 08:35
99b1cfa to
6653bc7
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
closes #55131
Architecture
The root cause was that an accepted
resourcewas recorded on the client as a persistentAudiencemapper, 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.client-id-metadata-documentexecutor no longer adds or removes protocol mappers. On an authorization request it only checks theresourceparameter against its allow list.TokenPostProcessorruns when an access token is built. If the token is bound to a resource (theresourceparameter 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.invalid_target) or approves it, and only an approved resource is added toaud.ResourceIndicatorsPostProcessorthen resolves the resource against the audience as for any other client.Policy applicability is deliberately left to
DefaultClientPolicyManagerrather 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
resource, or name another still-allowed resource: there is no mapper left to add the removed resource, so the resulting token cannot contain it.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
resourcevalue 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 aresourcevalue. This is described in the upgrading guide.Audiencemappers whose name starts withcimd-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 remainingAudienceorAudience Resolvemapper 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 thecimdfeature is enabled, so the upgrading guide asks administrators to remove these mappers themselves if they disable the feature.offline_accessscope recreates the client session context, which dropped the resource binding. The 26.8 mapper masked this for CIMD clients, so it is fixed here inResourceIndicatorsPostProcessorandTokenManager. This affects every user of theresource-indicatorsfeature, not only CIMD, and has its own entry in the upgrading guide.ClientPolicyEvent.CIMD_RESOURCE_INDICATORis added toserver-spi. A dedicated event was preferred over makingClientIdUriSchemeConditionvote 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.reject-requestexecutor ignores it, as it already ignoresAUTHORIZATION_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 agrant-typecondition 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.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.ClientIdMetadataDocumentTestcovers the refresh token, client credentials, offline token, omittedresource, multiple policies, areject-requestpolicy for another grant type, and 26.8 mapper cases, including a value that an administrator-configured mapper adds as well;ResourceIndicatorsTestcovers the offline token fix for a client not managed by CIMD.