Skip to content

[Fundamentals, SSL, Workers] Clarify visitor IP header trust - #34792

Open
irvinebroque wants to merge 6 commits into
productionfrom
docs/visitor-ip-header-trust
Open

[Fundamentals, SSL, Workers] Clarify visitor IP header trust#34792
irvinebroque wants to merge 6 commits into
productionfrom
docs/visitor-ip-header-trust

Conversation

@irvinebroque

@irvinebroque irvinebroque commented Oct 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

Corrects guidance that could cause origins to treat visitor IP headers or a Cloudflare source IP as proof that a request passed through their zone and security rules.

  • Clarifies Worker subrequest behavior by destination: external destinations can receive a Worker-chosen CF-Connecting-IP, while X-Real-IP is stripped before delivery.
  • Adds canonical visitor IP trust guidance and links it from Workers, DNS, Transform Rules, and True-Client-IP documentation. Explicitly distinguishes IP-based access restrictions from user or client authentication.
  • Prominently recommends Cloudflare-to-origin mTLS using zone-level or per-hostname AOP with a dedicated certificate, required and verified at the origin. Distinguishes this from shared Cloudflare IP ranges and global AOP certificates, with Tunnel as an alternative.
  • Adds authentication prerequisites to visitor IP restoration examples and replaces Lighttpd's IPv6 “trust all” workaround with explicit trusted proxy ranges.

This corrects documentation of existing behavior. Related public context: Worker subrequests to destinations outside Cloudflare.

Validation:

  • pnpm run check: passed.
  • pnpm run format: passed.
  • All 10 modified MDX files compile; all added internal links and anchors resolve.
  • git diff --check: passed.
  • pnpm run build (9,610 pages) and pnpm run lint:nimbus: passed before the final wording-only changes; not rerun.
  • Final authentication wording: MDX compilation, internal links and anchors, formatting, and diff checks passed.

Documentation checklist

  • The change adheres to the documentation style guide.
  • If a larger change - such as adding a new page- an issue has been opened in relation to any incorrect or out of date information that this PR fixes.

@irvinebroque
irvinebroque marked this pull request as ready for review October 30, 2026 19:29
@cloudflare-docs-bot

cloudflare-docs-bot Bot commented Oct 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

AI Review

✅ Reviewed 831906d · 0 findings · incremental

Resolved (5) · Dismissed (0)
  • Resolved: Directional reference "below" · Verified at head: http-headers.mdx line 25 now reads 'Refer to CF-Connecting-IP in Worker subrequests'. The directional 'as described below' was removed per the style rule.
  • Resolved: Directional reference "below" · Verified at head: line 17 caution now reads 'The visitor IP restoration configurations restore IP values...' and links to the trust requirements. 'The configurations below' was removed per the directional-word style rule.
  • Resolved: Directional reference "below" · Verified at head: HAProxy section now reads 'The from_cf source IP check is an additional network filter and does not identify your zone:'. The directional 'below' reference no longer exists.
  • Resolved: Semicolon joining two independent clauses · Verified at head: line 273 now reads 'The following example shows one range of each type. Add all remaining Cloudflare ranges before using it:'. The semicolon joining independent clauses was replaced with a period.
  • Resolved: Filename bolded instead of monospace · Verified at head: line 271 now reads 'Open lighttpd.conf and add mod_extforward...'. The filename is monospace, not bold, satisfying the filename-monospace style rule.
Commands
  • /review Run a review now.
  • /full-review Review the entire PR diff.
  • /disable-auto-review Stop automatic reviews.
  • /rebase Rebase against production.

@irvinebroque
irvinebroque requested review from a team, krys-cf and ngayerie as code owners October 30, 2026 19:29
@cloudflare-docs-bot

cloudflare-docs-bot Bot commented Oct 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Review coverage

🟡 7 ownership areas need approval.

Suggested reviewers: @dinasaur404 @chreo @hannes-cf @jhutchings1 @mvvmm @mbullock1986 @baubuchon-cf @lgarofalo @nikitacano

Needs approval Eligible approvers Suggested
workers @GregBrimble, @irvinebroque, @korinne, @MattieTK, @mikenomitch, @vy-ton, @WalshyDev, @cloudflare/deploy-config, @cloudflare/dev-plat-leads, @cloudflare/workers-runtime-1, @cloudflare/wrangler, @cloudflare/product-owners dinasaur404
dns @chreo, @dklbreitling, @esomoza-cf, @fattouche, @hannes-cf, @kerolasa, @matildeopbravo, @mworsley-cloudflare, @sebastiaanyn, @svenr-cf, @vavrusa, @vendemiat, @Woutifier, @xofyarg, @cloudflare/product-owners chreo, hannes-cf
fundamentals @adambouhmad, @jhutchings1, @cloudflare/product-owners jhutchings1
learning-paths @cloudflare/product-owners No suggestions
network @mbullock1986, @cloudflare/product-owners mvvmm
rules @maurizioabba, @mbullock1986, @smarsh-cf, @cloudflare/appsec-reviewers, @cloudflare/product-owners mbullock1986
ssl @baubuchon-cf, @lgarofalo, @cloudflare/appsec-reviewers, @cloudflare/product-owners baubuchon-cf, lgarofalo, nikitacano
✅ 1 area already covered
Area Approved by
support
1 file changed		 stechedo
CODEOWNERS mappings for displayed areas (8)
Pattern Owners
/src/content/docs/workers/ @GregBrimble, @irvinebroque, @korinne, @MattieTK, @mikenomitch, @vy-ton, @WalshyDev, @cloudflare/deploy-config, @cloudflare/dev-plat-leads, @cloudflare/workers-runtime-1, @cloudflare/wrangler, @cloudflare/product-owners
/src/content/docs/dns/ @chreo, @dklbreitling, @esomoza-cf, @fattouche, @hannes-cf, @kerolasa, @matildeopbravo, @mworsley-cloudflare, @sebastiaanyn, @svenr-cf, @vavrusa, @vendemiat, @Woutifier, @xofyarg, @cloudflare/product-owners
/src/content/docs/fundamentals/ @adambouhmad, @jhutchings1, @cloudflare/product-owners
/src/content/partials/learning-paths/ @cloudflare/product-owners
/src/content/docs/network/ @mbullock1986, @cloudflare/product-owners
/src/content/docs/rules/ @maurizioabba, @mbullock1986, @smarsh-cf, @cloudflare/appsec-reviewers, @cloudflare/product-owners
/src/content/docs/ssl/ @baubuchon-cf, @lgarofalo, @cloudflare/appsec-reviewers, @cloudflare/product-owners
/src/content/docs/support/ @krys-cf, @ngayerie, @shanecloudflare, @stechedo, @zeinjaber, @cloudflare/customer-support, @cloudflare/product-owners

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Oct 30, 2026 •
edited
Loading

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://docs-visitor-ip-header-trust.previews.developers.cloudflare.com (commit 831906d)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗		 https://09cd7a03.previews.developers.cloudflare.com 831906d 2026-10-31T00:47:11.908Z Visit the dashboard ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗		 https://7eb1144c.previews.developers.cloudflare.com 8382b13 2026-10-30T19:37:50.488Z Visit the dashboard ↗

@github-actions

github-actions Bot commented Oct 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Worker Preview URL: https://gh-docs-visitor-ip-header-trust.previews.developers.cloudflare.com
Worker Preview Deployment URL: https://0eec4a7a.previews.developers.cloudflare.com

Files with changes (up to 15)

Original Link Updated Link
https://developers.cloudflare.com/support/troubleshooting/restoring-visitor-ips/restoring-original-visitor-ips/ https://gh-docs-visitor-ip-header-trust.previews.developers.cloudflare.com/support/troubleshooting/restoring-visitor-ips/restoring-original-visitor-ips/
https://developers.cloudflare.com/fundamentals/reference/http-headers/ https://gh-docs-visitor-ip-header-trust.previews.developers.cloudflare.com/fundamentals/reference/http-headers/
https://developers.cloudflare.com/ssl/origin-configuration/authenticated-origin-pull/ https://gh-docs-visitor-ip-header-trust.previews.developers.cloudflare.com/ssl/origin-configuration/authenticated-origin-pull/
https://developers.cloudflare.com/dns/proxy-status/use-cases/ https://gh-docs-visitor-ip-header-trust.previews.developers.cloudflare.com/dns/proxy-status/use-cases/
https://developers.cloudflare.com/fundamentals/concepts/cloudflare-ip-addresses/ https://gh-docs-visitor-ip-header-trust.previews.developers.cloudflare.com/fundamentals/concepts/cloudflare-ip-addresses/
https://developers.cloudflare.com/network/true-client-ip-header/ https://gh-docs-visitor-ip-header-trust.previews.developers.cloudflare.com/network/true-client-ip-header/
https://developers.cloudflare.com/rules/transform/request-header-modification/ https://gh-docs-visitor-ip-header-trust.previews.developers.cloudflare.com/rules/transform/request-header-modification/
https://developers.cloudflare.com/workers/runtime-apis/headers/ https://gh-docs-visitor-ip-header-trust.previews.developers.cloudflare.com/workers/runtime-apis/headers/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@stechedo stechedo stechedo approved these changes
@GregBrimble GregBrimble Awaiting requested review from GregBrimble GregBrimble is a code owner
@korinne korinne Awaiting requested review from korinne korinne is a code owner
@MattieTK MattieTK Awaiting requested review from MattieTK MattieTK is a code owner
@vy-ton vy-ton Awaiting requested review from vy-ton vy-ton is a code owner
@WalshyDev WalshyDev Awaiting requested review from WalshyDev WalshyDev is a code owner
@krys-cf krys-cf Awaiting requested review from krys-cf krys-cf is a code owner
@ngayerie ngayerie Awaiting requested review from ngayerie ngayerie is a code owner
@zeinjaber zeinjaber Awaiting requested review from zeinjaber zeinjaber is a code owner
@baubuchon-cf baubuchon-cf Awaiting requested review from baubuchon-cf baubuchon-cf is a code owner
@lgarofalo lgarofalo Awaiting requested review from lgarofalo lgarofalo is a code owner
@maurizioabba maurizioabba Awaiting requested review from maurizioabba maurizioabba is a code owner
@mbullock1986 mbullock1986 Awaiting requested review from mbullock1986 mbullock1986 is a code owner
@smarsh-cf smarsh-cf Awaiting requested review from smarsh-cf smarsh-cf is a code owner
@AdamBouhmad AdamBouhmad Awaiting requested review from AdamBouhmad AdamBouhmad is a code owner
@jhutchings1 jhutchings1 Awaiting requested review from jhutchings1 jhutchings1 is a code owner
@chreo chreo Awaiting requested review from chreo chreo is a code owner
@dklbreitling dklbreitling Awaiting requested review from dklbreitling dklbreitling is a code owner
@esomoza-cf esomoza-cf Awaiting requested review from esomoza-cf esomoza-cf is a code owner
@hannes-cf hannes-cf Awaiting requested review from hannes-cf hannes-cf is a code owner
@matildeopbravo matildeopbravo Awaiting requested review from matildeopbravo matildeopbravo is a code owner
@SebastiaanYN SebastiaanYN Awaiting requested review from SebastiaanYN SebastiaanYN is a code owner
@svenr-cf svenr-cf Awaiting requested review from svenr-cf svenr-cf is a code owner
@vendemiat vendemiat Awaiting requested review from vendemiat vendemiat is a code owner
@Woutifier Woutifier Awaiting requested review from Woutifier Woutifier is a code owner
@xofyarg xofyarg Awaiting requested review from xofyarg xofyarg is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

product:dns Issues or PRs related to DNS product:fundamentals product:learning-paths product:network product:rules Related to rules product:ssl Related to SSL product:support product:workers Related to Workers product size/m

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@irvinebroque @stechedo