[v17] Add docs for multi-port TCP access (#50270)

* Add docs for multi-port TCP access

* Remove unknown word from TODO comment

docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx

@@ -209,6 +209,10 @@ Current limitations for this feature are:
   (The OpenSSH `ssh` client does not work with per-session MFA).
 - Only `kubectl` supports per-session WebAuthn authentication for Kubernetes.
 - For desktop access, only WebAuthn devices are supported.
+- When accessing a
+  [multi-port](../../../enroll-resources/application-access/guides/tcp.mdx#configuring-access-to-multiple-ports)
+  TCP application through [VNet](../../../connect-your-client/vnet.mdx), the first connection over
+  each port triggers an MFA check.
 
 ## Next steps
 

docs/pages/connect-your-client/vnet.mdx

@@ -43,13 +43,23 @@ tsh.app under "Allow in the Background".
 ## Step 3/3. Connect
 
 Once VNet is running, you can connect to the application using the application client you would
-normally use to connect to it. The port number is inconsequential. VNet forwards connections over
-any port number under the public address of the app to the app itself.
+normally use to connect to it.
 
 ```code
 $ psql postgres://[email protected]/postgres
 ```
 
+<Admonition type="note" title="Support for multiple ports">
+Unless the application specifies [multiple
+ports](../enroll-resources/application-access/guides/tcp.mdx#configuring-access-to-multiple-ports),
+VNet proxies connections over any port used by the application client. For multi-port apps, the port
+number must match one of the target ports of the app. To see a list of target ports, click the
+three dot menu next to an application in Teleport Connect or execute `tsh apps ls`.
+
+If [per-session MFA](../admin-guides/access-controls/guides/per-session-mfa.mdx) is enabled, the
+first connection over each port triggers an MFA check.
+</Admonition>
+
 VNet is going to automatically start on the next Teleport Connect launch, unless you stop VNet
 before closing Teleport Connect.
 

docs/pages/enroll-resources/application-access/guides/tcp.mdx

@@ -148,6 +148,56 @@ $ psql postgres://postgres@localhost:55868/postgres
 
 ## Next steps
 
+### Configuring access to multiple ports
+
+By default, the Application Service proxies connections to the `uri` field from the application
+specification. However, Teleport can enable access to multiple ports of a TCP application. An
+application specification in this case needs to have no port number in the `uri` field and a new
+field called `tcp_ports` with a list of ports.
+
+For example, let's take tcp-app from the steps above and add access to port 8080 and port range
+31276-32300. The Application Service definition should look like this:
+
+```yaml
+app_service:
+  enabled: "yes"
+  apps:
+  - name: "tcp-app"
+    uri: tcp://localhost # No port in the URI
+    tcp_ports:
+    - port: 5432 # PostgreSQL
+    - port: 8080 # HTTP server
+    - port: 31276
+      end_port: 32300 # Inclusive end of range
+```
+
+To access the app, [start VNet](../../../connect-your-client/vnet.mdx) and point an application
+client towards the target port:
+
+```code
+$ curl -I http://tcp-app.teleport.example.com:8080
+HTTP/1.1 200 OK
+
+$ psql postgres://[email protected]:5432/postgres
+```
+
+<Notice type="warning">
+There is no RBAC for TCP ports – a user that has access to an application can connect to any port in
+the specification. We&nbsp;strongly recommend specifying only the necessary ports instead of defining a
+wide port range that happens to include ports that are meant to be available.
+</Notice>
+
+{/* TODO: DELETE IN 19.0.0. At this point all compatible servers and clients are going
+to support multiple ports. */}
+
+Support for multiple ports is available in Teleport v17.1+. Connections from Teleport clients that
+do not support multiple ports are routed to the first port from the application specification. An
+Application Service that does not support multiple ports will not be able to handle traffic to a
+multi-port application if it receives such application through [dynamic
+registration](./dynamic-registration.mdx) from an Auth Service.
+
+### Further reading
+
 - Learn about [access controls](../controls.mdx) for applications.
 - Learn how to [connect to TCP apps with VNet](../../../connect-your-client/vnet.mdx) and
   [configure VNet for custom `public_addr`](vnet.mdx).