Restrict IPs Action

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.

Need to allow or block traffic from a specific service (like GitHub, AWS, or OpenAI) without managing hundreds of CIDRs by hand? Use IP Categories with a Traffic Policy expression instead. ngrok maintains up-to-date IP ranges for dozens of services and threat categories, so you can write rules like 'com.github' in conn.client_ip.categories or 'proxy.anonymous.tor' in conn.client_ip.categories. See Filter Traffic by IP Category for examples.

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

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 doesn’t 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 run.

IPv6 support

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

Include both the IPv4 and IPv6 ranges for every client you want to allow. ngrok endpoints accept connections over both protocols, and most browsers and operating systems use Happy Eyeballs to pick whichever one connects first. The same client can arrive from its IPv4 address on one request and its IPv6 address on the next. If you allow only one, requests from that client fail intermittently with a 403 or a closed connection.

To find both addresses for a network, visit a site such as https://test-ipv6.com from that network, or run curl -4 https://ifconfig.co and curl -6 https://ifconfig.co. Then add a CIDR for each:

on_http_request:
  - actions:
      - type: restrict-ips
        config:
          enforce: true
          allow:
            - 203.0.113.0/24
            - 2001:db8:1234::/48

Non-terminating action

This is a Non-terminating action. It does not return a response, and will allow Traffic Policy processing to continue to the next Action in the chain. All Cloud Endpoint Traffic Policies must end with a terminating action. This requirement does not apply to Agent Endpoints.

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

on_tcp_connect:
  - actions:
      - type: restrict-ips
        config:
          enforce: true
          allow:
            - 1.1.1.1/32
          deny:
            - 110.0.0.0/8

{
  "on_tcp_connect": [
    {
      "actions": [
        {
          "type": "restrict-ips",
          "config": {
            "enforce": true,
            "allow": [
              "1.1.1.1/32"
            ],
            "deny": [
              "110.0.0.0/8"
            ]
          }
        }
      ]
    }
  ]
}

This configuration will ensure that only requests from the IP 1.1.1.1 are allowed, while requests from the IP 110.0.0.0 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

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

{
  "on_tcp_connect": [
    {
      "actions": [
        {
          "type": "restrict-ips",
          "config": {
            "enforce": true,
            "ip_policies": [
              "ipp_1yjqdrIBwgciY2I9zH2EelgBbJF"
            ]
          }
        }
      ]
    }
  ]
}

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

Example request

If the request comes from an allowed IP, the response proceeds as normal. If the request comes from a denied IP, you receive an HTTP 403 response:

$ telnet 5.tcp.ngrok.io 22984

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

snippets/traffic-policy/actions/restrict-ips/tcp/examples/3-testing-traffic

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

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

{
  "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 ensures 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 proceeds as normal. If the request comes from a denied IP, you 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

{
  "on_http_request": [
    {
      "actions": [
        {
          "type": "restrict-ips",
          "config": {
            "enforce": true,
            "ip_policies": [
              "ipp_1yjqdrIBwgciY2I9zH2EelgBbJF"
            ]
          }
        }
      ]
    }
  ]
}

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

Example request

If the request comes from an allowed IP, the response proceeds as normal. If the request comes from a denied IP, you 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}

{
  "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 tests the incoming client IP against the specified IP Policy ipp_1yjqdrIBwgciY2I9zH2EelgBbJF without enforcing it, then logs the result using the log action.

Example request

ngrok allows the following request and logs an event:

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

Getting Started

Use Cases

Examples

Connectivity

Traffic Policy

Observability

Network

Resources

Identity & Access

Configuration reference

Supported phases

Type

Configuration fields

Behavior

Evaluation of rules

Allow and deny conditions

Building CIDR sets

Denied connection handling

IPv6 support

Non-terminating action

Examples `on_tcp_connect`

Restricting access with allow and deny lists

Example Traffic Policy document

Example request

Restricting access with IP Policies

Example Traffic Policy document

Example request

Examples `on_http_request`

Restricting access with allow and deny lists

Example Traffic Policy document

Example request

Restricting access with IP Policies

Example Traffic Policy document

Example request

Test restricting IPs

Example Traffic Policy document

Example request

Action result variables

​Configuration reference

​Supported phases

​Type

​Configuration fields

​Behavior

​Evaluation of rules

​Allow and deny conditions

​Building CIDR sets

​Denied connection handling

​IPv6 support

​Non-terminating action

​Examples on_tcp_connect

​Restricting access with allow and deny lists

​Example Traffic Policy document

​Example request

​Restricting access with IP Policies

​Example Traffic Policy document

​Example request

​Examples on_http_request

​Restricting access with allow and deny lists

​Example Traffic Policy document

​Example request

​Restricting access with IP Policies

​Example Traffic Policy document

​Example request

​Test restricting IPs

​Example Traffic Policy document

​Example request

​Action result variables

Configuration reference

Supported phases

Type

Configuration fields

Behavior

Evaluation of rules

Allow and deny conditions

Building CIDR sets

Denied connection handling

IPv6 support

Non-terminating action

Examples `on_tcp_connect`

Restricting access with allow and deny lists

Example Traffic Policy document

Example request

Restricting access with IP Policies

Example Traffic Policy document

Example request

Examples `on_http_request`

Restricting access with allow and deny lists

Example Traffic Policy document

Example request

Restricting access with IP Policies

Example Traffic Policy document

Example request

Test restricting IPs

Example Traffic Policy document

Example request

Action result variables