www_authenticate

The WWW Authenticate module is a highly flexible security suite for Drupal 10 and 11, designed to provide a robust HTTP-level authentication gate. It acts as a dynamic, database-driven alternative to static server-level .htpasswd files, allowing for seamless integration with Drupal's internal permissions, path systems, and network rules. Whether you need to shield a staging site or protect specific sensitive routes, this module provides granular control without touching server configurations.

Key Features

• Multi-Credential Support: Manage multiple username and password pairs independently of Drupal’s core user table for different stakeholders, clients, or automated services.
• Granular Path Scoping: Protect the entire site (Exclude mode) or target specific sensitive routes (Include mode) using Drupal's native path matcher.
• Advanced IP Filtering: Integrated allowlist and denylist logic supporting exact IPs, CIDR ranges (e.g., 192.168.1.0/24), and wildcards (e.g., 10.0.*).
• Temporal Restrictions: Automatically enable or disable authentication based on business hours, specific days of the week, and configurable timezones.
• Identity-Based Bypass: Allow logged-in Drupal users with specific roles to skip the HTTP Basic Auth prompt entirely, streamlining the workflow for authenticated team members.
• Admin Lockout Protection: Hardcoded exclusions for configuration and log paths ensure administrators can always access the settings even if rules are misconfigured.

Installation

Install the module via Composer to ensure core dependencies and database schema definitions are correctly mapped:

composer require drupal/www_authenticate

Enable the module using Drush:

drush en www_authenticate -y

Configuration & Permissions

After installation, follow these steps to secure your site:

1. Navigate to People » Permissions.
2. Grant "Administer WWW Authenticate" to manage credentials and access rules.
3. Grant "Access WWW Authenticate Logs" to users who need to monitor authentication history.
4. Go to Configuration » System » WWW Authenticate (/admin/config/system/www-authenticate) to define your security rules.

Architecture & Logic

The module operates as a high-priority middleware layer within the Drupal kernel to ensure maximum security with minimal overhead:

• Middleware Layer: Hooks into KernelEvents::REQUEST at the earliest stage to intercept requests before the routing system fully resolves.
• WwwAuthenticate Service: A centralized logic handler that performs real-time IP matching, CIDR calculations, and path validation.
• Smart Bypasses: Includes built-in toggles to allow Drush, Cron, and JSON:API/REST requests to function without manual authentication headers.
• Pruning Engine: Automatically maintains database health by trimming logs based on user-defined entry limits to prevent table bloat.

Troubleshooting

If you encounter issues during setup, consider the following:

• Emergency Access: If you accidentally lock yourself out, use the Drush command drush www-authenticate:disable to immediately drop the shield.
• IP Precedence: If an IP address exists in both the Allowlist and Denylist, the Allowlist takes precedence.
• Path Matching: Ensure you are using internal Drupal paths. The module automatically normalizes patterns like node/ and /node/ for consistency.

Similar projects

• Shield (Provides a site-wide Apache-style authentication shield, commonly used for staging environments)
• Restrict Login or Role Access by IP Address (Restricts site or role access based on specific IP ranges)
• HTTP Basic Authentication (Core Drupal module that authenticates users against their Drupal account credentials via headers)

Supporting this Module

If you find this module helpful or have suggestions for new features, please contribute to the issue queue. Your feedback helps keep this tool robust for the community!