Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions docs/documentation/upgrading/topics/changes/changes-27_0_0.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -719,6 +719,26 @@ keytool -importcert -alias <server-alias> -file server.crt \

Deployments using CA-signed certificates or a truststore that already contains the server certificate are not affected.

=== Resource indicator audiences of OAuth Client ID Metadata Document clients follow the allow list
// https://github.com/keycloak/keycloak/issues/55131

When the experimental `cimd` and `resource-indicators` features are enabled, the `client-id-metadata-document` client policy executor adds an audience mapper to a client for each `resource` parameter value that it accepts.
Previously, this mapper was of the `Audience` type, which kept adding the value to the `aud` claim after the value was removed from the *Resource indicator allow list* option.
As a result, the client could still obtain access tokens for the removed resource, for example with the client credentials grant or a refresh token.

The executor now adds a mapper of the new `Audience (CIMD Resource Indicator)` type.
This mapper adds its value to the `aud` claim only while the allow lists of the executors that apply to the client allow the value.
Removing a value from an allow list therefore takes effect on the tokens that are issued afterwards, for all grant types.
The mapper adds its value when a token is issued, including a lightweight access token, and adds nothing when a token is introspected.
The token introspection response therefore reports the `aud` claim that the token was issued with.
The mapper stays on the client, so the value is added to the `aud` claim again if you add it to the allow list again.
The mapper is removed only when the executor rejects an authorization request of the client for that value.

During the upgrade, the existing mappers that the executor added to clients are converted to the new type in the database.
A client that you import from a representation exported from 26.8.x still has mappers of the `Audience` type, which add their value regardless of the allow list.
These mappers are converted when the client sends its next authorization request.
If a value is no longer allowed, remove the mappers whose name starts with `cimd-resource-indicator-` from the representation before you import it.

// ------------------------ Deprecated features ------------------------ //
== Deprecated features

Expand Down
2 changes: 1 addition & 1 deletion docs/guides/securing-apps/mcp-authz-server.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -214,7 +214,7 @@ To configure the executor, create a client policy profile in the {project_name}
* *Required properties*: A list of client metadata properties that must be present in the Client ID Metadata Document. If the fetched document does not include all the listed properties, the request is rejected.
* *Only Allow Confidential Client*: If `ON`, the executor only accepts a Client ID Metadata Document representing a confidential client. In this case, the client metadata must include either a `jwks` or `jwks_uri` property and must use `private_key_jwt` or `tls_client_auth` as the token endpoint authentication method.
* *Accept Public Client with Confidential-only Grant Types*: If `ON`, the executor accepts a Client ID Metadata Document representing a public client even if it includes grant types that can be used only by a confidential client (e.g., `urn:ietf:params:oauth:grant-type:jwt-bearer`). The executor excludes such grant types from the client metadata. If `OFF`, the executor rejects such a Client ID Metadata Document.
* *Resource indicator allow list*: A list of values of the `resource` parameter that the executor accepts (e.g., `+https://example.com/mcp+`). This option is only effective if the `resource-indicators` feature is enabled. If the `resource` parameter value of an authorization request is not included in this list, the executor rejects the request. If the authorization request does not include the `resource` parameter, the executor does not enforce this list. If the list is empty, no `resource` parameter value is accepted. For an accepted `resource` parameter value, the executor adds to the client an `Audience` mapper whose `Included Custom Audience` field is the value so that the `aud` claim of an access token includes it.
* *Resource indicator allow list*: A list of values of the `resource` parameter that the executor accepts (e.g., `+https://example.com/mcp+`). This option is only effective if the `resource-indicators` feature is enabled. If the `resource` parameter value of an authorization request is not included in this list, the executor rejects the request. If the authorization request does not include the `resource` parameter, the executor does not enforce this list. If the list is empty, no `resource` parameter value is accepted. For an accepted `resource` parameter value, the executor adds to the client an `Audience (CIMD Resource Indicator)` mapper whose `Included Custom Audience` field is the value so that the `aud` claim of an access token includes it. The mapper adds the value only while this list allows it, so removing a value from this list takes effect on the access tokens issued afterwards.
+
. Click *Save*.

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
/*
* Copyright 2026 Red Hat, Inc. and/or its affiliates
* and other contributors as indicated by the @author tags.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

package org.keycloak.connections.jpa.updater.liquibase.custom;

import java.sql.PreparedStatement;
import java.sql.ResultSet;

import liquibase.exception.CustomChangeException;
import liquibase.statement.core.UpdateStatement;
import liquibase.structure.core.Table;

/**
* Converts the audience mappers that the CIMD executor added to clients for the resources it accepted. They were of
* the generic audience mapper type, which adds the audience regardless of the resource indicator allow list, and
* become of the type that adds the audience only while the resource is allowed for the client.
*
* <p>The mappers are identified in the same way as the CIMD executor identified them: by their type and by the prefix
* of their name, both compared case-sensitively. A {@code LIKE} condition alone is not enough, because it is
* case-insensitive with the collations of some databases, and would also convert unrelated audience mappers whose
* name differs from the prefix only in case.
*/
public class JpaUpdate27_0_0_CimdResourceIndicatorAudienceMapper extends CustomKeycloakTask {

private static final String AUDIENCE_MAPPER = "oidc-audience-mapper";
private static final String CIMD_RESOURCE_INDICATOR_AUDIENCE_MAPPER = "oidc-cimd-resource-indicator-audience-mapper";
private static final String NAME_PREFIX = "cimd-resource-indicator-";

@Override
protected void generateStatementsImpl() throws CustomChangeException {
String protocolMapperTable = getTableName("PROTOCOL_MAPPER");
// the conditions only narrow down the candidates: the type and the name are checked below.
String sql = "SELECT ID, NAME, PROTOCOL_MAPPER_NAME FROM " + protocolMapperTable
+ " WHERE PROTOCOL_MAPPER_NAME = ? AND NAME LIKE ? AND CLIENT_ID IS NOT NULL";
int converted = 0;
try (PreparedStatement ps = connection.prepareStatement(sql)) {
ps.setString(1, AUDIENCE_MAPPER);
ps.setString(2, NAME_PREFIX + "%");
try (ResultSet rs = ps.executeQuery()) {
while (rs.next()) {
String id = rs.getString(1);
String name = rs.getString(2);
String protocolMapper = rs.getString(3);
if (name == null || !name.startsWith(NAME_PREFIX) || !AUDIENCE_MAPPER.equals(protocolMapper)) {
continue;
}
statements.add(new UpdateStatement(null, null, database.correctObjectName("PROTOCOL_MAPPER", Table.class))
.addNewColumnValue("PROTOCOL_MAPPER_NAME", CIMD_RESOURCE_INDICATOR_AUDIENCE_MAPPER)
.setWhereClause("ID=?").addWhereParameter(id));
converted++;
}
}
} catch (Exception e) {
throw new CustomChangeException(getTaskId() + ": Failed to convert the audience mappers added by the CIMD executor", e);
}
confirmationMessage.append("Converted " + converted + " audience mappers added by the CIMD executor");
}

@Override
protected String getTaskId() {
return "27.0.0-55131-cimd-resource-indicator-audience-mapper";
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -25,4 +25,11 @@
<customChange class="org.keycloak.connections.jpa.updater.liquibase.custom.JpaUpdate27_0_0_OidcIssuerMigration"/>
</changeSet>

<!-- The audience mappers that the CIMD executor added to clients for the resources it accepted were of the generic
audience mapper type, which adds the audience regardless of the resource indicator allow list. They are
converted to the type that adds the audience only while the resource is allowed for the client. -->
<changeSet author="keycloak" id="27.0.0-55131-cimd-resource-indicator-audience-mapper">
<customChange class="org.keycloak.connections.jpa.updater.liquibase.custom.JpaUpdate27_0_0_CimdResourceIndicatorAudienceMapper"/>
</changeSet>

</databaseChangeLog>
Original file line number Diff line number Diff line change
Expand Up @@ -91,13 +91,38 @@ public ClientPolicyVote applyPolicy(ClientPolicyContext context) throws ClientPo
logger.debugv("not URL: clientId = {0}", clientId);
return ClientPolicyVote.NO;
}
if (isUriSchemeMatched(uri) && isTrustedDomainMatched(uri)) return ClientPolicyVote.YES;
if (isUriSchemeMatched(configuration.getClientIdUriSchemes(), uri) && isTrustedDomainMatched(uri)) return ClientPolicyVote.YES;

return ClientPolicyVote.NO;
}

private boolean isUriSchemeMatched(URI uri) {
return configuration.getClientIdUriSchemes().stream().anyMatch(i->i.equals(uri.getScheme()));
/**
* Checks if a client ID matches a configuration of this condition, in the same way as on the
* {@code PRE_AUTHORIZATION_REQUEST} and {@code AUTHORIZATION_REQUEST_REDIRECT_URI} events, without considering
* the negative logic of the configuration. Unlike evaluating the condition on the events, it does not log a mismatch.
*
* @param configuration a configuration of this condition
* @param clientId a client ID
* @return {@code true} if the client ID matches the configuration
*/
public static boolean isClientIdMatched(Configuration configuration, String clientId) {
if (configuration == null || clientId == null || configuration.getClientIdUriSchemes() == null || configuration.getClientIdUriSchemes().isEmpty()) {
return false;
}
final URI uri;
try {
uri = new URI(clientId);
} catch (URISyntaxException e) {
return false;
}
if (!isUriSchemeMatched(configuration.getClientIdUriSchemes(), uri) || uri.getHost() == null) {
return false;
}
return convertContentFilledList(configuration.getTrustedDomains()).stream().anyMatch(i -> checkTrustedDomain(uri.getHost(), i));
}

private static boolean isUriSchemeMatched(List<String> clientIdUriSchemes, URI uri) {
return convertContentFilledList(clientIdUriSchemes).stream().anyMatch(i->i.equals(uri.getScheme()));
}

private boolean isTrustedDomainMatched(URI uri) {
Expand All @@ -121,15 +146,15 @@ private boolean isTrustedDomainMatched(URI uri) {
}

// return a list with non-null, non-blank, and distinct values. If the input list is null, return an empty list.
private List<String> convertContentFilledList(List<String> list) {
private static List<String> convertContentFilledList(List<String> list) {
if (list == null) {
return Collections.emptyList();
}
return list.stream().filter(Objects::nonNull).filter(i->!i.isBlank()).distinct().toList();
}

// apply the same logic in TrustedHostClientRegistrationPolicy.
private boolean checkTrustedDomain(String hostname, String trustedDomain) {
private static boolean checkTrustedDomain(String hostname, String trustedDomain) {
if (trustedDomain.startsWith("*.")) {
String domain = trustedDomain.substring(2);
return hostname.equals(domain) || hostname.endsWith("." + domain);
Expand Down
Loading
Loading