bhammack / traefik-geoip-forwardauth

A very simple ForwardAuth middleware container for Traefik to allow only specific locations (GeoIP)

Simple GeoIP ForwardAuth for Traefik

Return HTTP 200 if the IP is allowed to access services, HTTP 403 otherwise.

Preparation

You will need the GeoLite2-City.mmdb database from MaxMind.

This database can be obtained free of charge from MaxMind by making an account on https://dev.maxmind.com/geoip/geolite2-free-geolocation-data?lang=en.

The container expects the database available on /db/GeoLite2-City.mmdb.

Alternatively, you can create a license key and have the container automatically download the database for you if it isn't found (see configuration).

Configuration

Environment variables

Environment variable	Description
SIMPLE_GEOIP_FORWARDAUTH_MAXMIND_LICENSE_KEY	A MaxMind license key to automatically download and update the GeoIP database (optional)

URL generation

This container will look at the request URL to calculate if a request is allowed or not.

locations

locations is a semi-colon separated list of countries. Each country can contain a comma-separated list of areas.

For example, to allow the whole of the Netherlands:

NL

To allow only the top 3 most LGBT-friendly US states (Nevada, Vermont and New York):

US:NV,VT,NY

To allow all of the Netherlands and the above-named US states:

NL;US:NV,VT,NY

Sometimes, the MaxMind GeoIP database may not have area info. You can whitelist an unknown area using UNK as area.

ips

IPs is a comma-separated list of IPs or networks allowed. For example, to allow both 127.0.0.1 and 192.168.0.0/16 simply use:

127.0.0.1,192.168.0.0/16

If an IP is put on the allowlist, it is allowed regardless of the location. This is the only way to whitelist IPs not in the GeoIP database.

Setup

Note: in the setup steps, I will use the locations and ip example explained above

Start the container into a bridge network called geoipforwardauth, giving it the hostname geoip. Then, make sure your Traefik container is also in that network.

On the SimpleGeoIPForwardAuth container, add a label with URLencoded parameters stating the allowed sources:

labels:
- traefik.enable=true
- traefik.http.middlewares.simple-geoip.forwardauth.address=http://geoip:8000/?locations=NL;US:NV,VT,NY&ips=127.0.0.1,192.168.0.0/16

Now, add this newly made simple-geoip middleware to the desired container labels:

labels:
- traefik.http.routers.my_route.middlewares=simple-geoip@docker