plug_ip_whitelist v1.2.0 API Reference
Modules
Parent module for the IpWhitelisting plug
IP Whitelists often need to be stored as an environment variable. This module provides functionality for parsing a list of IP ranges out of a string which could be stored in your application’s environment variables. Example:
"1.1.1.1-1.1.1.1 2.3.4.5-6.7.8.9"
This Plug is for use on applications running on Heroku. It injects the ip
address of the request into the the remote_ip attribute on the Plug.
It should be included in the Plug pipeline before the IpWhitelistEnforcer
.
We can get the originating request IP from the X-Forwarded-For header, which
usually contains a single ip address ie:
X-Forwarded-For: <the real request ip>
It will contain list of ip addresses if something besides the heroku router modified the X-Forwarded-For header earlier in the request chain. An example of when this would happen is if an attacker were trying to spoof the IP address. The heroku router handles this by including a comma-seperated list of ip addresses in the X-Forwarded-For header, where the last ip address in the list is the originating request IP, ie:
X-Forwarded-For: <spoofed request ip>, <real request ip>
So, we make the assumption that the heroku router isn’t compromised and that nothing between the heroku router and our application has been compromised. Given that assumption, we can trust that the last ip address in the list is the actual originating request IP, which we want to compare against our whitelist See also: https://devcenter.heroku.com/articles/http-routing#heroku-headers
Only allow requests from the range of IP addresses specified in the
application config. Assumes the request ip is present in the remote_ip
attribute on the passed in plug.
If the request IP is not whitelisted, the specified response code and body
will be added to the Plug.Conn and it will be halted.
If the request IP is on the whitelist, the plug chain will continue Include this module in your plug chain with required options Options:
ip_whitelist (required): A list of ip range tuples
Example:
```
[
{{1, 1, 1, 1}, {1, 1, 1, 2}},
{{1, 2, 3, 4}, {5, 6, 7, 8}}
]
```
This designates the ranges of IP addresses which are whitelisted
response_code_when_blacklisted: The HTTP status code assigned to the
response when the request's IP address is not in the whitelist. Defaults
to `401` if not specified
response_body_when_blacklisted: The body assigned to the response when the
request's IP address is not in the whitelist. Defaults to
`"Not Authenticated"` if not specified
Example:
```
# Include after a plug which adds the request IP to the remote_ip
# attribute on the Plug.Conn
plug Plug.IpWhitelist.IpWhitelistEnforcer, [
ip_whitelist: [
{{1, 1, 1, 1}, {1, 1, 1, 2}},
{{1, 2, 3, 4}, {5, 6, 7, 8}}
]
]
```