This article is for admins who need to lock down an Apache directory or endpoint without running a separate authentication service. A typical case is an admin panel left open to the internet, or an internal API that only a few partners should reach. Apache has two built-in answers. The first is HTTP Basic auth, where the browser sends a username and password encoded in a request header, and Apache checks them against an htpasswd file. The second is mTLS (mutual TLS), where the client presents a certificate during the TLS handshake that opens the encrypted connection. Basic auth is a cheap way to protect admin pages. mTLS suits B2B (business-to-business) API endpoints and internal-only services. You will find the setup for each, plus a decision matrix to help you pick.
How to verify
Confirm what is currently protecting any restricted paths:
apachectl -M | grep -E 'auth|ssl'
grep -rE 'AuthType|Require|SSLVerifyClient' /etc/apache2/sites-enabled/ /etc/apache2/conf-enabled/
ls -la /etc/apache2/.htpasswd /etc/apache2/htpasswd 2>/dev/null
curl -sI https://example.com/admin/ | head -3
curl -sI -u admin:wrong https://example.com/admin/ | head -3
A protected resource returns 401 Unauthorized with a WWW-Authenticate: Basic realm="..." header. With the right credentials, it returns 200. For mTLS, a request without a client cert returns 400 or hangs during the TLS handshake.
What’s happening
HTTP Basic auth is the simplest auth mechanism: the client sends Authorization: Basic <base64(user:pass)> in every request. Apache validates against a password file (created with htpasswd) and serves the resource or returns 401. Basic auth requires TLS in production — without it, the credentials are transmitted in cleartext, base64-encoded but not encrypted.
mTLS (mutual TLS) authenticates the client to the server during the TLS handshake. The client presents a certificate signed by a CA the server trusts, the server validates the certificate, and (if valid) lets the request through. No password header is sent. mTLS is operationally heavier — you need a CA, a way to issue and revoke certs, and a client device that can use them — but it is dramatically stronger than Basic auth.
When to use each:
- Basic auth — quick admin protection, staging environments, internal tooling where the user count is small.
- mTLS — B2B APIs, internal-only services with a small enrolled fleet, regulated environments where credentials must not transit on the wire.
- Neither — for user-facing apps with hundreds of users, use SSO (OIDC, SAML) via an upstream auth proxy. Basic auth has no logout, no MFA, no audit; mTLS has no convenient enrollment.
The procedure for Basic auth
-
Create the password file. The standard location is outside the DocumentRoot:
sudo htpasswd -c /etc/apache2/.htpasswd-admin admin # prompts for password, twice sudo htpasswd /etc/apache2/.htpasswd-admin reader sudo chmod 640 /etc/apache2/.htpasswd-admin sudo chown root:www-data /etc/apache2/.htpasswd-adminThe
-cflag creates the file; omit it for subsequent users.bcryptis the strongest available — pass-Bfor bcrypt:sudo htpasswd -B /etc/apache2/.htpasswd-admin newuser -
Protect the path in the vhost. Inside
<VirtualHost>:<Location /admin> AuthType Basic AuthName "Restricted area — staff only" AuthUserFile /etc/apache2/.htpasswd-admin Require valid-user </Location>AuthNameis shown in the browser’s auth prompt.Require valid-useraccepts any user in the file;Require user adminrestricts to one specific user. -
Enable the auth modules.
sudo a2enmod auth_basic authn_file sudo apache2ctl configtest sudo systemctl reload apache2 -
Test.
curl -sI https://example.com/admin/ curl -sI -u admin:correctpassword https://example.com/admin/First call: 401. Second call: 200.
-
For group-based access, use a group file:
sudo tee /etc/apache2/.htgroup <<EOF admins: alice bob readers: carol dave EOF # In vhost: AuthGroupFile /etc/apache2/.htgroup Require group admins
The procedure for mTLS
-
Set up a CA. For internal use, a minimal OpenSSL CA is fine. For production B2B, use a dedicated PKI tool (step-ca, EJBCA, Vault PKI). A bare-minimum CA setup:
openssl genrsa -out ca.key 4096 openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 \ -out ca.crt -subj "/CN=Example mTLS CA"Distribute
ca.crtto Apache (the trust anchor) and keepca.keyoffline. -
Issue a client certificate. Per client:
openssl genrsa -out client.key 2048 openssl req -new -key client.key -out client.csr -subj "/CN=client-name" openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial \ -out client.crt -days 365 -sha256 openssl pkcs12 -export -in client.crt -inkey client.key -out client.p12 -name "client-name"Distribute the
.p12to the client. The browser or HTTP client imports it and presents it during TLS handshakes. -
Configure Apache to require client certs. In the HTTPS vhost:
<VirtualHost *:443> ServerName api.example.com SSLEngine on SSLCertificateFile /etc/letsencrypt/live/api.example.com/fullchain.pem SSLCertificateKeyFile /etc/letsencrypt/live/api.example.com/privkey.pem # Trust this CA for client certs SSLCACertificateFile /etc/apache2/mtls/ca.crt # Optional, only require for specific paths <Location /private> SSLVerifyClient require SSLVerifyDepth 1 </Location> # Or require for the entire vhost # SSLVerifyClient require # SSLVerifyDepth 1 </VirtualHost> -
Reload and test. From a host with the
.p12available:curl --cert client.crt --key client.key https://api.example.com/privateWithout the cert, the curl call fails with a TLS error. With it, the request succeeds.
-
Pass the client CN to the upstream. When Apache acts as a reverse proxy and the upstream needs to know who authenticated:
RequestHeader set X-Client-CN "%{SSL_CLIENT_S_DN_CN}s"The upstream reads
X-Client-CNand authorizes based on the certificate subject.
Decision
- Internal admin path, small team, ad-hoc: Basic auth with bcrypt hashes is fine. Rotate the password file annually.
- Public API for B2B partners: mTLS. Each partner gets a cert; revocation lists handle deprovisioning.
- End-user-facing application: neither — use SSO via an upstream auth proxy (Authelia, Authentik, Cloudflare Access).
Common pitfalls
- Basic auth has no logout — once credentials are cached by the browser, the only way to “log out” is to close the browser or hit a 401-returning URL on a different realm.
htpasswdwithout-Bdefaults to MD5 (or worse on older versions) — always use-Bfor bcrypt.- mTLS revocation is hard. CRLs (
SSLCARevocationFile) need to be regenerated and reloaded. For high-volume revocations, consider an upstream auth gateway with online revocation checking. SSLVerifyClient requireat vhost scope rejects every request without a cert, including health checks — scope it to<Location>or whitelist the health check path.- A client cert signed by a different CA than the one in
SSLCACertificateFileis rejected with a TLS error that does not appear in the access log — checkerror.logfor the actual failure.
Stack Harbor sets up Basic auth and mTLS as standard access patterns where they fit, with the credentials and CAs under proper rotation. For larger access-control needs, the standard pattern is an upstream SSO proxy in front of Apache. The fit-for-purpose call is part of the Managed Operations onboarding.