From 6664ee38775da0c577f03aa4055d6b69da628a8d Mon Sep 17 00:00:00 2001 From: Nic Klaassen Date: Tue, 8 Jul 2025 18:10:31 -0700 Subject: [PATCH 1/3] [docs] add VNet warnings --- docs/pages/connect-your-client/vnet.mdx | 19 ++++++++ .../application-access/guides/vnet.mdx | 43 ++++++++++++------- 2 files changed, 46 insertions(+), 16 deletions(-) diff --git a/docs/pages/connect-your-client/vnet.mdx b/docs/pages/connect-your-client/vnet.mdx index 245bcf0699840..9b4f68793e994 100644 --- a/docs/pages/connect-your-client/vnet.mdx +++ b/docs/pages/connect-your-client/vnet.mdx @@ -32,6 +32,25 @@ features that traditional VPNs cannot provide. VNet is available on macOS and Windows in Teleport Connect and tsh, with plans for Linux support in a future version. + +VNet's VPN-like experience for app access means that any software running on +the client machine can access Teleport apps at local DNS or IP addresses. + +**Avoid running VNet on shared or multi-user hosts.** +If multiple OS users share the same machine, any user could access Teleport TCP +apps at their local VNet DNS or IP address. + +**Protect HTTP services behind VNet.** +Untrusted websites can potentially use DNS rebinding attacks to bypass the +browser’s Same-Origin Policy and issue plain HTTP requests to VNet IP addresses. +If your Teleport cluster contains TCP apps serving plain HTTP APIs, it is +stronly recommended to either avoid VNet or implement one or more of the +following mitigations for DNS rebinding attacks: +- upgrade these APIs to HTTPS or another protocol +- enforce a Host header allowlist at the HTTP server +- block browser access to HTTP websites + + ## Prerequisites diff --git a/docs/pages/enroll-resources/application-access/guides/vnet.mdx b/docs/pages/enroll-resources/application-access/guides/vnet.mdx index 6510f1bf8391e..f866e05d4bcf8 100644 --- a/docs/pages/enroll-resources/application-access/guides/vnet.mdx +++ b/docs/pages/enroll-resources/application-access/guides/vnet.mdx @@ -140,28 +140,39 @@ $ tsh login --proxy=leaf.example.com --user=email@example.com ### Accessing web apps through VNet -VNet does not officially support [web apps](connecting-apps.mdx) yet. However, technically any web -app is [a TCP app](tcp.mdx), so they can be made available over VNet as well. You'll need to change -`uri` of your application in the Application Service configuration file to use `tcp://` instead of -`http://`. There's also a couple of caveats: +VNet does not officially support [web apps](connecting-apps.mdx) yet. +However, since all web apps are served over TCP, it's possible to convert a web +app to [a TCP app](tcp.mdx) to make it available via VNet. +You'll need to change the `uri` of the application in the app resource or +Application Service configuration file to use `tcp://` instead of `https://`. + +Exposing plain HTTP web apps or APIs via VNet is not recommended. +Untrusted websites can potentially use DNS rebinding attacks to bypass the +browser’s Same-Origin Policy and issue plain HTTP requests to VNet IP addresses. +It is strongly recommended to either avoid VNet for plain HTTP access or +implement one or more of the following mitigations for DNS rebinding attacks: +- upgrade these APIs to HTTPS or another protocol +- enforce a Host header allowlist at the HTTP server +- block browser access to HTTP websites + +There are a few more caveats when converting a Teleport web app to a tcp app: - The Teleport Web UI uses [HSTS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security). - If the application is going to be served from a subdomain of a Proxy Service, it means that the - application will not be accessible in browsers over plain HTTP, even with VNet running. It's - possible to work around this by setting a custom `public_addr` as explained above in this guide. -- If the application needs to be accessible over HTTPS, it must handle TLS connections and return [a valid - cert](connecting-apps.mdx#step-23-optional-configure-tls-and-dns-for-your-web-applications) for the domain it is served on. -- [JWT Token](../jwt/introduction.mdx), [redirect](connecting-apps.mdx#rewrite-redirect) and + If the application is going to be served from a subdomain of a Proxy Service + it must use HTTPS, it will not be accessible in browsers over plain HTTP. + It's possible to work around this by setting a custom `public_addr` that is + not a subdomain of the proxy address as explained above in this guide. +- HTTPS Applications must handle their own TLS connections and have + a valid certificate for the app `public_addr`. +- [JWT Tokens](../jwt/introduction.mdx), [redirects](connecting-apps.mdx#rewrite-redirect) and [header rewrites](connecting-apps.mdx#headers-passthrough) are not available for TCP apps. - Teleport records the start and the end of a session for TCP apps in the audit log, but [session chunks](../../../reference/architecture/session-recording.mdx) are not captured. -When accessing an HTTP API through VNet, the same caveats apply as above, with one main exception. -Since API clients don't need to respect HSTS, the API itself does not need to be served over HTTPS. - -The important thing to understand is that VNet doesn't do anything extra with a connection, other -than passing it through a Teleport Proxy Service. Which application layer protocol is going to be -used depends solely on the app itself and its clients. +The important thing to understand is that VNet doesn't do anything extra with a +TCP connection, it tunnels it directly to the target application's `uri`. +The application layer protocol is determined solely by the app itself and its +clients. ### Further reading From 80cac14491205de85bfd7325d125c8fd20ff8a6f Mon Sep 17 00:00:00 2001 From: Nic Klaassen Date: Wed, 9 Jul 2025 15:37:14 -0700 Subject: [PATCH 2/3] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Rafał Cieślak --- docs/pages/connect-your-client/vnet.mdx | 2 +- .../enroll-resources/application-access/guides/vnet.mdx | 9 ++++----- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/pages/connect-your-client/vnet.mdx b/docs/pages/connect-your-client/vnet.mdx index 9b4f68793e994..741b92bd67d76 100644 --- a/docs/pages/connect-your-client/vnet.mdx +++ b/docs/pages/connect-your-client/vnet.mdx @@ -36,7 +36,7 @@ for Linux support in a future version. VNet's VPN-like experience for app access means that any software running on the client machine can access Teleport apps at local DNS or IP addresses. -**Avoid running VNet on shared or multi-user hosts.** +**Avoid running VNet on shared or multi-user machines.** If multiple OS users share the same machine, any user could access Teleport TCP apps at their local VNet DNS or IP address. diff --git a/docs/pages/enroll-resources/application-access/guides/vnet.mdx b/docs/pages/enroll-resources/application-access/guides/vnet.mdx index f866e05d4bcf8..683d757b67386 100644 --- a/docs/pages/enroll-resources/application-access/guides/vnet.mdx +++ b/docs/pages/enroll-resources/application-access/guides/vnet.mdx @@ -143,8 +143,7 @@ $ tsh login --proxy=leaf.example.com --user=email@example.com VNet does not officially support [web apps](connecting-apps.mdx) yet. However, since all web apps are served over TCP, it's possible to convert a web app to [a TCP app](tcp.mdx) to make it available via VNet. -You'll need to change the `uri` of the application in the app resource or -Application Service configuration file to use `tcp://` instead of `https://`. +You'll need to change the `uri` of the application to use `tcp://` instead of `https://`. Exposing plain HTTP web apps or APIs via VNet is not recommended. Untrusted websites can potentially use DNS rebinding attacks to bypass the @@ -155,13 +154,13 @@ implement one or more of the following mitigations for DNS rebinding attacks: - enforce a Host header allowlist at the HTTP server - block browser access to HTTP websites -There are a few more caveats when converting a Teleport web app to a tcp app: +There are a few more caveats when converting a Teleport web app to a TCP app: - The Teleport Web UI uses [HSTS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security). If the application is going to be served from a subdomain of a Proxy Service it must use HTTPS, it will not be accessible in browsers over plain HTTP. - It's possible to work around this by setting a custom `public_addr` that is - not a subdomain of the proxy address as explained above in this guide. + It's possible to work around this by setting a custom `public_addr` as explained + above in this guide to an address that is not a subdomain of the proxy address. - HTTPS Applications must handle their own TLS connections and have a valid certificate for the app `public_addr`. - [JWT Tokens](../jwt/introduction.mdx), [redirects](connecting-apps.mdx#rewrite-redirect) and From f72ce921317d301d13791e4299b84d6e834a87fd Mon Sep 17 00:00:00 2001 From: Nic Klaassen Date: Wed, 9 Jul 2025 15:37:48 -0700 Subject: [PATCH 3/3] fix typo --- docs/pages/connect-your-client/vnet.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/connect-your-client/vnet.mdx b/docs/pages/connect-your-client/vnet.mdx index 741b92bd67d76..eea8f885c40df 100644 --- a/docs/pages/connect-your-client/vnet.mdx +++ b/docs/pages/connect-your-client/vnet.mdx @@ -44,7 +44,7 @@ apps at their local VNet DNS or IP address. Untrusted websites can potentially use DNS rebinding attacks to bypass the browser’s Same-Origin Policy and issue plain HTTP requests to VNet IP addresses. If your Teleport cluster contains TCP apps serving plain HTTP APIs, it is -stronly recommended to either avoid VNet or implement one or more of the +strongly recommended to either avoid VNet or implement one or more of the following mitigations for DNS rebinding attacks: - upgrade these APIs to HTTPS or another protocol - enforce a Host header allowlist at the HTTP server