Skip to main content

Restrict IPs

Overview​

The Restrict IPs Traffic Policy action enables you to allow or deny traffic based on the source IP of the connection that was initiated to your ngrok endpoints.

You can define rules in two ways, with allow and deny lists or with identifiers to existing ngrok IP Policies.

Configuration Reference​

This is the Traffic Policy configuration reference for this action.

Action Type​

restrict-ips

Configuration Fields​

ParameterTypeDescription
enforceboolDefault true. If false, continue to the next action even if the IP is not permitted.
allow[]stringA list of of CIDRs that are allowed.
deny[]stringA list of of CIDRs that are denied.
ip_policies[]refList of IP Policy identifiers to be checked if the source IP is allowed access.

Supported Phases​

  • on_http_request
  • on_http_response
  • on_tcp_connect

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:

  • An HTTP 403 response is returned.
  • 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_http_request:
  - 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, you will receive an HTTP 403 response:

$ curl -i https://example.ngrok.app
HTTP/2 403

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_http_request:
  - 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, you will receive an HTTP 403 response:

$ curl -i https://example.ngrok.app
HTTP/2 403

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_http_request:
  - 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 -i https://example.ngrok.app
HTTP/2 200

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.

NameTypeDescription
actions.ngrok.restrict_ips.actionstringThe resulting action for this action execution. Supported values are either allow or deny.
actions.ngrok.restrict_ips.matched_cidrstringThe CIDR that matched for the incoming client ip. This may be empty.
actions.ngrok.restrict_ips.error.codestringCode for an error that occurred during the invocation of an action.
actions.ngrok.restrict_ips.error.messagestringMessage for an error that occurred during the invocation of an action.