How to set up authentication with .htaccess

Password-protect a directory or website in Apache HTTP Server using .htaccess, mod_auth_basic, and the htpasswd utility to create user credentials.

Prerequisites
Step-by-Step: Set Up .htaccess Authentication with Root Access
Step-by-Step: Set Up .htaccess Authentication Without Root Access
How to Verify .htaccess Authentication Works
Common Issues When Setting Up .htaccess Authentication

Set up HTTP Basic Authentication on Apache HTTP Server to password-protect a website directory using .htaccess and the htpasswd utility.

Prerequisites

Apache HTTP Server 2.4 or later with mod_auth_basic and mod_authn_file modules enabled.
AllowOverride AuthConfig (or AllowOverride All) set in the server configuration for the target directory.
SSH or terminal access to the server (for the htpasswd command). An alternative method for shared hosting without shell access is covered below.

Step-by-Step: Set Up .htaccess Authentication with Root Access

Connect to the server via SSH and navigate to the directory to protect. The htpasswd utility ships with Apache HTTP Server and creates the credential file.
To protect the entire website, navigate to the document root:
```
cd /var/www/example_com/public_html
```
To protect a specific subdirectory (such as example.com/admin/), navigate to that directory instead:
```
cd /var/www/example_com/public_html/admin
```
Run the htpasswd command to create a .htpasswd file with the first user account. The -c flag creates a new file. Apache stores the password using bcrypt or MD5 hash, not in plain text.
```
htpasswd -c /var/www/example_com/public_html/.htpasswd myuser
```
The command prompts for a password. Enter and confirm the password.
To add more users to an existing .htpasswd file, run htpasswd without the -c flag. The -c flag overwrites the file and removes all existing users.
```
htpasswd /var/www/example_com/public_html/.htpasswd anotheruser
```
Set file permissions on the .htpasswd file. Apache needs read access; other users should not have write or execute permissions.
```
chmod 644 /var/www/example_com/public_html/.htpasswd
```
Create or edit the .htaccess file in the directory to protect. Add the mod_auth_basic directives that point to the .htpasswd credential file.
```
AuthType Basic
AuthName "Restricted Area"
AuthUserFile /var/www/example_com/public_html/.htpasswd
Require valid-user
```
The AuthUserFile directive requires the absolute pathto the .htpasswd file. Relative paths do not work.
The Require valid-user directive grants access to any user listed in the .htpasswd file. To restrict access to a specific username, replace valid-user with user myuser:
```
Require user myuser
```
Restart Apache HTTP Server to clear any cached configurations. The restart command varies by operating system.
On Debian and Ubuntu:
```
sudo systemctl restart apache2
```
On CentOS, RHEL, and Fedora:
```
sudo systemctl restart httpd
```
On Alpine Linux:
```
sudo service apache2 restart
```

Step-by-Step: Set Up .htaccess Authentication Without Root Access

Shared hosting environments often lack SSH access. Use the hosting control panel's file manager to create the credential files.

Open the hosting control panel (cPanel, Plesk, or similar) and navigate to File Manager. Locate the document root directory, typically public_html/.
Create a new file named .htpasswd in the document root. Use an online .htpasswd generator to create a username and bcrypt-hashed password. Paste the generated line into the .htpasswd file and save.
Determine the absolute path to the .htpasswd file. If the hosting panel does not display the full path, create a temporary PHP file named path.php in the document root with this content:
```
<?php echo $_SERVER['DOCUMENT_ROOT']; ?>
```
Visit https://example.com/path.php in a browser to see the absolute path. Delete path.php immediately after noting the path.
Create or edit the .htaccess file in the directory to protect. Add the mod_auth_basic directives using the absolute path from the previous step.
```
AuthType Basic
AuthName "Restricted Area"
AuthUserFile "/home/myuser/public_html/.htpasswd"
Require valid-user
```
Replace /home/myuser/public_html/ with the actual path from step 3.

How to Verify .htaccess Authentication Works

Open a browser and navigate to the protected directory URL. Apache HTTP Server displays a browser-native authentication dialog requesting a username and password. Enter valid credentials from the .htpasswd file to confirm access.

Test with invalid credentials to verify that Apache returns a 401 Unauthorized response. Check the Apache error log if the dialog does not appear:

tail -f /var/log/apache2/error.log

Common Issues When Setting Up .htaccess Authentication

Apache returns a 500 Internal Server Error instead of the login dialog.The AllowOverride directive in httpd.conf does not include AuthConfig. Set AllowOverride AuthConfig or AllowOverride All in the <Directory> block for the protected directory. See .htaccess: 500 Internal Server Error.

Apache returns a 403 Forbidden after entering correct credentials.The AuthUserFile path is incorrect or the .htpasswd file has wrong permissions. Verify the absolute path and set permissions to 644. See .htaccess: 403 Forbidden.

The authentication dialog appears repeatedly even with correct credentials.The .htpasswd file contains a corrupted hash or the password was generated with an unsupported algorithm. Regenerate the credentials with htpasswd and verify the file contains one username:hash entry per line.