Skip to content

js-challenge: NGINX Javascript challenge module

Debian/Ubuntu installation

These docs apply to the APT package nginx-module-js-challenge provided by the GetPageSpeed Extras repository.

  1. Configure the APT repository as described in APT repository setup.
  2. Install the module:
sudo apt-get update
sudo apt-get install nginx-module-js-challenge
Show suites and architectures 
| Distro   | Suite             | Component   | Architectures   |
|----------|-------------------|-------------|-----------------|
| debian   | bookworm          | main        | amd64, arm64    |
| debian   | bookworm-mainline | main        | amd64, arm64    |
| debian   | trixie            | main        | amd64, arm64    |
| debian   | trixie-mainline   | main        | amd64, arm64    |
| ubuntu   | focal             | main        | amd64, arm64    |
| ubuntu   | focal-mainline    | main        | amd64, arm64    |
| ubuntu   | jammy             | main        | amd64, arm64    |
| ubuntu   | jammy-mainline    | main        | amd64, arm64    |
| ubuntu   | noble             | main        | amd64, arm64    |
| ubuntu   | noble-mainline    | main        | amd64, arm64    |

ngx_http_js_challenge_module

GitHub CodeFactor

Demo website

Simple javascript proof-of-work based access for Nginx with virtually no overhead.

Easy installation: just add load_module /path/to/ngx_http_js_challenge_module.so; to your nginx.conf file and follow the configuration instructions.

Configuration

Simple configuration 

server {
    js_challenge on;
    js_challenge_secret "change me!";

    # ...
}

Advanced configuration 

server {
    js_challenge on;
    js_challenge_secret "change me!";
    js_challenge_html /path/to/body.html;
    js_challenge_bucket_duration 3600;
    js_challenge_title "Verifying your browser...";

    location /static {
        js_challenge off;
        alias /static_files/;
    }

    location /sensitive {
        js_challenge_bucket_duration 600;
        #...
    }

    #...
}

  • js_challenge on|off Toggle javascript challenges for this config block
  • js_challenge_secret "secret" Secret for generating the challenges. DEFAULT: "changeme"
  • js_challenge_html "/path/to/file.html" Path to html file to be inserted in the <body> tag of the interstitial page
  • js_challenge_title "title" Will be inserted in the <title> tag of the interstitial page. DEFAULT: "Verifying your browser..."
  • js_challenge_bucket_duration time Interval to prompt js challenge, in seconds. DEFAULT: 3600

Known limitations / TODO

  • Users with cookies disabled will be stuck in an infinite refresh loop (TODO: redirect with a known query param, if no cookie is specified but the query arg is set, display an error page)
  • If nginx is behind a reverse proxy/load balancer, the same challenge will be sent to different users and/or the response cookie will be invalidated when the user is re-routed to another server. (TODO: use the x-real-ip header when available)