Skip to main content

73. Basic Authentication for Admin UIs

Status: Accepted Date: 2025-07-06

Context​

We need to protect sensitive, internal-facing web dashboards, such as the bull-board UI (adr://bull-dashboard-monitoring), from unauthorized access. These are not public-facing applications and are only intended for use by developers and operators. Implementing a full-blown OAuth or SSO integration for these simple, internal tools would be a significant amount of work for a low-traffic application. We need a simple, effective way to provide a baseline level of security.

Decision​

We will use HTTP Basic Authentication as the initial security mechanism for protecting internal administrative web UIs like bull-board.

A single, shared username and password will be configured in the mercury-worker's environment variables. The application will use a NestJS guard or middleware to protect the relevant routes (e.g., /admin/queues) and require a valid Authorization header. This provides a simple, universal, and effective barrier to entry.

This decision is seen as a first step. If and when our security needs for these tools evolve (e.g., we need per-user permissions or audit logs), this can be upgraded to a more robust solution like our company's SSO provider.

Consequences​

Positive:

  • Simple & Fast to Implement: Basic Auth is trivial to implement using standard libraries and requires minimal configuration.
  • Good Enough Security: For internal tools that are not exposed to the public internet, Basic Auth provides an effective and sufficient deterrent against unauthorized access.
  • Universal Support: Every browser and HTTP client natively supports Basic Auth.

Negative:

  • Shared Credentials: Uses a single shared username/password. This is not ideal as there is no per-user accountability, and revoking access for one person requires changing the credential for everyone.
  • Credentials Sent with Every Request: The Authorization header is sent with every request, which can be a minor security concern if not used over HTTPS.
  • Not "Enterprise-Grade": Lacks features like multi-factor authentication, password complexity rules, or centralized identity management.

Mitigation:

  • HTTPS Enforcement: All traffic to the worker, including the admin UIs, will be over HTTPS, ensuring the Basic Auth credentials are encrypted in transit.
  • Firewall/IP Whitelisting: Access to these admin endpoints will be further restricted at the network level (e.g., via a firewall or VPN) to only allow access from trusted IP addresses. Basic Auth is the second layer of defense, not the first.
  • Recognized as a Temporary Step: This solution is explicitly chosen for its simplicity. We acknowledge its limitations and have a clear path to upgrade it to a more robust authentication system if the need arises. The credentials will be managed via our secrets management system, making them easy to rotate.