jarylc/simple-nginx-otp

By jarylc

Updated almost 2 years ago

A simple Nginx OTP module for use with auth_request

Image
Security
Web Servers
Developer Tools

6.1K

Simple Nginx OTP

A simple Nginx OTP module for use with auth_request

Explore the docs »

Report Bugs · Request Features

About

Features
  • Lightweight and fast
  • Returns a very simple form with a text field and submit button for OTP entry
  • Basic TOTP support
  • YubiOTP support
  • Rate limiting support
Environment Variables
EnvironmentDefault valueDescription
SNO_LISTEN_IP0.0.0.0IP which SNO will listen at
SNO_LISTEN_PORT7079Port which SNO will listen at
SNO_SECRETOTP secret key. Enables TOTP functionality if not empty. If both this and SNO_YUBIOTP are empty, application will reply a random one for use and exit
SNO_YUBIOTPOne example of your YubiOTP. Enables YubiOTP functionality if not empty. Only the first 12 characters are used
SNO_TITLESimple Nginx OTPPage title on OTP entry page
SNO_COOKIE_NAMEsno_sessionSession cookie name
SNO_COOKIE_LENGTH16Session cookie length (recommended >=16)
SNO_COOKIE_LIFETIME14Session cookie lifetime in days
SNO_COOKIE_DOMAINSession cookie domain. If empty, default to current domain
SNO_RATE_LIMIT_COUNT3How many failures till rate limit kicks in
SNO_RATE_LIMIT_LIFETIME1Rate limit lifetime in minutes
Built With

Getting Started

To get a local copy up and running follow these simple steps.

Make sure to only allow nginx to access the application!

Please change/ SNO_SECRET and SNO_YUBIOTP accordingly as they are examples, run without both to generate a random SNO_SECRET for use.

1a. Docker Run
docker run -d \
  --name simple-nginx-otp \
  -e SNO_LISTEN_IP=0.0.0.0 \
  -e SNO_LISTEN_PORT=7079 \
  -e SNO_SECRET=JBSWY3DPEHPK3PXP \
  -e SNO_YUBIOTP=vvvvvvcurikvhjcvnlnbecbkubjvuittbifhndhn \
  -e SNO_TITLE="Simple Nginx OTP" \
  -e SNO_COOKIE_NAME=sno_session \
  -e SNO_COOKIE_LENGTH=16 \
  -e SNO_COOKIE_LIFETIME=14 \
  -e SNO_COOKIE_DOMAIN="" \
  -e SNO_RATE_LIMIT_COUNT=3 \
  -e SNO_RATE_LIMIT_LIFETIME=1 \
  -p 7079:7079 \
  --restart unless-stopped \
  jarylc/simple-nginx-otp
1b. Docker-compose

Please change/remove SNO_SECRET and SNO_YUBIOTP accordingly as they are examples, run without both to generate a random SNO_SECRET for use.

simple-nginx-otp:
    image: jarylc/simple-nginx-otp
    user: nobody
    ports:
        - "7079:7079"
    environment:
        - UID=0
        - GID=0
        - SNO_LISTEN_IP=0.0.0.0
        - SNO_LISTEN_PORT=7079
        - SNO_SECRET=JBSWY3DPEHPK3PXP
        - SNO_YUBIOTP=vvvvvvcurikvhjcvnlnbecbkubjvuittbifhndhn
        - SNO_TITLE="Simple Nginx OTP"
        - SNO_COOKIE_NAME=sno_session
        - SNO_COOKIE_LENGTH=16
        - SNO_COOKIE_LIFETIME=14
        - SNO_COOKIE_DOMAIN=""
        - SNO_RATE_LIMIT_COUNT=3
        - SNO_RATE_LIMIT_LIFETIME=1
    restart: unless-stopped
2. Nginx

Inside the server block:

error_page 401 = @error401;
location @error401 {
    return 302 /sno;
}
location /sno {
    error_page 401 /;
    proxy_pass http://127.0.0.1:7079;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $scheme://$http_host$request_uri;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
location / {
    auth_request /sno;
    proxy_pass http://endpoint;
}

Development

Building
cd /path/to/project/folder
go build -ldflags="-w -s"
Docker build
cd /path/to/project/folder
docker build .

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Feel free to fork the repository and submit pull requests.

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Jaryl Chng - git@jarylchng.com

https://jarylchng.com

Project Link: https://gitlab.com/jarylc/simple-nginx-otp/

Docker Pull Command

docker pull jarylc/simple-nginx-otp