Skip to main content

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:

RulePractical meaning
Country whitelistAllow only specific countries (e.g., [DE, FR, IT, ES, NL, BE, AT, PL])
Country blacklistBlock specific countries; allow rest of world
Region whitelistAllow only specified continents/regions (e.g., [EU])
IP-allowlistAllow only specific IP ranges (corporate intranet, partner gateways)
CombinedCountry 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.

IngressResidency NodeEU country listmatchAuthenticatorSessionissuanceno matchRejectHTTP 451outside-eu-rejection pageAudit eventresidency.eu_only_check
The Residency Node sits ahead of the Authenticator, so a request from outside the rule is rejected before any 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 include redirect (to a partner site) and log_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:

SourceConfidence
IP geolocationCoarse; defeated by VPN; usually accurate to the country level
TLS SNI domain hintsUseful for custom regional domains (e.g., eu.your-app.com)
HTTP Accept-LanguageWeak; 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​