replacing documentation references to port_forwarding with ssh_port_f…

…orwarding and adding some additional context to the rbac reference (#50361)
gravitational · Dec 19, 2024 · 561711d · 561711d
1 parent 017abd4
commit 561711d
Show file tree

Hide file tree

Showing 11 changed files with 113 additions and 19 deletions.
diff --git a/docs/pages/admin-guides/api/rbac.mdx b/docs/pages/admin-guides/api/rbac.mdx
@@ -859,7 +859,11 @@ spec:
         enabled: true
     max_session_ttl: 30h0m0s
     pin_source_ip: false
-    port_forwarding: true
+    ssh_port_forwarding:
+      remote:
+        enabled: true
+      local:
+        enabled: true
     record_session:
       default: best_effort
       desktop: true
@@ -906,7 +910,11 @@ spec:
         enabled: true
     max_session_ttl: 30h0m0s
     pin_source_ip: false
-    port_forwarding: true
+    ssh_port_forwarding:
+      remote:
+        enabled: true
+      local:
+        enabled: true
     record_session:
       default: best_effort
       desktop: true

diff --git a/docs/pages/enroll-resources/server-access/rbac.mdx b/docs/pages/enroll-resources/server-access/rbac.mdx
@@ -135,8 +135,18 @@ spec:
     create_host_user_mode: keep
     # forward_agent controls whether SSH agent forwarding is allowed
     forward_agent: true
-    # port_forwarding controls whether TCP port forwarding is allowed for SSH
-    port_forwarding: true
+    # ssh_port_forwarding controls which TCP port forwarding modes are allowed over SSH. This replaces
+    # the deprecated port_forwarding field, which did not differentiate between remote and local
+    # port forwarding modes. If you have any existing roles that allow forwarding by enabling the
+    # legacy port_forwarding field then the forwarding controls configured in ssh_port_forwarding will be
+    # ignored.
+    ssh_port_forwarding:
+      # configures remote port forwarding behavior
+      remote:
+        enabled: true
+      # configures local port forwarding behavior
+      local:
+        enabled: true
     # ssh_file_copy controls whether file copying (SCP/SFTP) is allowed.
     # Defaults to true.
     ssh_file_copy: false

diff --git a/docs/pages/includes/role-spec.mdx b/docs/pages/includes/role-spec.mdx
@@ -13,8 +13,18 @@ spec:
     max_session_ttl: 8h
     # forward_agent controls whether SSH agent forwarding is allowed
     forward_agent: true
-    # port_forwarding controls whether TCP port forwarding is allowed for SSH
-    port_forwarding: true
+    # ssh_port_forwarding controls which TCP port forwarding modes are allowed over SSH. This replaces
+    # the deprecated port_forwarding field, which did not differentiate between remote and local
+    # port forwarding modes. If you have any existing roles that allow forwarding by enabling the
+    # legacy port_forwarding field then the forwarding controls configured in ssh_port_forwarding will be
+    # ignored.
+    ssh_port_forwarding:
+      # configures remote port forwarding behavior
+      remote:
+        enabled: true
+      # configures local port forwarding behavior
+      local:
+        enabled: true
     # ssh_file_copy controls whether file copying (SCP/SFTP) is allowed.
     # Defaults to true.
     ssh_file_copy: false

diff --git a/docs/pages/reference/access-controls/roles.mdx b/docs/pages/reference/access-controls/roles.mdx
@@ -52,7 +52,7 @@ user:
 | - | - | - |
 | `max_session_ttl` | Max. time to live (TTL) of a user's SSH certificates | The shortest TTL wins |
 | `forward_agent` | Allow SSH agent forwarding | Logical "OR" i.e. if any role allows agent forwarding, it's allowed |
-| `port_forwarding` | Allow TCP port forwarding | Logical "OR" i.e. if any role allows port forwarding, it's allowed |
+| `ssh_port_forwarding` | Allow TCP port forwarding | Logical "AND" i.e. if any role denies port forwarding, it's denied |
 | `ssh_file_copy` | Allow SCP/SFTP | Logical "AND" i.e. if all roles allows file copying, it's allowed |
 | `client_idle_timeout` | Forcefully terminate active sessions after an idle interval | The shortest timeout value wins, i.e. the most restrictive value is selected |
 | `disconnect_expired_cert` | Forcefully terminate active sessions when a client certificate expires | Logical "OR" i.e. evaluates to "yes" if at least one role requires session termination |

diff --git a/docs/pages/reference/terraform-provider/resources/role.mdx b/docs/pages/reference/terraform-provider/resources/role.mdx
@@ -27,9 +27,17 @@ resource "teleport_role" "example" {
 
   spec = {
     options = {
-      forward_agent           = false
-      max_session_ttl         = "7m"
-      port_forwarding         = false
+      forward_agent   = false
+      max_session_ttl = "7m"
+      ssh_port_forwarding = {
+        remote = {
+          enabled = false
+        }
+
+        local = {
+          enabled = false
+        }
+      }
       client_idle_timeout     = "1h"
       disconnect_expired_cert = true
       permit_x11_forwarding   = false

diff --git a/examples/resources/admin.yaml b/examples/resources/admin.yaml
@@ -28,5 +28,9 @@ spec:
     - network
     forward_agent: true
     max_session_ttl: 30h0m0s
-    port_forwarding: true
+    ssh_port_forwarding:
+      remote:
+        enabled: true
+      local:
+        enabled: true
 version: v3
diff --git a/examples/resources/user.yaml b/examples/resources/user.yaml
@@ -56,5 +56,9 @@ spec:
     - network
     forward_agent: true
     max_session_ttl: 30h0m0s
-    port_forwarding: true
+    ssh_port_forwarding:
+      remote:
+        enabled: true
+      local:
+        enabled: true
 version: v3
diff --git a/integrations/terraform/examples/resources/teleport_role/resource.tf b/integrations/terraform/examples/resources/teleport_role/resource.tf
@@ -13,9 +13,17 @@ resource "teleport_role" "example" {
 
   spec = {
     options = {
-      forward_agent           = false
-      max_session_ttl         = "7m"
-      port_forwarding         = false
+      forward_agent   = false
+      max_session_ttl = "7m"
+      ssh_port_forwarding = {
+        remote = {
+          enabled = false
+        }
+
+        local = {
+          enabled = false
+        }
+      }
       client_idle_timeout     = "1h"
       disconnect_expired_cert = true
       permit_x11_forwarding   = false

diff --git a/integrations/terraform/reference.mdx b/integrations/terraform/reference.mdx
@@ -2051,7 +2051,8 @@ Options is for OpenSSH options like agent forwarding.
 | max_sessions               | number           |          | MaxSessions defines the maximum number of concurrent sessions per connection.                                                                                                                          |
 | permit_x11_forwarding      | bool             |          | PermitX11Forwarding authorizes use of X11 forwarding.                                                                                                                                                  |
 | pin_source_ip              | bool             |          | PinSourceIP forces the same client IP for certificate generation and usage                                                                                                                             |
-| port_forwarding            | bool             |          |                                                                                                                                                                                                        |
+| ssh_port_forwarding        | object           |          | SSHPortForwarding configures what types of SSH port forwarding are allowed by a role.                                                                                                                  |
+| port_forwarding            | bool             |          | Deprecated: Use SSHPortForwarding instead.                                                                                                                                                             |
 | record_session             | object           |          | RecordDesktopSession indicates whether desktop access sessions should be recorded. It defaults to true unless explicitly set to false.                                                                 |
 | request_access             | string           |          | RequestAccess defines the access request strategy (optional|note|always) where optional is the default.                                                                                                |
 | request_prompt             | string           |          | RequestPrompt is an optional message which tells users what they aught to request.                                                                                                                     |
@@ -2085,6 +2086,31 @@ SAML are options related to the Teleport SAML IdP.
 |---------|------|----------|-------------|
 | enabled | bool |          |             |
 
+##### spec.options.ssh_port_forwarding
+
+SSHPortForwarding configures what types of SSH port forwarding are allowed by a role.
+
+|  Name  |  Type  | Required |                    Description                            |
+|--------|--------|----------|-----------------------------------------------------------|
+| remote | object |          | remote contains options related to remote port forwarding |
+| local  | object |          | local contains options related to local port forwarding   |
+
+###### spec.options.ssh_port_forwarding.remote
+
+remote contains options related to remote port forwarding
+
+|  Name   | Type | Required | Description |
+|---------|------|----------|-------------|
+| enabled | bool |          |             |
+
+###### spec.options.ssh_port_forwarding.local
+
+local contains options related to local port forwarding
+
+|  Name   | Type | Required | Description |
+|---------|------|----------|-------------|
+| enabled | bool |          |             |
+
 ##### spec.options.record_session
 
 RecordDesktopSession indicates whether desktop access sessions should be recorded. It defaults to true unless explicitly set to false.
@@ -2114,11 +2140,19 @@ resource "teleport_role" "example" {
     options = {
       forward_agent           = false
       max_session_ttl         = "7m"
-      port_forwarding         = false
       client_idle_timeout     = "1h"
       disconnect_expired_cert = true
       permit_x11_forwarding   = false
       request_access          = "denied"
+      ssh_port_forwarding     = {
+        remote = {
+          enabled = false
+        }
+
+        local = {
+          enabled = false
+        }
+      }
     }
 
     allow = {

diff --git a/rfd/0007-rbac-oss.md b/rfd/0007-rbac-oss.md
@@ -90,7 +90,11 @@ role:
    name: user
 spec:
   options:
-    port_forwarding: true
+    ssh_port_forwarding:
+      remote:
+        enabled: true
+      local:
+        enabled: true
     max_session_ttl: 30h
     forward_agent: true
     enhanced_recording: ['command', 'network']

diff --git a/rfd/0008-application-access.md b/rfd/0008-application-access.md
@@ -303,7 +303,11 @@ version: v3
 spec:
   options:
     forward_agent: true
-    port_forwarding: false
+    ssh_port_forwarding:
+      remote:
+        enabled: false
+      local:
+        enabled: false
   allow:
     logins: ["rjones"]
     # Application labels define labels that an application must match for this