Designing Jurisdictional Ingress Routes
For applications with regulatory or compliance constraints on where end-users can originate from (EU-only services, US-residents-only healthcare apps, jurisdiction-restricted financial products), ingress routing is the structural answer. Rather than enforcing the constraint at the application layer (which works until someone forgets a check), Pathmakers compose a Residency Node into the Gate Studio identity flow: requests that fail the geographic match are rejected at ingress, before they reach the platform's core authentication or data layers.
This tutorial walks through configuring an EU-only login flow for a healthcare app.
Prerequisites
- A Pathmaker-role account on the project
- Gate Studio enabled
- An existing login page (from Building Custom Branded Login Pages) or a fresh one
- Clear understanding of the jurisdictional rule you're enforcing
Step 1 — Define the geographic rule
Be specific about what you're enforcing. Common patterns:
| Rule | Practical meaning |
|---|---|
| Country whitelist | Allow only specific countries (e.g., [DE, FR, IT, ES, NL, BE, AT, PL]) |
| Country blacklist | Block specific countries; allow rest of world |
| Region whitelist | Allow only specified continents/regions (e.g., [EU]) |
| IP-allowlist | Allow only specific IP ranges (corporate intranet, partner gateways) |
| Combined | Country whitelist AND IP-allowlist (highest restriction) |
For our healthcare app: EU member states only (country whitelist).
Step 2 — Open the identity stream editor
In Gate Studio, navigate to the login page you want to constrain. Click Identity stream to open the flow editor — a visual canvas showing the sequence of nodes a request traverses from ingress to authenticated session.
The default flow has three nodes:
[Ingress] → [Authenticator] → [Session issuance]
Step 3 — Drop a Residency Node
From the node palette, drag Residency Node onto the canvas. Place it between Ingress and Authenticator:
[Ingress] → [Residency Node] → [Authenticator] → [Session issuance]
The Residency Node runs before any authentication takes place — a rejection here means the user never sees the credential prompt.
Step 4 — Configure the Residency Node
Click the node to open its configuration:
type: residency_node
match:
type: country_whitelist
countries: [DE, FR, IT, ES, NL, BE, AT, PL, IE, DK, SE, FI, PT, GR, RO, BG, HR, CZ, HU, SK, SI, EE, LV, LT, LU, MT, CY]
on_match:
proceed: true
on_no_match:
action: reject
reject_with:
http_status: 451 # "Unavailable for Legal Reasons"
page: "outside-eu-rejection" # a separate Gate Studio page explaining the constraint
audit_event: residency.eu_only_check
Notable fields:
match.countries— the EU member states (use ISO 3166-1 alpha-2 codes; Gate Studio offers presets for common groupings)on_no_match.action: reject— rejected requests do not proceed; alternative actions includeredirect(to a partner site) andlog_and_proceed(for monitoring without blocking)reject_with.page— a separate Gate Studio page that explains the rejection in user-friendly language (compose this in the same Gate Studio surface)audit_event— the event name in the audit log for these checks
Step 5 — Geo source and confidence
Geographic identification at the ingress layer uses:
| Source | Confidence |
|---|---|
| IP geolocation | Coarse; defeated by VPN; usually accurate to the country level |
| TLS SNI domain hints | Useful for custom regional domains (e.g., eu.your-app.com) |
| HTTP Accept-Language | Weak; user-configurable; informational only |
For most jurisdictional rules, IP geolocation is the operative signal. The Residency Node uses MaxMind GeoIP2 City (refreshed weekly); accuracy at the country level is approximately 99%.
The Residency Node configuration includes an optional vpn_handling flag:
vpn_handling:
detection: enabled # detect known VPN exit IPs
action: reject_with_message # reject + render a different page explaining VPN policy
VPN detection uses a known-VPN-exit IP database; it is not perfect (residential proxies can defeat it), but it raises the bar above default IP geolocation.
Step 6 — Test the flow
Use Gate Studio's geographic-simulation preview:
Preview as: [Country selector] → DE
The preview routes the synthetic request through the Residency Node as if it originated from Germany. The flow should proceed to the authenticator.
Switch the country to a non-EU country (US):
Preview as: [Country selector] → US
The preview should show the rejection: HTTP 451 status, the custom rejection page rendered.
Try the VPN scenario if VPN detection is configured:
Preview as: [Country selector] → DE + [VPN exit IP]
The rejection should fire with the VPN-specific page.
Step 7 — Layer with other nodes
The identity stream supports composing multiple nodes for richer policies. Some common compositions:
Country whitelist + IP allowlist:
[Ingress] → [Residency Node: EU] → [IP Allowlist: corporate ranges only] → [Authenticator] → ...
Both checks must pass; rejection at either node terminates the request.
Time-of-day constraint:
[Ingress] → [Residency Node: EU] → [Time Window: 09:00–18:00 CET weekdays] → [Authenticator] → ...
For internal applications with operating-hours constraints.
Suspicious-source check:
[Ingress] → [Residency Node: EU] → [Threat Intelligence: block known-bad IPs] → [Rate Limiter] → [Authenticator] → ...
Layering in threat-intel feeds and rate limiting before any authenticator runs.
Step 8 — Publish and observe
Click Publish. The new identity stream goes live; subsequent requests to the login page traverse the Residency Node.
In Lookout, the residency.eu_only_check audit event surfaces:
- Pass rate over time
- Rejection count by source country
- Rejection count by VPN-detection
- Geographic distribution of inbound traffic
The rejection count is operationally informative. Large numbers of rejections may indicate either a legitimate access-pattern (people outside the EU trying to reach the app, which is the constraint working as designed) or a misconfiguration (your sales team in NYC suddenly cannot reach the internal admin surface — fix the IP allowlist).
What just happened
You added a structural jurisdictional constraint to your application's ingress without modifying application code. The constraint:
- Runs at ingress, before any credential check
- Cannot be bypassed by an authenticated session (because authentication never starts)
- Produces audit-log evidence of every check
- Surfaces analytics through Lookout for ongoing observation
- Can be modified through Gate Studio without a deploy
For regulated applications, this is the cleanest structural pattern: the constraint is the platform's, not the application's.
Next
- Building Custom Branded Login Pages — the underlying surface this builds on.
- Identity-Native Telemetry Mapping — surfacing the residency-check stats in monitoring dashboards.
- Regions & residency — data residency (where data lives) vs ingress residency (where requests come from); both contribute to the sovereign posture.