Configuration¶
Setting up the app¶
Add iprestrict
to INSTALLED_APPS
in your settings file:
INSTALLED_APPS = (
...
'iprestrict',
)
Run the migrations for the iprestrict
application:
$ ./manage.py migrate iprestrict
Enable Django Admin for at least the iprestrict application.
Add the urls of iprestrict to your project. Ex in your root urls.py:
from django.conf.urls import url, include
urlpatterns = [
# ... snip ...
url(r'^iprestrict/', include('iprestrict.urls', namespace='iprestrict')),
This configuration will allow you to configure and test your restriction rules.
Configuring the restriction rules¶
Go to your admin page and open IPRestrict Rules to get a list of your current rules.
The rules consist of:
- a URL pattern - this is regex that will be matched against the URL requested by the client. The value
"ALL"
is special and it will always match (a tad nicer than.*
) - Reverse ip group - reverses the IP Group. Ex. “Australian IPs” will match all IPs from Australia. However if Reverse ip group is set it will match all IPs that aren’t in Australia.
- an IP Group - a named group of IP addresses. Examples would be “localnet”, “Trusted net”, “Sam’s Home IP” etc. or the provided “ALL” and “localhost”
- an Action (labeled “Is allowed?”) - what to do if both the client url and the ip match the URL Pattern and the IP Group. Possible values are
"ALLOW"
and"DENY"
to allow or deny the request.
The rules are checked in the order you see them from top to bottom. The url the client requested is matched against the URL Pattern and the client IP address is checked if it is in the IP Group. If both the URL and IP address of a rule match the processing of the rules stops, and the request will be denied or allowed based on the rule’s Action.
If no rules match the request the request will just fall through (ie. it will be allowed).
As you can see after installation 2 rules are provided by default.
- The first one allows all request from localhost
- The second denies all requests
This is a deny by default strategy, when you will have to create rules for all the IP addresses that can access the application explicitly.
To allow everything by default and specify the IP addresses you would like to deny access simply delete the ALL, ALL, DENY rule.
The order of the rules can be changed by clicking the “Move Up” and “Move Down” links.
Example config:
/admin/.* localnet ALLOW
/admin/.* ALL DENY
These rules would restrict access to admin only from localnet, but allow access to the rest of the application.
Example config 2:
ALL "Fishy IPs" DENY
ALL "Trusted Nets" ALLOW
ALL ALL DENY
App can be used only from “Trusted Nets”, but even inside the Trusted Nets there are some IPs you would like to Deny access to (defined in “Fishy IPs”).
Example config 3:
ALL "localnet" ALLOW
ALL "Fishy IPs" DENY
ALL "Australian IPs" "Reverse ip group" DENY
ALL ALL ALLOW
Allow full access from localnet, deny some “Fishy IPs”, deny access from IPs that are NOT from Australia, then allow access for everyone else. The last 2 rules combined is a way to allow access only to IPs from Australia.
Sooner or later you will probably have to define some IP Groups (ex. like Trusted Nets above).
There are 2 types of IP Groups. The first type allows you to define specific IP addresses or ranges/subnets of IP addresses. The second type allows you to define rules based on the IP’s country of origin.
Both IP Groups have a name and an optional longer description.
Range based IP Groups¶
The range based IP Groups are defined by a a list of IP Ranges.
IP Ranges can be:
- a single IP address (complete just the First ip field)
- a subnet (complete the First ip field and the CIDR prefix length)
- a range of ip addressess (complete the First ip and the Last ip in the range and leave the Cidr prefix length empty)
Ex.
Value | First ip | Cidr prefix length | Last ip |
---|---|---|---|
single ip 192.168.1.1 | 192.168.1.1 | ||
subnet 192.168.1.1/24 | 192.168.1.1 | 24 | |
ip range 192.168.1.1 - 192.168.1.10 | 192.168.1.1 | 192.168.1.10 |
Location based IP Groups¶
The usage of location based IP Group is optional.
It is possible to opt out of using them by setting IPRESTRICT_GEOIP_ENABLED
to False
in your settings.py
in which case you don’t have to install the dependencies needed by geoip
.
The location based IP Groups are defined by a list of 2 digit country codes. You can add one or more country codes to the group. If you have more than one country code, the group will match the IP address if its country matches any of the country codes in the group.
Ex.
Value | Country codes |
---|---|
All IPs from Australia | AU |
All IPs from Australia and New Zealand | AU, NZ |
Testing the rules¶
When you are happy with the rules you set up, you might want to test them.
Go to YOUR_URL/iprestrict/ page. You can use the page to enter any URL and IP Address and Test them against the rules in your database.
Enabling the middleware¶
Add iprestrict.middleware.IPRestrictMiddleware
to your MIDDLEWARE
in your settings file (or MIDDLEWARE_CLASSES
for old versions of Django). Generally, you will want this middleware to run early, before your session, auth etc. middlewares (the superuser_required
decorator may also not function correctly if placed out of order):
MIDDLEWARE_CLASSES = (
'django.middleware.common.CommonMiddleware',
'iprestrict.middleware.IPRestrictMiddleware',
...
)
Your Django project is now restricted based on the rules defined.
Settings¶
Django IP Restrict has settings to adapt to the environment in which your app is hosted in.
IPRESTRICT_GEOIP_ENABLED¶
Default: True
Set to False
if you don’t require restriction by location. In this case the dependencies needed by location based IP Groups, don’t have to be installed.
IPRESTRICT_RELOAD_RULES¶
Default: True
When set to False
rules will be reloaded only after restarting the
server. See Rules are cached.
IPRESTRICT_IGNORE_PROXY_HEADER¶
Default: False
When this setting is True
, Django IP Restrict will completely
disregard the X-Forwarded-For
HTTP header. Normally, the
middleware would block requests with a suspect value for
X-Forwarded-For
.
IPRESTRICT_TRUSTED_PROXIES¶
Default: []
(Empty List)
Use this setting when your app is hosted behind a reverse proxy. When
values are provided, they will be checked against the HTTP
X-Forwarded-For
header to determine the true client IP address.
IPRESTRICT_TRUST_ALL_PROXIES¶
Default: False
Use this setting when using a managed proxy with a dynamic IP (like when
behind an AWS Load Balancer, or other cloud equivalent). When this
setting is True
, Django IP Restrict will always check the HTTP
X-Forwarded-For
header to determine the true client IP address.