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
18 changes: 18 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 @@ -763,6 +763,24 @@ As a workaround, use the default value of a property that is not defined, for ex
This did not work before, as the `$` prevented the placeholder from being closed.
It only works as long as the property is not defined.

=== Client ID Metadata Document executor verifies the back-channel URLs of the client metadata
// https://github.com/keycloak/keycloak/issues/55378

The `client-id-metadata-document` client policy executor of the experimental Client ID Metadata Document feature now verifies the `backchannel_logout_uri` and `backchannel_client_notification_endpoint` properties of a client metadata document in the same way as the other URLs that {project_name} sends a request to, such as the `jwks_uri` property.
Their host must match one of the *Trusted domains* of the executor.
Their scheme must be `https` unless *Allow http scheme* is `ON`.
Their host must not resolve to a loopback, private, link-local, unique local or multicast address unless *Allow private-use addresses* is `ON`.
If *Restrict same domain* is `ON`, they must also be under the same trusted domain as the Client ID URL and the Redirect URI.

An authorization request of a client whose metadata does not pass these checks is rejected.
This also applies to a client that was registered before the upgrade, because the URLs that {project_name} stored for it are checked on every authorization request.
If such a client is legitimate, add the host of these URLs to *Trusted domains*.

{project_name} does not remove the URLs that it stored for a client before the upgrade, and it keeps sending back-channel logout requests and CIBA client notifications to them.
Therefore, review the clients that were registered through a Client ID Metadata Document before the upgrade, which are the clients whose client ID is the URL of the document.
Delete a client whose back-channel logout URL or CIBA client notification endpoint is a destination that {project_name} should not send requests to.
A deleted client is registered again from its client metadata document on its next authorization request.

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

Expand Down
7 changes: 5 additions & 2 deletions docs/guides/securing-apps/mcp-authz-server.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -207,8 +207,11 @@ To configure the executor, create a client policy profile in the {project_name}
. Click *Add executor* and select `client-id-metadata-document` from the list.
. Configure the executor with the following options:
+
* *Allow http scheme*: If `ON`, allows `http` scheme for the URLs that {project_name} fetches itself, that is the Client ID URL and the `jwks_uri`, `sector_identifier_uri` and `request_uris` properties of the client metadata. This should only be `ON` in a development environment and must be `OFF` in a production environment.
* *Allow private-use addresses*: If `OFF`, the executor rejects the URLs that {project_name} fetches itself, that is the Client ID URL and the `jwks_uri`, `sector_identifier_uri` and `request_uris` properties, when their host resolves to a loopback, private, link-local, unique local or multicast address. They are rejected even if their host matches one of the trusted domains, which prevents Server-Side Request Forgery (SSRF) against hosts that only {project_name} can reach. This should only be `ON` in a development environment and must be `OFF` in a production environment.
* *Allow http scheme*: If `ON`, allows `http` scheme for the URLs that {project_name} sends a request to itself, that is the Client ID URL and the `jwks_uri`, `sector_identifier_uri`, `request_uris`, `backchannel_logout_uri` and `backchannel_client_notification_endpoint` properties of the client metadata. This should only be `ON` in a development environment and must be `OFF` in a production environment.
* *Allow private-use addresses*: If `OFF`, the executor rejects the URLs that {project_name} sends a request to itself, that is the Client ID URL and the `jwks_uri`, `sector_identifier_uri`, `request_uris`, `backchannel_logout_uri` and `backchannel_client_notification_endpoint` properties, when their host resolves to a loopback, private, link-local, unique local or multicast address. They are rejected even if their host matches one of the trusted domains, which prevents Server-Side Request Forgery (SSRF) against hosts that only {project_name} can reach. This should only be `ON` in a development environment and must be `OFF` in a production environment.
The scheme and the address of these URLs are checked when {project_name} fetches the client metadata.
They are not checked again when {project_name} later sends a request to one of these URLs, so a host that resolves to a different address afterwards is not detected.
Therefore, only add domains whose owners and DNS records you trust to *Trusted domains*.
* *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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,14 @@
import org.keycloak.http.simple.SimpleHttp;
import org.keycloak.http.simple.SimpleHttpRequest;
import org.keycloak.http.simple.SimpleHttpResponse;
import org.keycloak.models.CibaConfig;
import org.keycloak.models.ClientModel;
import org.keycloak.models.KeycloakSession;
import org.keycloak.models.ProtocolMapperModel;
import org.keycloak.models.RealmModel;
import org.keycloak.models.utils.KeycloakModelUtils;
import org.keycloak.protocol.oauth2.cimd.provider.ClientIdMetadataDocumentProvider;
import org.keycloak.protocol.oidc.OIDCAdvancedConfigWrapper;
import org.keycloak.protocol.oidc.OIDCLoginProtocol;
import org.keycloak.protocol.oidc.mappers.AudienceProtocolMapper;
import org.keycloak.protocol.oidc.resourceindicators.ResourceIndicatorConstants;
Expand All @@ -42,6 +44,7 @@
import org.keycloak.services.clientpolicy.context.PreAuthorizationRequestContext;
import org.keycloak.services.clientpolicy.executor.ClientPolicyExecutorProvider;
import org.keycloak.util.JsonSerialization;
import org.keycloak.utils.StringUtil;

import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.core.JsonProcessingException;
Expand Down Expand Up @@ -400,16 +403,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 persisted client metadata and the resource parameter still need to be verified on every authorization request.
ClientModel clientModel = session.getContext().getRealm().getClientByClientId(clientId);
verifyPersistedClientMetadata(redirectUriURI, clientModel);
enforceResourceIndicator(preAuthorizationRequestContext, clientModel);
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 clientModel = session.getContext().getRealm().getClientByClientId(clientId);
verifyPersistedClientMetadata(redirectUriURI, clientModel);
enforceResourceIndicator(preAuthorizationRequestContext, clientModel);
return;
}

Expand All @@ -428,6 +435,8 @@ private void process(PreAuthorizationRequestContext preAuthorizationRequestConte
clientModel = provider.updateClientMetadata(clientOIDCWithCacheControl);
}

// an update does not remove every property that the fetched client metadata no longer includes
verifyPersistedClientMetadata(redirectUriURI, clientModel);
enforceResourceIndicator(preAuthorizationRequestContext, clientModel);
}

Expand Down Expand Up @@ -739,6 +748,8 @@ protected URI verifyClientMetadata(final URI clientIdURI, final URI redirectUriU
// RFC 7591 (optional): logo_uri, client_uri, tos_uri, policy_uri, jwks_uri
// OIDC Dynamic Client Registration (optional): sector_identifier_uri, request_uris, fetched by the
// authorization server after the registration
// OIDC Back-Channel Logout (optional): backchannel_logout_uri, CIBA (optional): backchannel_client_notification_endpoint,
// which the authorization server sends a request to after the registration

List<String> trustedDomains = convertContentFilledList(getConfiguration().getTrustedDomains());
verifyUriProperty(clientOIDC.getClientId(), "client_id", trustedDomains);
Expand All @@ -759,6 +770,9 @@ protected URI verifyClientMetadata(final URI clientIdURI, final URI redirectUriU
verifyFetchedUriProperty(requestUri, "request_uris", trustedDomains);
}

verifyRequestedUriProperty(clientOIDC.getBackchannelLogoutUri(), "backchannel_logout_uri", trustedDomains);
verifyRequestedUriProperty(clientOIDC.getBackchannelClientNotificationEndpoint(), "backchannel_client_notification_endpoint", trustedDomains);
Comment thread
tnorimat marked this conversation as resolved.
Resolved

URI clientIdURIfromMetadata;
try {
clientIdURIfromMetadata = new URI(clientOIDC.getClientId());
Expand All @@ -771,6 +785,46 @@ protected URI verifyClientMetadata(final URI clientIdURI, final URI redirectUriU
return clientIdURIfromMetadata;
}

/**
* Verifies and validates the URLs of a persisted client metadata that the authorization server sends a request to,
* in the same way as the ones of a fetched client metadata.
* It is done on every authorization request, because the persisted client metadata is used whether it was fetched
* for the request or not, and it can have been persisted before the configuration of the executor changed.
*
* @param redirectUriURI a value of {redirect_uri} parameter of an authorization request in {@link URI}
* @param clientModel a persisted client metadata
* @throws ClientPolicyException when verifying or validating a persisted client metadata fails.
*/
protected void verifyPersistedClientMetadata(final URI redirectUriURI, final ClientModel clientModel) throws ClientPolicyException {
List<String> trustedDomains = convertContentFilledList(getConfiguration().getTrustedDomains());
String backchannelLogoutUrl = OIDCAdvancedConfigWrapper.fromClientModel(clientModel).getBackchannelLogoutUrl();
String backchannelClientNotificationEndpoint = clientModel.getAttribute(CibaConfig.CIBA_BACKCHANNEL_CLIENT_NOTIFICATION_ENDPOINT);
verifyRequestedUriProperty(backchannelLogoutUrl, "backchannel_logout_uri", trustedDomains);
verifyRequestedUriProperty(backchannelClientNotificationEndpoint, "backchannel_client_notification_endpoint", trustedDomains);

if (getConfiguration().isRestrictSameDomain()) {
List<String> l = Stream.of(backchannelLogoutUrl, backchannelClientNotificationEndpoint).filter(StringUtil::isNotBlank).toList();
validateSameDomain(l, redirectUriURI, trustedDomains);
}
}

// same domain policy: the URIs have to be under the same trusted domain as the redirect_uri parameter
private void validateSameDomain(List<String> uris, URI redirectUriURI, List<String> trustedDomains) throws ClientPolicyException {
String redirectUriHost = redirectUriURI.getHost();
try {
for (String s : uris) {
URI u = new URI(s);
if (redirectUriHost == null || trustedDomains.stream().noneMatch(i -> checkTrustedDomain(u.getHost(), i) && checkTrustedDomain(redirectUriHost, i))) {
getLogger().warnv("not under the same domain = {0}", u.getHost());
throw invalidClientIdMetadata(ERR_METADATA_NO_ALL_URIS_SAMEDOMAIN);
}
}
} catch (URISyntaxException e) {
getLogger().warnv("URI not resolved {0}}", e);
throw invalidClientIdMetadata(ERR_METADATA_NO_ALL_URIS_SAMEDOMAIN);
}
}

private void verifyUriProperty(String uriString, String propertyName, List<String> trustedDomains) throws ClientPolicyException {
verifyUri(uriString, trustedDomains, false, (error, logMessageTemplate) -> {
getLogger().warnv(logMessageTemplate, propertyName, uriString);
Expand All @@ -789,6 +843,13 @@ private void verifyFetchedUriProperty(String uriString, String propertyName, Lis
});
}

// for a property whose URL the authorization server sends a request to itself, which it does not do for a blank one
private void verifyRequestedUriProperty(String uriString, String propertyName, List<String> trustedDomains) throws ClientPolicyException {
if (StringUtil.isNotBlank(uriString)) {
verifyFetchedUriProperty(uriString, propertyName, trustedDomains);
}
}

private void verifyUriPropertyIfPresent(String uriString, String propertyName, List<String> trustedDomains) throws ClientPolicyException {
if (uriString != null) {
verifyUriProperty(uriString, propertyName, trustedDomains);
Expand Down Expand Up @@ -888,7 +949,8 @@ protected void validateClientMetadata(final URI clientIdURI, final URI redirectU
// An authorization server MAY impose restrictions or relationships
// between the redirect_uris and the client_id or client_uri properties

// same domain policy: client_id, redirect_uri, redirect_uris, client_uri, logo_uri, tos_uri,, policy_uri, jwks_uri
// same domain policy: client_id, redirect_uri, redirect_uris, client_uri, logo_uri, tos_uri,, policy_uri, jwks_uri,
// backchannel_logout_uri, backchannel_client_notification_endpoint
List<String> trustedDomains = convertContentFilledList(getConfiguration().getTrustedDomains());
if (getConfiguration().isRestrictSameDomain() && trustedDomains != null && !trustedDomains.isEmpty()) {
// Client Metadata verification ensures that
Expand All @@ -900,20 +962,10 @@ protected void validateClientMetadata(final URI clientIdURI, final URI redirectU
throw invalidClientIdMetadata(ERR_METADATA_URIS_SAMEDOMAIN);
}

List<String> l = Stream.of(clientOIDC.getClientId(), clientOIDC.getClientUri(), clientOIDC.getLogoUri(), clientOIDC.getTosUri(), clientOIDC.getPolicyUri(), clientOIDC.getJwksUri())
.filter(Objects::nonNull).toList();
try {
for (String s : l) {
URI u = new URI(s);
if (trustedDomains.stream().filter(i->!i.isBlank()).noneMatch(i -> checkTrustedDomain(u.getHost(), i) && checkTrustedDomain(redirectUriURI.getHost(), i))) {
getLogger().warnv("not under the same domain = {0}", u.getHost());
throw invalidClientIdMetadata(ERR_METADATA_NO_ALL_URIS_SAMEDOMAIN);
}
}
} catch (URISyntaxException e) {
getLogger().warnv("URI not resolved {0}}", e);
throw invalidClientIdMetadata(ERR_METADATA_NO_ALL_URIS_SAMEDOMAIN);
}
List<String> l = Stream.of(clientOIDC.getClientId(), clientOIDC.getClientUri(), clientOIDC.getLogoUri(), clientOIDC.getTosUri(), clientOIDC.getPolicyUri(), clientOIDC.getJwksUri(),
clientOIDC.getBackchannelLogoutUri(), clientOIDC.getBackchannelClientNotificationEndpoint())
.filter(StringUtil::isNotBlank).toList();
validateSameDomain(l, redirectUriURI, trustedDomains);
}

// required properties policy
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,9 @@ static protected void addCommonConfigProperties(List<ProviderConfigProperty> con
ProviderConfigProperty property = new ProviderConfigProperty(
ALLOW_HTTP_SCHEME,
"Allow http scheme",
"If ON, then the executor allows http scheme as a valid Client ID URL and property of Client Metadata whose value is URL: client_uri, logo_uri, tos_uri, policy_uri, jwks_uri. " +
"If ON, then the executor allows http scheme for a URL that the server sends a request to itself, namely the Client ID URL and the " +
"jwks_uri, sector_identifier_uri, request_uris, backchannel_logout_uri and backchannel_client_notification_endpoint " +
"properties of Client Metadata. " +
"It can be ON only for development environment. It must be OFF in production environment. ",
ProviderConfigProperty.BOOLEAN_TYPE,
false);
Expand All @@ -93,8 +95,9 @@ static protected void addCommonConfigProperties(List<ProviderConfigProperty> con
property = new ProviderConfigProperty(
ALLOW_PRIVATE_USE_ADDRESSES,
"Allow private-use addresses",
"If OFF, then the executor rejects a URL that the server fetches itself, namely the Client ID URL and the " +
"jwks_uri, sector_identifier_uri and request_uris properties of Client Metadata, whose host resolves to a " +
"If OFF, then the executor rejects a URL that the server sends a request to itself, namely the Client ID URL and the " +
"jwks_uri, sector_identifier_uri, request_uris, backchannel_logout_uri and backchannel_client_notification_endpoint " +
"properties of Client Metadata, whose host resolves to a " +
"loopback, private, link-local, unique local or multicast address. Such URLs are rejected even if their host " +
"matches one of the trusted domains, which prevents Server-Side Request Forgery (SSRF) against hosts only " +
"reachable from the server. It can be ON only for development environment. It must be OFF in production environment.",
Expand All @@ -108,7 +111,8 @@ static protected void addCommonConfigProperties(List<ProviderConfigProperty> con
"Trusted domains",
"If some domains are filled, the executor only accepts the following URL-formatted parameters whose host part matches one of the filled domains: " +
"Authorization request parameters: client_id, redirect_uri, " +
"Client metadata properties: client_id, redirect_uris, jwks_uri, logo_uri, policy_uri, tos_uri, client_uri, sector_identifier_uri, request_uris. " +
"Client metadata properties: client_id, redirect_uris, jwks_uri, logo_uri, policy_uri, tos_uri, client_uri, sector_identifier_uri, request_uris, " +
"backchannel_logout_uri, backchannel_client_notification_endpoint. " +
"The domains are checked by using wildcard pattern matching (e.g. '*.example.org'). " +
"If the domains not filled, the executor denies all such the parameters and properties. " +
"For example, use pattern like '*.example.org' if you want to accept the parameter / property whose domain is 'example.org' or its subdomains.",
Expand Down
Loading
Loading