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:

• When used on the on_tcp_connect phase:
  • The connection is closed.
• When used on the on_http_request or on_http_response phase:
  • An HTTP 403 response is returned.
• The upstream server is never reached.
• No further rules or actions in the traffic policy 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 on_tcp_connect

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

YAML

---
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

JSON

{
  "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 will be closed:

$ telnet 5.tcp.ngrok.io 22984

Trying...
Connected to 5.tcp.ngrok.io.
Connection closed by foreign host.

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

YAML

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

JSON

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

$ telnet 5.tcp.ngrok.io 22984

Trying...
Connected to 5.tcp.ngrok.io.
Connection closed by foreign host.

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

YAML

---
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}

JSON

{
  "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:

$ telnet 5.tcp.ngrok.io 22984

Trying...
Connected to 5.tcp.ngrok.io.

Examples on_http_request

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

YAML

---
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

JSON

{
  "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

YAML

---
on_http_request:
  - actions:
      - type: restrict-ips
        config:
          enforce: true
          ip_policies:
            - ipp_1yjqdrIBwgciY2I9zH2EelgBbJF

JSON

{
  "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

YAML

---
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}

JSON

{
  "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.

• 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.