Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions docs/pages/connect-your-client/vnet.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Admonition type="warning">
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 machines.**
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
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
- block browser access to HTTP websites
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just checking if you meant "HTTP APIs" here instead of "HTTP websites"?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the concern is the user navigating to an HTTP website in the browser, and JS on that website then hitting an HTTP API over VNet, so I think it's correct to mention blocking access to HTTP websites in the browser

Copy link
Copy Markdown
Member

@ravicious ravicious Jul 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, I see. I assumed it talks about somehow blocking access to HTTP websites that the user owns, since the previous two points are related to modifying resources owned by the user too.

</Admonition>

## Prerequisites

<Tabs>
Expand Down
42 changes: 26 additions & 16 deletions docs/pages/enroll-resources/application-access/guides/vnet.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -140,28 +140,38 @@ $ 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 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` 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
[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

Expand Down
Loading