From 5a2b2fa2cbad6380dc3052e990c1cd471e100b4b Mon Sep 17 00:00:00 2001 From: Ekhorn Date: Mon, 7 Sep 2026 14:48:16 +0200 Subject: [PATCH] Document gateway tunneling roles --- docs/tutorials/070-edge-gateway-secure-tunnel.md | 2 +- .../080-gateways-and-devices/10-edge-gateway.md | 15 +++++++++++++++ .../tutorials/070-edge-gateway-secure-tunnel.md | 2 +- .../080-gateways-and-devices/10-edge-gateway.md | 15 +++++++++++++++ 4 files changed, 32 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/070-edge-gateway-secure-tunnel.md b/docs/tutorials/070-edge-gateway-secure-tunnel.md index dfaf4e2a..7a5a7f94 100644 --- a/docs/tutorials/070-edge-gateway-secure-tunnel.md +++ b/docs/tutorials/070-edge-gateway-secure-tunnel.md @@ -30,7 +30,7 @@ Configure the edge instance with the central instance's address and the gateway Open the gateway's local UI from the central instance through the **secure tunnel**, so field engineers can configure and troubleshoot a site without a site visit or a public inbound port. Follow the tunnel setup in [OpenRemote as Edge Gateway](../user-guide/080-gateways-and-devices/10-edge-gateway.md). :::caution -Restrict who can open tunnels and access gateway UIs using [roles and restricted users](./060-enterprise-identity-sso-rbac.md); remote access to field equipment should be tightly scoped. +Remote access to field equipment should be tightly scoped. Opening a tunnel needs the `write:tunnels` role, which is not granted by default - see [who can open and view tunnels](../user-guide/080-gateways-and-devices/10-edge-gateway.md#who-can-open-and-view-tunnels). Combine it with [roles and restricted users](./060-enterprise-identity-sso-rbac.md) to limit which gateways each person can reach. ::: ## Step 5 - Decide what runs where diff --git a/docs/user-guide/080-gateways-and-devices/10-edge-gateway.md b/docs/user-guide/080-gateways-and-devices/10-edge-gateway.md index e717f57c..07550db9 100644 --- a/docs/user-guide/080-gateways-and-devices/10-edge-gateway.md +++ b/docs/user-guide/080-gateways-and-devices/10-edge-gateway.md @@ -177,6 +177,21 @@ On top of the Interaction via the Gateway, you can remotely access the full Mana ![](img/create-gateway-tunnel.png) _Creating a gateway tunnel and opening the manager UI of the remote instance which is connected as a gateway._ +### Who can open and view tunnels + +A tunnel reaches a host and port on the network the gateway sits on, so tunnel access has its own roles rather than following the general admin roles: + +| Role | Grants | +| --- | --- | +| `read:tunnels` | See which tunnels are open | +| `write:tunnels` | Open and close tunnels | + +Both are part of the `read` and `write` composite roles, but neither is given to new users by default. Assign them explicitly to anyone who needs the 'Gateway Tunnels' settings page, a 'Gateway Widget' on a dashboard, or who opens tunnels through the REST API. Users who were given individual roles rather than a composite will not have them. + +A restricted user only sees and controls tunnels for the gateway assets linked to them, on top of the roles above. + +The gateway's own service user does not need either role. An edge gateway is told about its open tunnels over its connection to the central instance, not through the API. + ## Requirements ### Central Manager - Must be running the Keycloak identity provider diff --git a/versioned_docs/version-1.31.0/tutorials/070-edge-gateway-secure-tunnel.md b/versioned_docs/version-1.31.0/tutorials/070-edge-gateway-secure-tunnel.md index dfaf4e2a..7a5a7f94 100644 --- a/versioned_docs/version-1.31.0/tutorials/070-edge-gateway-secure-tunnel.md +++ b/versioned_docs/version-1.31.0/tutorials/070-edge-gateway-secure-tunnel.md @@ -30,7 +30,7 @@ Configure the edge instance with the central instance's address and the gateway Open the gateway's local UI from the central instance through the **secure tunnel**, so field engineers can configure and troubleshoot a site without a site visit or a public inbound port. Follow the tunnel setup in [OpenRemote as Edge Gateway](../user-guide/080-gateways-and-devices/10-edge-gateway.md). :::caution -Restrict who can open tunnels and access gateway UIs using [roles and restricted users](./060-enterprise-identity-sso-rbac.md); remote access to field equipment should be tightly scoped. +Remote access to field equipment should be tightly scoped. Opening a tunnel needs the `write:tunnels` role, which is not granted by default - see [who can open and view tunnels](../user-guide/080-gateways-and-devices/10-edge-gateway.md#who-can-open-and-view-tunnels). Combine it with [roles and restricted users](./060-enterprise-identity-sso-rbac.md) to limit which gateways each person can reach. ::: ## Step 5 - Decide what runs where diff --git a/versioned_docs/version-1.31.0/user-guide/080-gateways-and-devices/10-edge-gateway.md b/versioned_docs/version-1.31.0/user-guide/080-gateways-and-devices/10-edge-gateway.md index e717f57c..07550db9 100644 --- a/versioned_docs/version-1.31.0/user-guide/080-gateways-and-devices/10-edge-gateway.md +++ b/versioned_docs/version-1.31.0/user-guide/080-gateways-and-devices/10-edge-gateway.md @@ -177,6 +177,21 @@ On top of the Interaction via the Gateway, you can remotely access the full Mana ![](img/create-gateway-tunnel.png) _Creating a gateway tunnel and opening the manager UI of the remote instance which is connected as a gateway._ +### Who can open and view tunnels + +A tunnel reaches a host and port on the network the gateway sits on, so tunnel access has its own roles rather than following the general admin roles: + +| Role | Grants | +| --- | --- | +| `read:tunnels` | See which tunnels are open | +| `write:tunnels` | Open and close tunnels | + +Both are part of the `read` and `write` composite roles, but neither is given to new users by default. Assign them explicitly to anyone who needs the 'Gateway Tunnels' settings page, a 'Gateway Widget' on a dashboard, or who opens tunnels through the REST API. Users who were given individual roles rather than a composite will not have them. + +A restricted user only sees and controls tunnels for the gateway assets linked to them, on top of the roles above. + +The gateway's own service user does not need either role. An edge gateway is told about its open tunnels over its connection to the central instance, not through the API. + ## Requirements ### Central Manager - Must be running the Keycloak identity provider