OTPdoor

OTPdoor is a premium, lightweight Python library for creating and managing TOTP (One-Time Password) authentication, specifically designed to be used as an auth_request backend for Nginx.

It provides a modern, glassmorphic UI for user login and a dedicated configuration portal for initial setup and device provisioning.

Features

• Multi-Domain Support: Protect multiple independent applications with a single OTPdoor instance, each with its own secret and settings.
• TOTP Authentication: Industry-standard Time-based One-Time Passwords (RFC 6238).
• Premium UI: Modern, glassmorphic design with support for Light and Dark modes.
• Runtime Configuration: Update session durations and TOTP secrets on the fly via the /_config endpoint.
• Flexible Sessions: Configure session duration in seconds, minutes, or hours.
• Security First:
  • Secure, encrypted session cookies using Fernet (AES-128).
  • Restricted configuration mode with explicit CLI activation and warnings.
  • Safety confirmation dialogs for critical actions.
• Production Ready: Powered by Waitress, a stable production-grade WSGI server.
• Easy Provisioning: Built-in QR code generation for quick configuration with apps like Google Authenticator or Authy.

Installation

Install OTPdoor using pip:

pip install otpdoor

Quick Start

1. Installation

pip install otpdoor

2. Launch

export OTPDOOR_COOKIE_SECRET="your-secure-key"
python -m otpdoor -c

3. Setup via Browser

1. Navigate to http://localhost:8080/_config.

[!CAUTION] SECURITY REQUIREMENT: Log in with the default secret BASE32SECRET3232 and Immediately generate a new secret for the default domain. Never leave the default secret active after initial setup.

• Scan this QR for quick access:
  

4. Use the "Create New Domain" section to add other applications.

[!IMPORTANT] Access to the configuration portal now requires a valid authentication session for the default domain.

Multi-Domain Support

OTPdoor allows you to manage multiple independent authentication domains. Each domain has its own secret, session duration, and theme. Configurations are encrypted and persisted in otpdoor_config.json.

Managing Domains

• Add a domain: python -m otpdoor --add-domain myapp
• List domains: python -m otpdoor --list-domains

Using Domains in URLs

Access routes for a specific domain by adding the domain parameter:

• http://127.0.0.1:8080/_auth?domain=myapp
• http://127.0.0.1:8080/_check?domain=myapp
• http://127.0.0.1:8080/_config?domain=myapp

If no domain is provided, it defaults to default.

5. Nginx Configuration (Multi-Domain)

To protect a specific app (myapp), pass the domain parameter in the proxy requests:

geo $otpdoor_lan_bypass {
    default  "";
    127.0.0.1/32 true;
    10.0.0.0/8 true;
    172.16.0.0/12 true;
    192.168.0.0/16 true;
}

upstream otpdoor_backend {
    server 127.0.0.1:8080;
}

server {
    listen 80;
    server_name myapp.example.com;

    location / {
        # Pass the domain to the check endpoint
        auth_request /_check;
        error_page 401 = @error401;
        proxy_pass http://your_app_backend;
    }

    location = /_check {
        internal;
        # Optional: let LAN clients skip OTP when matched by the geo block.
        proxy_set_header X-OTPdoor-LAN-Bypass $otpdoor_lan_bypass;
        # Pass domain=myapp to use the correct secret
        proxy_pass http://otpdoor_backend/_check?domain=myapp;
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
    }

    location /_auth {
        # Pass domain=myapp so the login page uses the correct configuration
        proxy_pass http://otpdoor_backend/_auth?domain=myapp;
        proxy_set_header Host $host;
    }

    location @error401 {
        # Redirect to the domain-specific auth page
        return 302 $scheme://$http_host/_auth?domain=myapp&originator=$request_uri;
    }
}

Configuration Reference

• OTPDOOR_TOTP_SECRET: Shared secret for the default domain.
• OTPDOOR_COOKIE_SECRET: Key used to encrypt session cookies.
• OTPDOOR_CONFIG_FILE: Path to the JSON configuration file (default: otpdoor_config.json).
• OTPDOOR_SESSION_DURATION: Default session duration in seconds.
• OTPDOOR_THEME: Default theme (dark or light).
• OTPDOOR_ALLOWED_DOMAINS: Allowed domains for redirects.
• OTPDOOR_COOKIE_SECURE: Set to true to enable HTTPS-only cookies (default: false).
• OTPDOOR_LAN_BYPASS_HEADER: Header OTPdoor checks for an Nginx-approved LAN bypass (default: X-OTPdoor-LAN-Bypass).
• OTPDOOR_LAN_BYPASS_VALUE: Exact header value required to bypass OTP on /_check (default: true).

Persistence & Updates 🔄

OTPdoor is designed to keep your data safe during version upgrades. The otpdoor_config.json file resides in your working directory, entirely separate from the package code.

Steps for a safe update:

1. Run python -m otpdoor --show-config and note the path.
2. Back up that file.
3. Install the new version (pip install --upgrade otpdoor or similar).
4. Restart the server. Your configuration will be automatically detected and reloaded.

License

MIT License - see the LICENSE file for details.

Contact

[germanespinosa@gmail.com]

Package created with Easy-pack