Skip to content

armgit / core

Public Imported from GitHub
0

100% open-source IoT Platform - Integrate your devices, add intelligence, build custom apps

Require dedicated roles for gateway tunnel endpoints

Ekhorn72045b9889e1
diff --git a/manager/src/main/java/org/openremote/manager/setup/database/V20260903_1000__AddTunnelRoles.java b/manager/src/main/java/org/openremote/manager/setup/database/V20260903_1000__AddTunnelRoles.java
new file mode 100644
index 000000000..f6b1b384a
--- /dev/null
+++ b/manager/src/main/java/org/openremote/manager/setup/database/V20260903_1000__AddTunnelRoles.java
@@ -0,0 +1,44 @@
+/*
+ * Copyright 2026, 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 <https://www.gnu.org/licenses/>.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+package org.openremote.manager.setup.database;
+
+import java.util.List;
+import org.openremote.model.security.ClientRole;
+
+/**
+ * Flyway migration that adds the {@code read:tunnels} and {@code write:tunnels} client roles to the
+ * {@code openremote} client of every realm and wires them into the existing {@code read}/{@code
+ * write} composite roles. See {@link AbstractKeycloakRolesMigration} for the credential handling
+ * and why this must stay a Java migration.
+ *
+ * <p>Users provisioned with individual roles rather than a composite do not gain these, so accounts
+ * that used the tunnel endpoints without holding {@code read}/{@code write} need them assigning.
+ */
+public class V20260903_1000__AddTunnelRoles extends AbstractKeycloakRolesMigration {
+
+ @Override
+ protected List<ClientRole> getReadRoles() {
+ return List.of(ClientRole.READ_TUNNELS);
+ }
+
+ @Override
+ protected List<ClientRole> getWriteRoles() {
+ return List.of(ClientRole.WRITE_TUNNELS);
+ }
+}
diff --git a/model/src/main/java/org/openremote/model/Constants.java b/model/src/main/java/org/openremote/model/Constants.java
index f3dd284f4..6d61b2da0 100644
--- a/model/src/main/java/org/openremote/model/Constants.java
+++ b/model/src/main/java/org/openremote/model/Constants.java
@@ -38,6 +38,7 @@ public interface Constants {
String READ_ALARMS_ROLE = "read:alarms";
String READ_NOTIFICATIONS_ROLE = "read:notifications";
String READ_SERVICES_ROLE = "read:services";
+ String READ_TUNNELS_ROLE = "read:tunnels";
String WRITE_SERVICES_ROLE = "write:services";
String WRITE_USER_ROLE = "write:user";
String WRITE_ADMIN_ROLE = "write:admin";
@@ -48,6 +49,7 @@ public interface Constants {
String WRITE_INSIGHTS_ROLE = "write:insights";
String WRITE_ALARMS_ROLE = "write:alarms";
String WRITE_NOTIFICATIONS_ROLE = "write:notifications";
+ String WRITE_TUNNELS_ROLE = "write:tunnels";
String RESTRICTED_USER_REALM_ROLE = "restricted_user";
String AUTH_CONTEXT = "AUTH_CONTEXT";
String SESSION_OPEN = "connection.sessionOpen";
diff --git a/model/src/main/java/org/openremote/model/gateway/GatewayServiceResource.java b/model/src/main/java/org/openremote/model/gateway/GatewayServiceResource.java
index b58e0be3b..c2dfa282b 100644
--- a/model/src/main/java/org/openremote/model/gateway/GatewayServiceResource.java
+++ b/model/src/main/java/org/openremote/model/gateway/GatewayServiceResource.java
@@ -43,7 +43,7 @@ public interface GatewayServiceResource {
@GET
@Path("tunnel/{realm}")
@Produces(APPLICATION_JSON)
- @RolesAllowed({Constants.READ_ADMIN_ROLE})
+ @RolesAllowed({Constants.READ_TUNNELS_ROLE})
@Operation(
operationId = "getAllActiveTunnelInfos",
summary = "Retrieve all active gateway tunnels in a realm",
@@ -59,6 +59,7 @@ public interface GatewayServiceResource {
@GET
@Path("tunnel/{realm}/{id}")
@Produces(APPLICATION_JSON)
+ @RolesAllowed({Constants.READ_TUNNELS_ROLE})
@Operation(
operationId = "getGatewayActiveTunnelInfos",
summary = "Retrieve the active tunnels of a gateway",
@@ -76,6 +77,7 @@ public interface GatewayServiceResource {
@GET
@Path("tunnel/{realm}/{id}/{target}/{targetPort}")
@Produces(APPLICATION_JSON)
+ @RolesAllowed({Constants.READ_TUNNELS_ROLE})
@Operation(
operationId = "getActiveTunnelInfo",
summary = "Retrieve one active gateway tunnel",
@@ -106,6 +108,7 @@ public interface GatewayServiceResource {
@Path("tunnel")
@Consumes(APPLICATION_JSON)
@Produces(APPLICATION_JSON)
+ @RolesAllowed({Constants.WRITE_TUNNELS_ROLE})
@Operation(
operationId = "startTunnel",
summary = "Start a tunnel for a gateway",
@@ -129,6 +132,7 @@ public interface GatewayServiceResource {
@Path("tunnel")
@Consumes(APPLICATION_JSON)
@Produces(APPLICATION_JSON)
+ @RolesAllowed({Constants.WRITE_TUNNELS_ROLE})
@Operation(
operationId = "stopTunnel",
summary = "Stop a tunnel for a gateway",
diff --git a/model/src/main/java/org/openremote/model/security/ClientRole.java b/model/src/main/java/org/openremote/model/security/ClientRole.java
index 40d40c1b6..532d49907 100644
--- a/model/src/main/java/org/openremote/model/security/ClientRole.java
+++ b/model/src/main/java/org/openremote/model/security/ClientRole.java
@@ -36,6 +36,7 @@ public enum ClientRole {
READ_ALARMS(Constants.READ_ALARMS_ROLE, "Read alarms"),
READ_NOTIFICATIONS(Constants.READ_NOTIFICATIONS_ROLE, "Read notifications"),
READ_SERVICES(Constants.READ_SERVICES_ROLE, "View services"),
+ READ_TUNNELS(Constants.READ_TUNNELS_ROLE, "Read gateway tunnels"),
WRITE_SERVICES(Constants.WRITE_SERVICES_ROLE, "Write service data"),
WRITE_USER(Constants.WRITE_USER_ROLE, "Write data of the authenticated user"),
@@ -47,6 +48,9 @@ public enum ClientRole {
WRITE_INSIGHTS(Constants.WRITE_INSIGHTS_ROLE, "Write dashboard data"),
WRITE_ALARMS(Constants.WRITE_ALARMS_ROLE, "Write alarm data"),
WRITE_NOTIFICATIONS(Constants.WRITE_NOTIFICATIONS_ROLE, "Write notification data"),
+ WRITE_TUNNELS(
+ Constants.WRITE_TUNNELS_ROLE,
+ "Open and close gateway tunnels (NOTE: reaches hosts on the gateway's own network!)"),
READ(
"read",
@@ -61,7 +65,8 @@ public enum ClientRole {
READ_INSIGHTS,
READ_ALARMS,
READ_NOTIFICATIONS,
- READ_SERVICES
+ READ_SERVICES,
+ READ_TUNNELS
}),
WRITE(
@@ -78,6 +83,7 @@ public enum ClientRole {
READ_ALARMS,
READ_NOTIFICATIONS,
READ_SERVICES,
+ READ_TUNNELS,
WRITE_USER,
WRITE_ADMIN,
WRITE_LOGS,
@@ -87,7 +93,8 @@ public enum ClientRole {
WRITE_INSIGHTS,
WRITE_ALARMS,
WRITE_NOTIFICATIONS,
- WRITE_SERVICES
+ WRITE_SERVICES,
+ WRITE_TUNNELS
});
// Only individual roles, not composites
diff --git a/test/src/test/groovy/org/openremote/test/gateway/GatewayTunnelAuthorizationTest.groovy b/test/src/test/groovy/org/openremote/test/gateway/GatewayTunnelAuthorizationTest.groovy
new file mode 100644
index 000000000..70e7e4ff8
--- /dev/null
+++ b/test/src/test/groovy/org/openremote/test/gateway/GatewayTunnelAuthorizationTest.groovy
@@ -0,0 +1,111 @@
+/*
+ * Copyright 2026, 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 <https://www.gnu.org/licenses/>.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+package org.openremote.test.gateway
+
+import jakarta.ws.rs.WebApplicationException
+import org.openremote.manager.setup.SetupService
+import org.openremote.model.gateway.GatewayServiceResource
+import org.openremote.model.gateway.GatewayTunnelInfo
+import org.openremote.setup.integration.KeycloakTestSetup
+import org.openremote.test.ManagerContainerTrait
+import spock.lang.Shared
+import spock.lang.Specification
+
+import static org.openremote.model.Constants.KEYCLOAK_CLIENT_ID
+
+/**
+ * Covers the role gate on the gateway tunnel endpoints. Opening a tunnel puts the manager on a
+ * host inside the gateway's own network, so it has to require a role of its own rather than
+ * accepting any account that happens to be signed in.
+ */
+class GatewayTunnelAuthorizationTest extends Specification implements ManagerContainerTrait {
+
+ @Shared
+ static GatewayServiceResource noRoleTunnelResource
+
+ @Shared
+ static String buildingRealm
+
+ def setupSpec() {
+ def container = startContainer(defaultConfig(), defaultServices())
+ def keycloakTestSetup = container.getService(SetupService.class).getTaskOfType(KeycloakTestSetup.class)
+ buildingRealm = keycloakTestSetup.realmBuilding.name
+
+ // testuser2 holds write:user, read:map and read:assets and nothing else. It is the least
+ // privileged account the API will accept, and it is not a restricted user.
+ def accessToken = authenticate(container, buildingRealm, KEYCLOAK_CLIENT_ID, "testuser2", "testuser2")
+ noRoleTunnelResource = getClientApiTarget(serverUri(serverPort), buildingRealm, accessToken)
+ .proxy(GatewayServiceResource.class)
+ }
+
+ def "A user holding no tunnel role cannot list a gateway's tunnels"() {
+
+ when: "a user with no administrative role lists the tunnels of an arbitrary gateway"
+ noRoleTunnelResource.getGatewayActiveTunnelInfos(null, buildingRealm, "somegatewayid")
+
+ then: "the request is refused"
+ WebApplicationException ex = thrown()
+ ex.response.status == 403
+ }
+
+ def "A user holding no tunnel role cannot read a single tunnel"() {
+
+ when: "a user with no administrative role reads one tunnel by endpoint"
+ noRoleTunnelResource.getActiveTunnelInfo(null, buildingRealm, "somegatewayid", "10.0.0.1", 22)
+
+ then: "the request is refused"
+ WebApplicationException ex = thrown()
+ ex.response.status == 403
+ }
+
+ def "A user holding no tunnel role cannot start a tunnel"() {
+
+ when: "a user with no administrative role opens a tunnel to a host on the gateway's network"
+ noRoleTunnelResource.startTunnel(new GatewayTunnelInfo(
+ buildingRealm,
+ "somegatewayid",
+ GatewayTunnelInfo.Type.TCP,
+ "169.254.169.254",
+ 80))
+
+ then: "the request is refused before the gateway is ever consulted"
+ WebApplicationException ex = thrown()
+ ex.response.status == 403
+ }
+
+ def "A user holding no tunnel role cannot stop a tunnel"() {
+
+ when: "a user with no administrative role stops a tunnel"
+ noRoleTunnelResource.stopTunnel(new GatewayTunnelInfo(buildingRealm, "somegatewayid"))
+
+ then: "the request is refused"
+ WebApplicationException ex = thrown()
+ ex.response.status == 403
+ }
+
+ def "A user holding no tunnel role cannot list a realm's tunnels"() {
+
+ when: "a user with no administrative role lists every tunnel in the realm"
+ noRoleTunnelResource.getAllActiveTunnelInfos(null, buildingRealm)
+
+ then: "the request is refused"
+ WebApplicationException ex = thrown()
+ ex.response.status == 403
+ }
+}
diff --git a/ui/app/manager/src/headers.ts b/ui/app/manager/src/headers.ts
index 43ffe731e..fd770a6d0 100644
--- a/ui/app/manager/src/headers.ts
+++ b/ui/app/manager/src/headers.ts
@@ -86,7 +86,7 @@ export function headerItemGatewayTunnel<S extends AppStateKeyed, A extends AnyAc
value: "gateway-tunnel",
href: "gateway-tunnel",
text: "gatewayTunnel",
- roles: [ClientRole.WRITE_ADMIN, ClientRole.READ_ADMIN],
+ roles: [ClientRole.WRITE_TUNNELS, ClientRole.READ_TUNNELS],
};
}