Document gateway tunneling roles

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

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

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

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