How to enable basic authentication in Apache

Basic authentication puts a browser login prompt in front of a site, directory, or admin path before Apache serves the content. It is a practical containment layer for staging sites, internal dashboards, and temporary maintenance areas where anonymous requests should stop at a credential challenge instead of reaching the application.

Apache handles this flow with mod_auth_basic and an authentication provider such as mod_authn_file. The provider reads usernames and password hashes from a file created with htpasswd, while the protected section is usually defined in a Directory block inside the matching virtual host so the rule is loaded once when Apache starts.

Basic authentication must only be exposed through HTTPS because the credentials are encoded, not encrypted. Keep the password file outside the document root, prefer the main virtual host config over .htaccess for the default setup, and remember that .htaccess authentication directives only take effect when the matching directory allows AllowOverride AuthConfig.

1. Enable the authentication modules if the distro packaging has not loaded them already.

   $ sudo a2enmod auth_basic authn_file
   Considering dependency authn_core for auth_basic:
   Module authn_core already enabled
   Module auth_basic already enabled
   Module authn_file already enabled

   On RHEL-family systems, these modules are commonly available and loaded by default.

2. Install the password-file utility if htpasswd is not already present.

   $ sudo apt install --assume-yes apache2-utils
   apache2-utils is already the newest version (2.4.58-1ubuntu8.8).
   ##### snipped #####

   On RHEL-family systems, install httpd-tools.

3. Create the password file outside the web root and add the first user.

   $ sudo htpasswd -cB /etc/apache2/.htpasswd admin
   New password:
   Re-type new password:
   Adding password for user admin

   The -c option creates a new file and overwrites an existing one. Omit it when adding more users, for example sudo htpasswd -B /etc/apache2/.htpasswd alice.

   Use htpasswd -i for non-interactive automation. Avoid -b unless the environment is tightly controlled because it exposes the password on the command line.

4. Restrict access to the password file so only root and the Apache runtime group can read it.

   $ sudo chown root:www-data /etc/apache2/.htpasswd
   $ sudo chmod 0640 /etc/apache2/.htpasswd

   Replace www-data with the active Apache group on the host, such as apache on RHEL-family systems.

   If the Apache runtime user cannot read the password file, authentication fails with 500 and an auth provider error in the error log.

5. Add the authentication directives to the matching virtual host or included site config.

   <Directory "/var/www/html/admin">
       AuthType Basic
       AuthName "Restricted"
       AuthBasicProvider file
       AuthUserFile /etc/apache2/.htpasswd
       Require valid-user
   </Directory>

   Place the block inside the correct VirtualHost so only that site or path is protected. AuthName is the label shown in the browser login prompt.

   Use Location instead of Directory when the protected target is mapped by URL rather than by a filesystem path, such as a proxied admin endpoint. If .htaccess must hold the auth rules, the matching directory also needs AllowOverride AuthConfig.

6. Test the Apache configuration before applying the change.

   $ sudo apache2ctl configtest
   Syntax OK

   Use sudo apachectl -t or sudo httpd -t on platforms that ship those control names instead.

   Related: How to test Apache configuration

7. Reload Apache to apply the new authentication rules.

   $ sudo systemctl reload apache2

   Use sudo apache2ctl graceful when systemd is not managing the service. On RHEL-family systems, the unit name is commonly httpd.

   Related: How to manage the Apache web server service

8. Verify that unauthenticated requests are challenged and valid credentials are accepted.

   $ curl -sI -H 'Host: example.com' http://127.0.0.1/admin/
   HTTP/1.1 401 Unauthorized
   Date: Wed, 08 Apr 2026 04:49:38 GMT
   Server: Apache/2.4.58 (Ubuntu)
   WWW-Authenticate: Basic realm="Restricted"
   Content-Type: text/html; charset=iso-8859-1
   ##### snipped #####
   
   $ curl -sI -H 'Host: example.com' -u admin:******** http://127.0.0.1/admin/
   HTTP/1.1 200 OK
   Date: Wed, 08 Apr 2026 04:49:38 GMT
   Server: Apache/2.4.58 (Ubuntu)
   Last-Modified: Wed, 08 Apr 2026 04:49:38 GMT
   ETag: W/"a-64eeba0972ed2"
   Accept-Ranges: bytes
   Content-Length: 10
   Content-Type: text/html
   ##### snipped #####

   Expose the protected path through HTTPS before giving the URL to other users. The local HTTP check is only for confirming that the challenge and login flow works before the site is published.