Documentation

Recent changes

IP Filtering

The IP filtering plugin allows you to restrict the traffic to your API gateway based on the IP address. It works in two different modes (allow or deny) where you define the list of IPs (CIDR blocks) that are authorized to use the API, or that are denied from using the API.

The filtering applies globally to all endpoints, or to only specific endpoints depending on the placement of the configuration.

The basic configuration looks like this:

{
    "ip-filter": {
        "CIDR": [
            "192.168.0.0/24",
            "172.17.2.56/32",
            "10.0.0.0/16",
            "127.0.0.1"
        ],
        "allow": true
    }
}

The supported options of the plugin are:

  • CIDR list: The CIDR blocks (list of IPs) you want to allow or deny.
  • client_ip_headers list (optional): A custom list of all headers that might contain the real IP of the client. The first matching IP in the list will be used. Default headers are (in order of checking): X-Forwarded-For, X-Real-IP, and X-Appengine-Remote-Addr.
  • trusted_proxies list (optional): A custom list of all the recognized machines/balancers that proxy the client to your application. This list is used to avoid spoofing when trying to get the real IP of the client.
  • allow bool: IP filtering mode. Defaults to false (deny mode).
    • true: Allow mode. Only the matching IPs are able to access the content.
    • false: Deny mode. All matching IPs are discarded.
    • In the rare case that the machine is unable to parse the given IP (couldn’t be parsed as an IPv4 or IPv6), in deny mode the request will pass, but the allow won’t.

Filter IPs globally

The following configuration is used when you want to enable a common set of IP filtering rules for any request to the gateway. All endpoints will enable IP based access with this configuration:

{
    "version": 3,
    "plugin": {
        "pattern":".so",
        "folder": "/opt/krakend/plugins/"
    },
      "extra_config": {
          "plugin/http-server": {
            "name": ["ip-filter", "some-other-plugin-here" ],
            "ip-filter":
            {
                "allow": true,
                "CIDR": [
                    "192.168.0.0/24",
                    "172.17.2.56/32",
                    "10.0.0.0/16",
                    "127.0.0.1"
                ]
            }
        }
    }
}

When the plugin is loaded as a plugin/http-server the configuration affects all endpoints.

Filter IPs by endpoint

To filter IPs on specific endpoints, or to write additional rules to the global IP configuration (having a second check), then you have to place the configuration inside the endpoint’s extra_config.

Custom location of the IP address
When filtering endpoints, the IP address is taken from the X-Forwarded-For header which is automatically calculated by KrakenD. If this header couldn’t retrieve the client IP, you might want to set both client_ip_headers in the plugin configuration, and input_headers in the endpoint configuration with the custom headers you need.

The following configuration is used to filter access to specific endpoints:

{
    "version": 3,
    "plugin": {
        "pattern":".so",
        "folder": "/opt/krakend/plugins/"
    },
    "endpoints": [
    {
        "endpoint": "/filtered-endpoint",
        "extra_config": {
            "plugin/req-resp-modifier": {
                "name": ["ip-filter" ],
                "ip-filter":
                {
                    "allow": true,
                    "CIDR": [
                        "192.168.0.0/24",
                        "172.17.2.56/32",
                        "10.0.0.0/16",
                        "127.0.0.1"
                    ]
                }
            }
        }
    }]
}

When the plugin is loaded as a plugin/req-resp-modifier the configuration affects that specific endpoint only.

Filtered IPs logging

Whenever a request is denied by the IP filter plugin, the attempt is logged using an INFO level. Example:

IP filtering log 
$▶ INFO [PLUGIN: ip-filter] blocking access to endpoint /foo from IP 1.2.3.4 

If you want to see these logs in production make sure to enable logging with the INFO level.

Advanced calculation of IPs

There will be times when your PaaS provides the real IP in a specific custom header, or when you need to add a trusted proxy.

Here is an example of the configuration (set your custom values):

{
    "ip-filter": {
        "CIDR": [
            "192.168.0.0/24",
            "172.17.2.56/32",
            "10.0.0.0/16",
            "127.0.0.1"
        ],
        "client_ip_headers": [
            "X-User-IP",
            "X-MyCompany-Client-IP"
        ],
        "trusted_proxies": [
            "10.0.0.0/16"
        ],
        "allow": true
    }
}

Unresolved issues?

The documentation is only a piece of the help you can get! Whether you are looking for Open Source or Enterprise support, see more support channels that can help you.

We use cookies to understand how you use our site and to improve your overall experience. By continuing to use our site, you accept our Privacy Policy. More information