From 9b5e8212a89a4555f062e2e654641168f2e7f80a Mon Sep 17 00:00:00 2001 From: Wouter Born Date: Fri, 20 Nov 2026 17:05:54 +0100 Subject: [PATCH] Prevent master access tokens from growing with realm count - Limit client roles and audiences emitted by master OpenRemote tokens - Apply the mapper configuration during clean setup and upgrades - Verify stable token size and migration retries against Keycloak Fixes #3566 --- .../manager/setup/KeycloakInitSetup.java | 14 +- .../setup/MasterClientTokenMappers.java | 317 ++++++++++++++++++ ...1540__RestrictMasterClientTokenClaims.java | 47 +++ .../test/security/IdentityProviderTest.groovy | 76 +++++ 4 files changed, 452 insertions(+), 2 deletions(-) create mode 100644 manager/src/main/java/org/openremote/manager/setup/MasterClientTokenMappers.java create mode 100644 manager/src/main/java/org/openremote/manager/setup/database/V20261120_1540__RestrictMasterClientTokenClaims.java diff --git a/manager/src/main/java/org/openremote/manager/setup/KeycloakInitSetup.java b/manager/src/main/java/org/openremote/manager/setup/KeycloakInitSetup.java index a0b1f2ced4..0ca4c4be57 100644 --- a/manager/src/main/java/org/openremote/manager/setup/KeycloakInitSetup.java +++ b/manager/src/main/java/org/openremote/manager/setup/KeycloakInitSetup.java @@ -47,8 +47,18 @@ public void onStart() throws Exception { keycloakProvider.updateRealm(masterRealm); // Create our client application with its default roles in the master realm - keycloakProvider.createUpdateClient( - masterRealm.getName(), keycloakProvider.generateOpenRemoteClientRepresentation()); + if (keycloakProvider.createUpdateClient( + masterRealm.getName(), keycloakProvider.generateOpenRemoteClientRepresentation()) + == null) { + throw new IllegalStateException("Could not create the master OpenRemote client"); + } + // Flyway runs before this client exists on a clean install. Apply the same token mapper + // configuration after creation to keep admin authorization while limiting token growth. + keycloakProvider.getRealms( + realms -> { + MasterClientTokenMappers.configure(realms.realm(MASTER_REALM)); + return null; + }); // Update master user name User adminUser = keycloakProvider.getUserByUsername(MASTER_REALM, MASTER_REALM_ADMIN_USER); diff --git a/manager/src/main/java/org/openremote/manager/setup/MasterClientTokenMappers.java b/manager/src/main/java/org/openremote/manager/setup/MasterClientTokenMappers.java new file mode 100644 index 0000000000..5862db8040 --- /dev/null +++ b/manager/src/main/java/org/openremote/manager/setup/MasterClientTokenMappers.java @@ -0,0 +1,317 @@ +/* + * Copyright 2016, OpenRemote Inc. + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as + * published by the Free Software Foundation, either version 3 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see . + * + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +package org.openremote.manager.setup; + +import static org.openremote.model.Constants.KEYCLOAK_CLIENT_ID; + +import jakarta.ws.rs.core.Response; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import java.util.Objects; +import java.util.logging.Logger; +import java.util.stream.Stream; +import org.keycloak.admin.client.resource.ClientResource; +import org.keycloak.admin.client.resource.ClientScopeResource; +import org.keycloak.admin.client.resource.ClientScopesResource; +import org.keycloak.admin.client.resource.RealmResource; +import org.keycloak.representations.idm.ClientRepresentation; +import org.keycloak.representations.idm.ClientScopeRepresentation; +import org.keycloak.representations.idm.MappingsRepresentation; +import org.keycloak.representations.idm.ProtocolMapperRepresentation; +import org.keycloak.representations.idm.RoleRepresentation; + +/** + * Keeps access tokens issued to {@code master/openremote} from growing when realms are added. + * + *

Keycloak adds each realm's management client roles to the master realm's composite {@code + * admin} role. Keycloak expands composites in client scope mappings, so allowing {@code admin} in a + * restricted scope would still allow all of those roles. The default role mappers would then write + * the management roles to {@code resource_access} and their client IDs to {@code aud}. + * + *

OpenRemote uses {@code admin} in {@code realm_access.roles} to authorize master superusers. + * Keep the existing role scope and realm role claim, including custom roles, and limit the client + * role claim to {@code openremote} and {@code account}. Replace Audience Resolve with an {@code + * account} audience gated by account roles so users without those roles keep their existing + * audience behavior. + * + *

Clean setup and the upgrade migration both stage and verify the replacement mappers before + * detaching the stock {@code roles} scope from this client. This keeps authorization claims + * available if setup is interrupted and preserves the shared scope for other clients. + */ +public final class MasterClientTokenMappers { + + private static final Logger LOG = Logger.getLogger(MasterClientTokenMappers.class.getName()); + private static final String OIDC = "openid-connect"; + private static final String ACCOUNT = "account"; + private static final String ACCOUNT_SCOPE = "openremote-account-audience"; + private static final String CLIENT_ROLE_TARGET = "usermodel.clientRoleMapping.clientId"; + private static final String REALM_ROLE_MAPPER = "oidc-usermodel-realm-role-mapper"; + private static final String CLIENT_ROLE_MAPPER = "oidc-usermodel-client-role-mapper"; + private static final String AUDIENCE_RESOLVE = "oidc-audience-resolve-mapper"; + private static final String AUDIENCE = "oidc-audience-mapper"; + private static final String CLAIM = "claim.name"; + + private MasterClientTokenMappers() {} + + public static void configure(RealmResource master) { + var clients = master.clients(); + var match = clients.findByClientId(KEYCLOAK_CLIENT_ID); + if (match.isEmpty()) { + return; // Clean installation: KeycloakInitSetup will configure the client after creation. + } + + ClientResource client = clients.get(match.getFirst().getId()); + List defaults = client.getDefaultClientScopes(); + var stockRoles = defaults.stream().filter(scope -> "roles".equals(scope.getName())).findFirst(); + if (stockRoles.isEmpty()) { + return; // Already configured or replaced by the deployment. + } + + // A scope named "roles" may have been customized. Detach it only when the stock + // mappers and scope settings are present. + var scopes = master.clientScopes(); + var stock = scopes.get(stockRoles.get().getId()); + var stockMappers = stock.getProtocolMappers().getMappers(); + var realmMapper = + stockMappers.stream() + .filter(m -> isStockMapper(m, REALM_ROLE_MAPPER, "realm_access.roles")) + .findFirst(); + var clientMapper = + stockMappers.stream() + .filter(m -> isStockMapper(m, CLIENT_ROLE_MAPPER, "resource_access.${client_id}.roles")) + .findFirst(); + var audienceResolver = + stockMappers.stream().filter(m -> isStockMapper(m, AUDIENCE_RESOLVE, null)).findFirst(); + var settings = client.toRepresentation(); + if (!Boolean.TRUE.equals(settings.isFullScopeAllowed()) + || Boolean.TRUE.equals(settings.isConsentRequired()) + || !"false".equals(stock.toRepresentation().getAttributes().get("include.in.token.scope")) + || stockMappers.size() != 3 + || realmMapper.isEmpty() + || clientMapper.isEmpty() + || audienceResolver.isEmpty() + || hasMappings(stock.getScopeMappings().getAll())) { + LOG.warning("Skipping token mapper update for customized master/openremote role scope"); + return; + } + + // Reuse the stock claim names and token settings. Setting a client ID on each + // client-role mapper limits which client's roles it emits. + var replacements = + List.of( + copyMapper(realmMapper.get(), "openremote realm roles", null), + copyMapper(clientMapper.get(), "openremote client roles", KEYCLOAK_CLIENT_ID), + copyMapper(clientMapper.get(), "openremote account roles", ACCOUNT)); + var directMappers = client.getProtocolMappers().getMappers(); + // Other default or requested optional scopes can still write these claims. + // An exact match for a replacement can be left over from an interrupted run. + var linkedMappers = + Stream.concat(defaults.stream(), client.getOptionalClientScopes().stream()) + .filter( + scope -> + !scope.getId().equals(stockRoles.get().getId()) + && !ACCOUNT_SCOPE.equals(scope.getName())) + .flatMap(scope -> scopes.get(scope.getId()).getProtocolMappers().getMappers().stream()); + if (Stream.concat(directMappers.stream(), linkedMappers) + .anyMatch( + mapper -> + (writesRolesOrAudience(mapper) + || replacements.stream() + .anyMatch( + replacement -> replacement.getName().equals(mapper.getName()))) + && replacements.stream() + .noneMatch(replacement -> sameMapper(mapper, replacement)))) { + LOG.warning( + "Skipping token mapper update for customized master/openremote role or audience mappers"); + return; + } + + ClientRepresentation account = clients.findByClientId(ACCOUNT).getFirst(); + String audienceScope = + ensureAccountAudience(scopes, clients.get(account.getId()), account.getId()); + // Keep the existing scope attached until every replacement is in place. + for (var mapper : replacements) { + if (directMappers.stream().noneMatch(existing -> sameMapper(existing, mapper))) { + try (Response response = client.getProtocolMappers().createMapper(mapper)) { + requireCreated(response, mapper.getName()); + } + } + } + if (!hasScope(defaults, audienceScope)) { + client.addDefaultClientScope(audienceScope); + } + // Read back both kinds of configuration before removing the old claim source. + var installed = client.getProtocolMappers().getMappers(); + if (!hasScope(client.getDefaultClientScopes(), audienceScope) + || replacements.stream() + .anyMatch( + mapper -> installed.stream().noneMatch(existing -> sameMapper(existing, mapper)))) { + throw new IllegalStateException( + "Could not verify replacement token mappers for master/openremote"); + } + client.removeDefaultClientScope(stockRoles.get().getId()); + if (hasScope(client.getDefaultClientScopes(), stockRoles.get().getId())) { + throw new IllegalStateException( + "Could not detach the stock roles scope from master/openremote"); + } + LOG.info("Configured compact access token claims for master/openremote"); + } + + private static boolean hasScope(List scopes, String id) { + return scopes.stream().anyMatch(scope -> id.equals(scope.getId())); + } + + private static boolean isStockMapper( + ProtocolMapperRepresentation mapper, String type, String claim) { + var config = mapper.getConfig(); + return OIDC.equals(mapper.getProtocol()) + && type.equals(mapper.getProtocolMapper()) + && Objects.equals(claim, config.get(CLAIM)) + && "true".equals(config.get("access.token.claim")) + && "true".equals(config.get("introspection.token.claim")) + && config.entrySet().stream() + .allMatch( + entry -> + switch (entry.getKey()) { + case CLAIM, "access.token.claim", "introspection.token.claim" -> true; + case "multivalued" -> "true".equals(entry.getValue()); + case "jsonType.label" -> "String".equals(entry.getValue()); + // Keycloak's stock role mappers carry this unused placeholder. + case "user.attribute" -> "foo".equals(entry.getValue()); + case "id.token.claim", "userinfo.token.claim", "lightweight.claim" -> + "false".equals(entry.getValue()); + default -> entry.getValue() == null || entry.getValue().isEmpty(); + }) + && (claim == null || "true".equals(config.get("multivalued"))); + } + + private static boolean hasMappings(MappingsRepresentation mappings) { + return (mappings.getRealmMappings() != null && !mappings.getRealmMappings().isEmpty()) + || (mappings.getClientMappings() != null && !mappings.getClientMappings().isEmpty()); + } + + private static boolean writesRolesOrAudience(ProtocolMapperRepresentation mapper) { + String claim = Objects.toString(mapper.getConfig().get(CLAIM), ""); + return claim.startsWith("realm_access") + || claim.startsWith("resource_access") + || claim.equals("aud") + || AUDIENCE_RESOLVE.equals(mapper.getProtocolMapper()) + || AUDIENCE.equals(mapper.getProtocolMapper()); + } + + private static boolean sameMapper( + ProtocolMapperRepresentation left, ProtocolMapperRepresentation right) { + return Objects.equals(left.getName(), right.getName()) + && Objects.equals(left.getProtocolMapper(), right.getProtocolMapper()) + && Objects.equals(left.getProtocol(), right.getProtocol()) + && Objects.equals(left.getConfig(), right.getConfig()); + } + + private static ProtocolMapperRepresentation copyMapper( + ProtocolMapperRepresentation source, String name, String clientId) { + // Keycloak assigns a new ID for the dedicated mapper. Copy the config so the + // client filter applies only to the new mapper. + var copy = new ProtocolMapperRepresentation(); + copy.setName(name); + copy.setProtocol(source.getProtocol()); + copy.setProtocolMapper(source.getProtocolMapper()); + copy.setConfig(new HashMap<>(source.getConfig())); + if (clientId != null) { + copy.getConfig().put(CLIENT_ROLE_TARGET, clientId); + } + return copy; + } + + private static String ensureAccountAudience( + ClientScopesResource scopes, ClientResource account, String accountId) { + var audience = new ProtocolMapperRepresentation(); + audience.setName("account audience"); + audience.setProtocol(OIDC); + audience.setProtocolMapper(AUDIENCE); + audience.setConfig( + Map.of( + "included.client.audience", ACCOUNT, + "access.token.claim", "true", + "introspection.token.claim", "true", + "id.token.claim", "false", + "userinfo.token.claim", "false")); + + // This scope gates a mapper internally and adds no OAuth scope or consent prompt. + var attributes = + Map.of("include.in.token.scope", "false", "display.on.consent.screen", "false"); + var existing = + scopes.findAll().stream() + .filter(scope -> ACCOUNT_SCOPE.equals(scope.getName())) + .findFirst(); + String id; + // A retry can reuse a scope created before the role mappings were added. + // Verify its contents before using a scope with the expected name. + if (existing.isPresent()) { + id = existing.get().getId(); + var mappers = scopes.get(id).getProtocolMappers().getMappers(); + if (!OIDC.equals(existing.get().getProtocol()) + || !attributes.equals(existing.get().getAttributes()) + || mappers.size() != 1 + || !sameMapper(mappers.getFirst(), audience)) { + throw new IllegalStateException("Client scope name already in use: " + ACCOUNT_SCOPE); + } + } else { + var scope = new ClientScopeRepresentation(); + scope.setName(ACCOUNT_SCOPE); + scope.setProtocol(OIDC); + scope.setAttributes(attributes); + scope.setProtocolMappers(List.of(audience)); + try (Response response = scopes.create(scope)) { + requireCreated(response, ACCOUNT_SCOPE); + String path = response.getLocation().getPath(); + id = path.substring(path.lastIndexOf('/') + 1); + } + } + + ClientScopeResource scope = scopes.get(id); + var mappings = scope.getScopeMappings(); + var all = mappings.getAll(); + if ((all.getRealmMappings() != null && !all.getRealmMappings().isEmpty()) + || (all.getClientMappings() != null + && all.getClientMappings().keySet().stream().anyMatch(name -> !ACCOUNT.equals(name)))) { + throw new IllegalStateException("Unexpected role mappings on client scope " + ACCOUNT_SCOPE); + } + // Keycloak enables a role-mapped client scope only for users with a matching + // effective role. The stock Audience Resolve mapper also required an account role. + List accountRoles = account.roles().list(); + if (accountRoles.isEmpty()) { + throw new IllegalStateException("No account roles available to gate the account audience"); + } + var roleScope = mappings.clientLevel(accountId); + var assigned = roleScope.listAll().stream().map(RoleRepresentation::getId).toList(); + var missing = accountRoles.stream().filter(role -> !assigned.contains(role.getId())).toList(); + if (!missing.isEmpty()) { + roleScope.add(missing); + } + return id; + } + + private static void requireCreated(Response response, String name) { + if (response.getStatus() != Response.Status.CREATED.getStatusCode()) { + throw new IllegalStateException( + "Could not create Keycloak " + name + " (HTTP " + response.getStatus() + ")"); + } + } +} diff --git a/manager/src/main/java/org/openremote/manager/setup/database/V20261120_1540__RestrictMasterClientTokenClaims.java b/manager/src/main/java/org/openremote/manager/setup/database/V20261120_1540__RestrictMasterClientTokenClaims.java new file mode 100644 index 0000000000..e5fc79bb16 --- /dev/null +++ b/manager/src/main/java/org/openremote/manager/setup/database/V20261120_1540__RestrictMasterClientTokenClaims.java @@ -0,0 +1,47 @@ +/* + * Copyright 2016, OpenRemote Inc. + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as + * published by the Free Software Foundation, either version 3 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see . + * + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +package org.openremote.manager.setup.database; + +import static org.openremote.model.Constants.MASTER_REALM; + +import org.flywaydb.core.api.migration.Context; +import org.openremote.manager.setup.MasterClientTokenMappers; + +/** + * Updates the existing {@code master/openremote} client through the Keycloak Admin API so its + * access tokens preserve OpenRemote's authorization claims without including per-realm Keycloak + * management roles and audiences. + * + *

On a clean installation, the client may not exist when Flyway runs. {@link + * org.openremote.manager.setup.KeycloakInitSetup} applies the same mapper configuration after + * creating the client. + */ +public class V20261120_1540__RestrictMasterClientTokenClaims extends AbstractKeycloakMigration { + + @Override + public void migrate(Context context) { + if (!isKeycloakDeployment()) { + return; + } + + try (var keycloak = openKeycloak()) { + MasterClientTokenMappers.configure(keycloak.realm(MASTER_REALM)); + } + } +} diff --git a/test/src/test/groovy/org/openremote/test/security/IdentityProviderTest.groovy b/test/src/test/groovy/org/openremote/test/security/IdentityProviderTest.groovy index eff78d56d8..af100ef7ff 100644 --- a/test/src/test/groovy/org/openremote/test/security/IdentityProviderTest.groovy +++ b/test/src/test/groovy/org/openremote/test/security/IdentityProviderTest.groovy @@ -18,11 +18,14 @@ */ package org.openremote.test.security +import groovy.json.JsonSlurper +import org.keycloak.admin.client.Keycloak import org.keycloak.admin.client.resource.IdentityProviderResource import org.keycloak.admin.client.resource.IdentityProvidersResource import org.keycloak.representations.idm.IdentityProviderMapperRepresentation import org.openremote.manager.security.ManagerIdentityService import org.openremote.manager.security.ManagerKeycloakIdentityProvider +import org.openremote.manager.setup.database.V20261120_1540__RestrictMasterClientTokenClaims import org.openremote.model.Constants import org.openremote.model.security.ClientRole import org.openremote.model.security.Realm @@ -30,6 +33,10 @@ import org.openremote.test.ManagerContainerTrait import spock.lang.Shared import spock.lang.Specification +import static org.openremote.container.security.IdentityProvider.OR_ADMIN_PASSWORD +import static org.openremote.container.security.IdentityProvider.OR_ADMIN_PASSWORD_DEFAULT +import static org.openremote.container.security.keycloak.KeycloakIdentityProvider.* + class IdentityProviderTest extends Specification implements ManagerContainerTrait { @Shared @@ -87,6 +94,75 @@ class IdentityProviderTest extends Specification implements ManagerContainerTrai identityProvider.getRealm(realmName) == null } + def "Master OpenRemote access tokens stay compact when realms are added"() { + def realmNames = (1..3).collect { "token-growth-test-$it" } + def master = identityProvider.getRealms { it.realm(Constants.MASTER_REALM) } + def client = master.clients().get(master.clients().findByClientId(Constants.KEYCLOAK_CLIENT_ID).first().id) + def stockScope = master.clientScopes().findAll().find { it.name == "roles" } + + when: "the manager has provisioned its master client" + def before = masterAccessToken() + def beforeClaims = jwtClaims(before) + + then: + !client.defaultClientScopes.any { it.id == stockScope.id } + beforeClaims.realm_access.roles.contains(Constants.SUPER_USER_REALM_ROLE) + beforeClaims.resource_access.openremote.roles.contains(ClientRole.READ_ASSETS.value) + beforeClaims.resource_access.keySet() == ["openremote", "account"] as Set + beforeClaims.aud == "account" + + when: "realms are added and a staged upgrade still has the old scope attached" + realmNames.each { identityProvider.createRealm(new Realm(null, it, it, true)) } + client.addDefaultClientScope(stockScope.id) + def expandedClaims = jwtClaims(masterAccessToken()) + + then: + realmNames.every { expandedClaims.resource_access.containsKey("${it}-realm".toString()) } + realmNames.every { expandedClaims.aud.contains("${it}-realm".toString()) } + + when: "the same configuration routine is rerun" + def migration = new V20261120_1540__RestrictMasterClientTokenClaims() + migration.migrate(null) + migration.migrate(null) + def after = masterAccessToken() + def afterClaims = jwtClaims(after) + + then: + (afterClaims.realm_access.roles as Set) == (beforeClaims.realm_access.roles as Set) + afterClaims.aud == beforeClaims.aud + afterClaims.resource_access.keySet() == beforeClaims.resource_access.keySet() + afterClaims.resource_access.every { clientId, access -> + (access.roles as Set) == (beforeClaims.resource_access[clientId].roles as Set) + } + after.length() == before.length() + + cleanup: + if (client?.defaultClientScopes?.any { it.id == stockScope.id }) { + client.removeDefaultClientScope(stockScope.id) + } + realmNames.findAll { + identityProvider.realmExists(it) + }.each { + identityProvider.deleteRealm(it) + } + } + + private String masterAccessToken() { + def config = defaultConfig() + def host = config.getOrDefault(OR_KEYCLOAK_HOST, OR_KEYCLOAK_HOST_DEFAULT) + def port = config.getOrDefault(OR_KEYCLOAK_PORT, OR_KEYCLOAK_PORT_DEFAULT.toString()) + def path = config.getOrDefault(OR_KEYCLOAK_PATH, OR_KEYCLOAK_PATH_DEFAULT) + def serverUrl = "http://$host:$port/${path.replaceFirst('^/+', '')}" + Keycloak.getInstance(serverUrl, Constants.MASTER_REALM, Constants.MASTER_REALM_ADMIN_USER, + config.getOrDefault(OR_ADMIN_PASSWORD, OR_ADMIN_PASSWORD_DEFAULT), Constants.KEYCLOAK_CLIENT_ID).withCloseable { + it.tokenManager().grantToken().token + } + } + + private static Map jwtClaims(String token) { + new JsonSlurper().parse(Base64.urlDecoder.decode(token.split("\\.")[1])) as Map + } + def "Configure Keycloak chaining"() { def realmName = Constants.MASTER_REALM def idpAlias = "keycloak-oidc"