Skip to content
Open
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
1 change: 1 addition & 0 deletions docs/guides/securing-apps/mcp-authz-server.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -212,6 +212,7 @@ To configure the executor, create a client policy profile in the {project_name}
* *Trusted domains*: A list of domain patterns (wildcard) that the executor accepts for the Client ID URL and Client Metadata URL properties. For example, use `*.example.org` to accept any subdomain of `example.org`. If empty, all domains are denied.
* *Restrict same domain*: If `ON`, the executor verifies that the Client ID URL and Redirect URI in an authorization request, as well as URL-valued properties of the client metadata, are all under the same trusted domain.
* *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.
* *Client scope allow list*: A list of names of realm client scopes that a client registered from a Client ID Metadata Document is allowed to have as optional client scopes (e.g., `mcp:tools`). The executor removes any scope name in the `scope` property of the Client ID Metadata Document that is not included in this list before the client is created or updated. Moreover, on every authorization request, the executor removes from the client any optional client scope that is not included in this list, including realm default optional client scopes and client scopes added by an administrator. Default client scopes are not affected. If the list is empty, the client has no optional client scope.
* *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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
import org.keycloak.http.simple.SimpleHttpRequest;
import org.keycloak.http.simple.SimpleHttpResponse;
import org.keycloak.models.ClientModel;
import org.keycloak.models.ClientScopeModel;
import org.keycloak.models.KeycloakSession;
import org.keycloak.models.ProtocolMapperModel;
import org.keycloak.models.RealmModel;
Expand Down Expand Up @@ -150,6 +151,8 @@ public static class Configuration extends ClientPolicyExecutorConfigurationRepre
protected boolean restrictSameDomain = false;
@JsonProperty(AbstractClientIdMetadataDocumentExecutorFactory.REQUIRED_PROPERTIES)
protected List<String> requiredProperties = null;
@JsonProperty(AbstractClientIdMetadataDocumentExecutorFactory.CLIENT_SCOPE_ALLOW_LIST)
protected List<String> clientScopeAllowList = null;

// Resource Indicators (RFC 8707) allow list
@JsonProperty(AbstractClientIdMetadataDocumentExecutorFactory.RESOURCE_INDICATOR_ALLOW_LIST)
Expand Down Expand Up @@ -198,6 +201,14 @@ public void setRequiredProperties(List<String> requiredProperties) {
this.requiredProperties = requiredProperties;
}

public List<String> getClientScopeAllowList() {
return clientScopeAllowList;
}

public void setClientScopeAllowList(List<String> clientScopeAllowList) {
this.clientScopeAllowList = clientScopeAllowList;
}

public List<String> getResourceIndicatorAllowList() {
return resourceIndicatorAllowList;
}
Expand Down Expand Up @@ -400,16 +411,20 @@ private void process(PreAuthorizationRequestContext preAuthorizationRequestConte
validateClientId(clientIdURI);

if (fetchOp == FetchOperation.NO_UPDATE) {
// no update, but the resource parameter still needs to be enforced on every authorization request.
enforceResourceIndicator(preAuthorizationRequestContext, session.getContext().getRealm().getClientByClientId(clientId));
// no update, but the client scope allow list and the resource parameter still need to be enforced on every authorization request.
ClientModel existingClientModel = session.getContext().getRealm().getClientByClientId(clientId);
enforceClientScopeAllowList(existingClientModel);
enforceResourceIndicator(preAuthorizationRequestContext, existingClientModel);
return;
}

// fetch Client ID Metadata
OIDCClientRepresentationWithCacheControl clientOIDCWithCacheControl = fetchClientMetadata(clientIdURI, fetchOp == FetchOperation.UPDATE, provider);
if (clientOIDCWithCacheControl == null) {
// fetched but no update
enforceResourceIndicator(preAuthorizationRequestContext, session.getContext().getRealm().getClientByClientId(clientId));
ClientModel existingClientModel = session.getContext().getRealm().getClientByClientId(clientId);
enforceClientScopeAllowList(existingClientModel);
enforceResourceIndicator(preAuthorizationRequestContext, existingClientModel);
return;
}

Expand All @@ -419,6 +434,9 @@ private void process(PreAuthorizationRequestContext preAuthorizationRequestConte
// Client Metadata validation
validateClientMetadata(clientIdURI, redirectUriURI, clientOIDCWithCacheControl.getOidcClientRepresentation());

// Client scope allow list: called here, not from validateClientMetadata, so that it cannot be skipped by overriding it
enforceClientScopeAllowList(clientOIDCWithCacheControl.getOidcClientRepresentation());

ClientModel clientModel;
if (fetchOp == FetchOperation.CREATE) {
// Create Client Metadata
Expand All @@ -428,6 +446,10 @@ private void process(PreAuthorizationRequestContext preAuthorizationRequestConte
clientModel = provider.updateClientMetadata(clientOIDCWithCacheControl);
}

// the client can obtain optional client scopes not from the scope property, e.g. realm default optional client scopes
// on creation, or the previously persisted ones on update when the scope property is absent.
enforceClientScopeAllowList(clientModel);

enforceResourceIndicator(preAuthorizationRequestContext, clientModel);
}

Expand Down Expand Up @@ -925,6 +947,68 @@ protected void validateClientMetadata(final URI clientIdURI, final URI redirectU
throw invalidClientIdMetadata(ERR_METADATA_NO_REQUIRED_PROPERTIES);
}
}

}

/**
* Restricts the client scopes that the {@code scope} property of a client metadata can attach to the client.
*
* <p>The {@code scope} property is converted to optional client scopes of the client, which are linked to any
* existing realm client scope by its name. To prevent a client metadata from attaching a client scope that an
* administrator does not intend for clients registered by CIMD, the scope names not included in the client scope
* allow list are removed from the {@code scope} property before the client is created or updated.
* If the allow list is vacant, no client scope is attached by the {@code scope} property.
*
* @param clientOIDC a client metadata
*/
protected void enforceClientScopeAllowList(final OIDCClientRepresentation clientOIDC) {
String scope = clientOIDC.getScope();
if (scope == null) {
return;
}
List<String> allowList = convertContentFilledList(getConfiguration().getClientScopeAllowList());
List<String> requested = Arrays.stream(scope.trim().split("\\s+")).filter(i -> !i.isBlank()).distinct().toList();
List<String> allowed = requested.stream().filter(allowList::contains).toList();
if (allowed.size() != requested.size()) {
RealmModel realm = session.getContext().getRealm();
List<String> removed = requested.stream().filter(i -> !allowList.contains(i)).toList();
// only warn about names of existing realm client scopes, others (e.g. "openid") would never be attached anyway
List<String> removedClientScopes = removed.stream().filter(i -> KeycloakModelUtils.getClientScopeByName(realm, i) != null).toList();
if (!removedClientScopes.isEmpty()) {
getLogger().warnv("client metadata includes client scopes not allowed, they are removed: clientId = {0}, scopes = {1}",
clientOIDC.getClientId(), removedClientScopes);
} else {
getLogger().debugv("client metadata includes scopes not allowed, they are removed: clientId = {0}, scopes = {1}",
clientOIDC.getClientId(), removed);
}
}
clientOIDC.setScope(String.join(" ", allowed));
}

/**
* Removes the optional client scopes not included in the client scope allow list from a client managed by CIMD.
*
* <p>A client managed by CIMD can have an optional client scope that does not come from the {@code scope} property
* of its client metadata, e.g. a realm default optional client scope attached on creation when the {@code scope}
* property is absent, or a client scope persisted before the allow list was changed. The method is called on every
* authorization request so that the allow list is the only source of optional client scopes of such a client,
* even while its persisted client metadata is still effective.
*
* @param clientModel a client managed by CIMD
*/
protected void enforceClientScopeAllowList(final ClientModel clientModel) {
if (clientModel == null) {
return;
}
List<String> allowList = convertContentFilledList(getConfiguration().getClientScopeAllowList());
List<ClientScopeModel> notAllowed = clientModel.getClientScopes(false).values().stream()
.filter(i -> !allowList.contains(i.getName()))
.toList();
for (ClientScopeModel clientScope : notAllowed) {
getLogger().debugv("optional client scope not allowed, it is removed: clientId = {0}, scope = {1}",
clientModel.getClientId(), clientScope.getName());
clientModel.removeClientScope(clientScope);
}
}

// unique name prefix for the protocol mappers added below; the resource value itself is matched via the
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
* <ul>
* <li>Restrict same domain: only allow {client_id} and {redirect_uri} parameter of an authorization request whose hostname is under the one of the permitted domain (wildcard * can be used)</li>
* <li>Required properties: only allow a client metadata that includes all required properties</li>
* <li>Client scope allow list: only allow the scope property of a client metadata to attach the client scopes included in the allow list</li>
* </ul>
* <li>Resource Indicators (RFC 8707) support</li>
* <ul>
Expand All @@ -49,6 +50,7 @@ public abstract class AbstractClientIdMetadataDocumentExecutorFactory
// Client Metadata Validation
public static final String REQUIRED_PROPERTIES = "cimd-required-properties";
public static final String RESTRICT_SAME_DOMAIN = "cimd-restrict-same-domain";
public static final String CLIENT_SCOPE_ALLOW_LIST = "cimd-client-scope-allow-list";

// Resource Indicators (RFC 8707) support
public static final String RESOURCE_INDICATOR_ALLOW_LIST = "cimd-resource-indicator-allow-list";
Expand Down Expand Up @@ -134,6 +136,18 @@ static protected void addCommonConfigProperties(List<ProviderConfigProperty> con
null);
configProperties.add(property);

property = new ProviderConfigProperty(
CLIENT_SCOPE_ALLOW_LIST,
"Client scope allow list",
"Names of the realm client scopes that a client registered by the executor is allowed to have as optional client scopes. " +
"Any scope name in the scope property of client metadata that is not included in this allow list is removed from the client metadata before the client is created or updated. " +
"Moreover, on every authorization request, any optional client scope of the client that is not included in this allow list is removed from the client, " +
"including realm default optional client scopes and client scopes added by an administrator. Default client scopes are not affected. " +
"If the allow list is vacant, the client has no optional client scope.",
ProviderConfigProperty.MULTIVALUED_STRING_TYPE,
null);
configProperties.add(property);

// Resource Indicators (RFC 8707) support
property = new ProviderConfigProperty(
RESOURCE_INDICATOR_ALLOW_LIST,
Expand Down
Loading
Loading