What is HTTP Basic Authentication and when is it used?
HTTP Basic Authentication is one of the oldest authentication methods, defined in the HTTP protocol's own standard, for restricting access to a directory or URL with a username and password. When a protected page is opened, the browser shows its own built-in login dialog; once the username and password are entered, the browser sends that information to the server with every request. No session management, cookie or application-level login form is needed — verification happens entirely at the web server (Apache or Nginx) layer.
That simplicity makes Basic Auth a realistic choice for particular scenarios: hiding a staging environment that has not gone live yet from search engines and casual visitors, protecting an admin panel (a monitoring tool, an internal dashboard, or a tool such as phpMyAdmin) with an extra layer, or simply blocking outside access to a directory used only within the team. It requires no user registration, no password reset flow and no database; a few lines of server configuration are enough. By contrast, Basic Auth is not suitable for a public membership system or for situations that need detailed role/permission-based authorisation; those needs call for an authentication system at the application level.
Basic Auth should be thought of not as a replacement for an in-application login system but as an extra door at the server level. For example, when you want to hide the test server of a WordPress installation from the outside world before going live, you can put the whole site behind a password by adding a few lines to the server configuration without touching the application at all. The same approach also works for a CI/CD preview environment, an internal reporting tool or an API endpoint that is still being tested.
.htpasswd file format and password hashing
.htpasswd is a plain-text file that holds username and password pairs line by line — but plain text here refers to the file itself, not to how the password is stored. Each line is in the form username:hash, and several users can be defined in one file. In a correctly generated .htpasswd file passwords are never stored as clear text; they are always kept after being passed through a hash function.
Apache supports several hash schemes. The format that begins with the {SHA} prefix consists of the SHA-1 digest of the password encoded with Base64 and is what the classic htpasswd -s command produces; this scheme is still supported for backward compatibility, but SHA-1 is considered cryptographically weak. The format beginning with $apr1$ is Apache's own MD5-based (APR1) algorithm. On modern Apache installations the bcrypt hash generated with htpasswd -B should be preferred wherever possible; bcrypt is deliberately designed to run slowly, and that property makes it far more resistant to brute-force attacks. On the Nginx side, ngx_http_auth_basic_module supports the {SHA} format directly; because bcrypt support can vary from build to build, you need to check in advance which hash scheme is supported.
Configuration on the Apache side
In Apache, Basic Auth can be defined in two ways: inside a <Directory> block in the main configuration file, or in a .htaccess file dropped into the directory to be protected. Both methods use the same four directives: AuthType Basic states that the authentication method is Basic; AuthName is the text the browser shows in the login dialog (the realm); AuthUserFile is the full path on the server to the .htpasswd file containing the username:hash lines; and Require valid-user allows any user defined in that file to log in — for specific users only, Require user username can be written instead.
If you are working with .htaccess, writing the same four lines directly into that file is enough; but for it to work, AllowOverride AuthConfig (or AllowOverride All) must be defined for the relevant directory in the main configuration. Otherwise Apache completely ignores the authentication directives inside .htaccess and the directory is left unprotected. When this setting is forgotten, people assume the file 'is not working' and start questioning the hash or the path; yet the problem is usually the AllowOverride line.
Configuration on the Nginx side
Nginx does not support per-directory override files like .htaccess; all configuration is defined inside a server or location block. Two directives are enough for Basic Auth: auth_basic sets the realm text shown in the browser (the value off can be used to disable it), and auth_basic_user_file points to the path of the .htpasswd file on the server.
If you want to protect the entire site rather than a specific subdirectory, you can write the same two lines directly inside the server block instead of a location block. Unlike Apache's .htaccess file, in Nginx no change takes effect until the configuration is reloaded (nginx -s reload); so remember that the service has to be told about the change afterwards.
Common mistakes
| Mistake | Why it is risky |
|---|---|
| Serving Basic Auth over plain HTTP | Credentials are only <b>Base64-encoded, not encrypted</b>; without HTTPS anyone listening on the network can read the username and password directly. Basic Auth must therefore always be served over HTTPS. |
| Placing the <code>.htpasswd</code> file inside the web root | If the file can be requested directly by URL, the hash lines become downloadable; the file should be kept outside the web root or access to it blocked separately in the server configuration. |
| Forgetting to define <code>AllowOverride AuthConfig</code> in Apache | The <code>AuthType</code>/<code>AuthUserFile</code> directives inside <code>.htaccess</code> are completely ignored and the directory is left unprotected without any error. |
| Leaving the permissions on the <code>.htpasswd</code> file wider than necessary | Other users or processes sharing the server can reach the hash values; the file should be readable only by the web server user. |
| Using a weak or outdated hash scheme | Old hash formats that are close to plain text or easily cracked mean passwords are broken quickly once the file is stolen; bcrypt should be preferred wherever possible. |
Set up correctly, Basic Auth is a simple but effective access barrier added without touching the application code. Because a single line of misconfiguration — a wrong path, a forgotten AllowOverride, serving over HTTP — can render this protection meaningless, both the .htpasswd line and the server-side directives should be tested from a browser after installation.