docs(tcp): document forward-proxy behavior for pomerium-cli tcp#2218
Closed
desimone wants to merge 1 commit into
Closed
docs(tcp): document forward-proxy behavior for pomerium-cli tcp#2218desimone wants to merge 1 commit into
desimone wants to merge 1 commit into
Conversation
The TCP tunnel does not traverse an HTTP/HTTPS forward proxy: only the auth/token requests honor HTTP_PROXY/HTTPS_PROXY, while the tunnel's connection check and CONNECT are dialed directly. Document this on the TCP capabilities page, distinguish it from the bastion-host feature, and give two workarounds (narrow direct-egress allowlist, jump host).
✅ Deploy Preview for pomerium-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Bobby DeSimone seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account. You have signed the CLA already but the status is still pending? Let us recheck it. |
Contributor
Author
|
Hopefully do-able pomerium/cli#691 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a Connecting through an HTTP forward proxy section to the TCP capabilities page (
/docs/capabilities/non-http/tcp#forward-proxy).It documents that
pomerium-cli tcpdoes not route the tunnel through an HTTP/HTTPS forward proxy (e.g. Squid): only the authentication/token requests honorHTTP_PROXY/HTTPS_PROXY, while the tunnel's initial connection check and theCONNECTare dialed directly. It distinguishes this from the existing Bastion host feature (Pomerium-as-bastion, not an arbitrary proxy) and gives two workarounds: a narrow direct-egress allowlist for the Pomerium endpoint, or a jump host with direct egress reached over SSH-L.Why
Recurring question from PoC/enterprise customers whose client networks have no direct outbound HTTPS and must egress through a forward proxy. The behavior was undocumented, leading to confusion (e.g. attempts to use Squid as a bastion). Complements the existing "Two ports, one transport" / L4-edge guidance for egress-restricted environments. Relates to ENG-4040.
Verification
Behavior verified end-to-end in a Squid + Pomerium docker-compose lab (Pomerium server v0.32.0;
pomerium-clibuilt from v0.32.1-rc.1 source). With the client restricted to proxy-only egress andHTTPS_PROXYset, the tunnel's probe andCONNECTdial the Pomerium endpoint directly and the proxy logs nothing for the tunnel; a control request through the same proxy is logged. Both documented workarounds were exercised and returned the upstream payload.yarn format-check,yarn cspell, andyarn buildpass.AI assistance
Drafted with Claude Code (Opus). Claude built the docker-compose proof lab, ran the tests, and wrote this docs section. The behavior and the proofs were then independently re-run and verified by a human (clean
docker compose up, all checks green), and the wording was corrected for precision (the auth-helper fetch is what honors the proxy; the 302 comes from the direct tunnel attempt).