aralez-basic-auth

aralez-basic-auth is an htpasswd-based HTTP Basic authentication plugin designed for the aralez reverse proxy.

It provides basic authentication by reading credentials from standard .htpasswd files, featuring real-time hot-reloading for file updates without requiring proxy restarts.

Features

• htpasswd File Support: Reads and parses standard username:hash formatted htpasswd files, automatically skipping comments and empty lines.
• bcrypt Password Verification: Validates passwords using bcrypt hashing. Automatically normalizes $2y$ hash prefixes to $2b$ for compatibility.
• Real-Time Hot-Reloading: Utilizes notify file watching to detect changes in the .htpasswd file asynchronously and update credentials in memory dynamically.
• Efficient Resource Management: Caches loaded credential data and watcher tasks using Weak references to prevent duplicate file watchers for the same file path.
• Plug & Play: Integrates seamlessly via the inventory plugin system under the plugin name "htpasswd".

Authentication Flow

1. Access Validation: The plugin checks the incoming request for an Authorization header using the Basic scheme.
2. Credential Extraction: Decodes the Base64 payload from the header to extract the username and password.
3. Password Verification: Looks up the user's password hash from memory and verifies the provided password using bcrypt.
4. Access Grant or Challenge: If verification succeeds, the request is proxied directly to the backend. If authentication fails or the header is missing, the plugin returns a 401 Unauthorized response with the WWW-Authenticate: Basic realm="Access Required" header.

Configuration

You can configure this plugin using your application's configuration file (compatible with noyalib / YAML structures) by specifying the htpasswd auth plugin type.

Configuration Items

Key	Type	Required	Description
type	String	Required	Must be set to "htpasswd" to select this plugin.
data	String	Required	The file path to the .htpasswd file (e.g., "/etc/aralez/.htpasswd").

Configuration Example (YAML)

upstreams.yaml

  authorization:
    type: "htpasswd"
    data: "/etc/aralez/.htpasswd"

License

Licensed under the Apache License, Version 2.0.