otpdoor 0.0.12

OTPdoor is a Python library for creating and managing OTP (One-Time Password) authentication with nginx.

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:

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;
        # 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 false for local HTTP testing.

License

MIT License - see the LICENSE file for details.

Contact

[[e-mail]]

---

Package created with Easy-pack