Plug.IpWhitelist

Installation

The package can be installed by adding plug_ip_whitelist to your list of dependencies in mix.exs:

def deps do
  [
    {:plug_ip_whitelist, "~> 1.0.0"}
  ]
end

Usage

Include Plug.IpWhitelist.IpWhitelistEnforcer somewhere in your Phoenix application's plug chain, with options. This usually means it goes somewhere in your Routes or Endpoint files, or in a Controller:

plug Plug.IpWhitelist.IpWhitelistEnforcer, [
  ip_whitelist: [
      {{1, 1, 1, 1}, {1, 1, 1, 2}},
      {{1, 2, 3, 4}, {5, 6, 7, 8}}
  ],
  response_code_when_blacklisted: 401,
  response_body_when_blacklisted: "Not Authenticated"
]

IMPORTANT: Set IP Address via remote_ip

Phoenix/Plug.Conn do not provide out of the box support for request ip address. IpWhitelistEnforcer assumes that something further up the plug chain has already set the remote_ip attribute on the connection to be the request ip address. If your application runs on Heroku, see the section on Usage with Heroku for the built-in functionality provided

Usage outside of a Plug

Sometimes you just want a boolean indicating whether or not an IP address is on the whitelist.

ip_whitelist = [
    {{1, 1, 1, 1}, {1, 1, 1, 2}},
    {{1, 2, 3, 4}, {5, 6, 7, 8}}
]

# You can pass in a Plug.Conn to see if it's remote ip is whitelisted:
Plug.IpWhitelist.IpWhitelistEnforcer.is_whitelisted?(some_conn, ip_whitelist)
# => true/false

# Or you can pass in an IP address directly:
Plug.IpWhitelist.IpWhitelistEnforcer.is_whitelisted?({1, 1, 1, 1}, ip_whitelist)
# => true

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

Usage with Heroku

If your application runs on Heroku, the request ip can be retrieved from the X-Forwarded-For header (this header is set by the Heroku router). The Plug.IpWhitelist.HerokuRemotIp plug handles retrieving the request ip from the X-Forwarded-For header and storing it in the remote_ip attribute on the connection.

To use this module, include it in your plug chain anywhere before the IpWhitelistEnforcer plug:

plug Plug.IpWhitelist.HerokuRemoteIp
plug Plug.IpWhitelist.IpWhitelistEnforcer, [...options...]

For more info see the module documentation https://hexdocs.pm/plug_ip_whitelist/Plug.IpWhitelist.HerokuRemoteIp

Documentation

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/plug_ip_whitelist.