Skip to main content

Restrict IPs

Overview

The Restrict IPs Traffic Policy action allows you to allow or deny traffic based on the source IP address of connections to your ngrok endpoints.

You can define rules using either Allow and Deny lists, or Reference IDs to existing ngrok IP Policies.

Configuration Reference

The Traffic Policy configuration reference for this action.

Supported Phases

on_http_request, on_http_response, on_tcp_connect

Type

restrict-ips

Configuration Fields

  • enforcebooleanRequired

    Default true. If false, continue to the next action even if the IP is not permitted.

  • allowarray of strings

    A list of CIDRs that are allowed.

  • denyarray of strings

    A list of CIDRs that are denied.

  • ip_policiesarray of refs

    List of IP Policy identifiers to be checked if the source IP is allowed access.

Behavior

Evaluation of Rules

This action evaluates the configured rules against the layer 4 source IP (conn.client_ip) of a connection. HTTP headers like X-Forwarded-For are never used.

Allow and Deny Conditions

A connection is allowed only if its source IP matches at least one of the allowed CIDRs and does not match any of the denied CIDRs.

Building CIDR Sets

The set of allowed and denied CIDRs are built from:

  • The CIDRs specified in the allow and deny fields.
  • The CIDRs belonging to the ngrok IP Policies specified in the ip_policies field.

Denied Connection Handling

If this action denies the connection:

  • The connection is immediately closed.
  • The upstream server is never reached.
  • No further actions or policy rules in the policy configuration will be executed.

IPv6 Support

This action supports IPv6 addresses for all IP rules. You may use standard abbreviated notations such as "::/0".

Don't forget to create IPv6 rules. It is easy to test with only IPv4 and then suddenly things don't work as expected because you forgot to create IPv6 rules.

Examples

Restricting Access with Allow and Deny Lists

The following Traffic Policy configuration demonstrates how to restrict access to specific IP addresses using the restrict-ips action.

Example Traffic Policy Document

---
on_tcp_connect:
- actions:
- type: "restrict-ips"
config:
enforce: true
allow:
- "1.1.1.1/32"
deny:
- "e680:5791:be4c:5739:d959:7b94:6d54:d4b4/128"

This configuration will ensure that only requests from the IP 1.1.1.1 are allowed, while requests from the IP e680:5791:be4c:5739:d959:7b94:6d54:d4b4 are denied.

Example Request

If the request comes from an allowed IP, the response will proceed as normal. If the request comes from a denied IP, the connection to the server will be immediately closed:

$ curl --insecure https://example.ngrok.app
curl: (52) Empty reply from server

Restricting Access with IP Policies

The following Traffic Policy configuration demonstrates how to restrict access using the restrict-ips action with IP Policies.

Example Traffic Policy Document

---
on_tcp_connect:
- actions:
- type: "restrict-ips"
config:
enforce: true
ip_policies:
- "ipp_1yjqdrIBwgciY2I9zH2EelgBbJF"

This configuration will ensure that the IP Policies specified ipp_1yjqdrIBwgciY2I9zH2EelgBbJF are enforced against incoming traffic.

Example Request

If the request comes from an allowed IP, the response will proceed as normal. If the request comes from a denied IP, the connection to the server will be immediately closed:

$ curl --insecure https://example.ngrok.app
curl: (52) Empty reply from server

Test Restricting IPs

The following Traffic Policy configuration demonstrates how to test restricting IPs using the log action with the restrict-ips action and IP Policies.

Example Traffic Policy Document

---
on_tcp_connect:
- actions:
- type: "restrict-ips"
config:
enforce: false
ip_policies:
- "ipp_1yjqdrIBwgciY2I9zH2EelgBbJF"
- type: "log"
config:
metadata:
message: "Restrict IPs action would be ${actions.ngrok.restrict_ips.action} for
${conn.client_ip}."
matched_cidr: "${actions.ngrok.restrict_ips.matched_cidr}"
error_code: "${actions.ngrok.restrict_ips.error.code}"
error_message: "${actions.ngrok.restrict_ips.error.message}"

This configuration will test the incoming client IP against the specified IP Policy ipp_1yjqdrIBwgciY2I9zH2EelgBbJF without enforcing it, then log the result using the log action.

Example Request

The following request will be allowed and an event will be logged:

$ curl --insecure https://example.ngrok.app

Action Result Variables

The following variables are made available for use in subsequent expressions and CEL interpolations after the action has run. Variable values will only apply to the last action execution, results are not concatenated.

  • actions.ngrok.restrict_ips.actionstring

    The action taken for this request.

    • Possible values
    • allow - If the request was permitted.
    • deny - If the request was denied.
  • actions.ngrok.restrict_ips.matched_cidrstring

    The CIDR block that matched the incoming client's IP address. If no match was found, this value will be empty.

  • actions.ngrok.restrict_ips.error.codestring

    A machine-readable code describing an error that occurred during the action's execution.

  • actions.ngrok.restrict_ips.error.messagestring

    A human-readable message providing details about an error that occurred during the action's execution.