Show HN: A dynamic key-value IP allowlist for Nginx

5 points

5 months ago

I am currently working on a larger project that needs a short-lived HTTP "auth" based on a separate, out-of-band authentication process. Since every allowed IP only needs to be allowed for a few minutes at a time on specific server names, I created this project to solve that. It should work with any Redis-compatible database. For the docker-compose example, I used valkey.

This is mostly useful if you have multiple domains that you want to control access to. If you want to allow 1.1.1.1 to mywebsite.com and securesite.com, and 2.2.2.2 to securesite.com and anothersite.org for certain TTLs, you just need to set hash keys in your Redis-compatible database of choice like:

1.1.1.1:

  - mywebsite.com: 1 (30 sec TTL)

  - securesite.com: 1 (15 sec TTL)

2.2.2.2:

  - securesite.com: 1 (3600 sec TTL)

  - anothersite.org: 1 (never expires)

Since you can use any Redis-compatible database as the backend, per-entry TTLs are encouraged.

An in-process cache can also be used, but is not enabled unless you pass --enable-l1-cache to kvauth. That makes successful auth_requests a lot faster since the program is not reaching out to the key/value database on every request.

I didn't do any hardcore profiling on this but did enable the chi logger middleware to see how long requests generally took:

kvauth-1 | 2025/12/30 21:32:28 "GET http://127.0.0.1:8888/kvauth HTTP/1.0" from 127.0.0.1:42038 - 401 0B in 300.462µs # disallowed request

nginx-1 | 192.168.65.1 - - [30/Dec/2025:21:32:28 +0000] "GET / HTTP/1.1" 401 179 "-" "curl/8.7.1"

kvauth-1 | 2025/12/30 21:32:37 "GET http://127.0.0.1:8888/kvauth HTTP/1.0" from 127.0.0.1:40160 - 401 0B in 226.189µs # disallowed request

nginx-1 | 192.168.65.1 - - [30/Dec/2025:21:32:37 +0000] "GET / HTTP/1.1" 401 179 "-" "curl/8.7.1"

# IP added to redis allowlist

kvauth-1 | 2025/12/30 21:34:02 "GET http://127.0.0.1:8888/kvauth HTTP/1.0" from 127.0.0.1:54032 - 200 0B in 290.648µs # allowed, but had to reach out to valkey

kvauth-1 | 2025/12/30 21:34:02 "GET http://127.0.0.1:8888/kvauth HTTP/1.0" from 127.0.0.1:54044 - 200 0B in 4.041µs

nginx-1 | 192.168.65.1 - - [30/Dec/2025:21:34:02 +0000] "GET / HTTP/1.1" 200 111 "-" "curl/8.7.1"

kvauth-1 | 2025/12/30 21:34:06 "GET http://127.0.0.1:8888/kvauth HTTP/1.0" from 127.0.0.1:51494 - 200 0B in 6.617µs # allowed, used cache

kvauth-1 | 2025/12/30 21:34:06 "GET http://127.0.0.1:8888/kvauth HTTP/1.0" from 127.0.0.1:51496 - 200 0B in 3.313µs

nginx-1 | 192.168.65.1 - - [30/Dec/2025:21:34:06 +0000] "GET / HTTP/1.1" 200 111 "-" "curl/8.7.1

IP allowlisting isn't true authentication, and any production implementation of this project should use it as just a piece of the auth flow. This was made to solve the very specific problem of a dynamic IP allow list for NGINX.