Skip to content

Basic auth and client certificates on Apache

Learn how to protect a directory or endpoint on Apache with HTTP Basic auth or mTLS client certificates. This guide walks through the htpasswd workflow and the SSL directives, then helps you choose between the two.

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

  1. 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-admin

    The -c flag creates the file; omit it for subsequent users. bcrypt is the strongest available — pass -B for bcrypt:

    sudo htpasswd -B /etc/apache2/.htpasswd-admin newuser
  2. 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>

    AuthName is shown in the browser’s auth prompt. Require valid-user accepts any user in the file; Require user admin restricts to one specific user.

  3. Enable the auth modules.

    sudo a2enmod auth_basic authn_file
    sudo apache2ctl configtest
    sudo systemctl reload apache2
  4. Test.

    curl -sI https://example.com/admin/
    curl -sI -u admin:correctpassword https://example.com/admin/

    First call: 401. Second call: 200.

  5. 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

  1. 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.crt to Apache (the trust anchor) and keep ca.key offline.

  2. 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 .p12 to the client. The browser or HTTP client imports it and presents it during TLS handshakes.

  3. 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>
  4. Reload and test. From a host with the .p12 available:

    curl --cert client.crt --key client.key https://api.example.com/private

    Without the cert, the curl call fails with a TLS error. With it, the request succeeds.

  5. 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-CN and 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.
  • htpasswd without -B defaults to MD5 (or worse on older versions) — always use -B for 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 require at 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 SSLCACertificateFile is rejected with a TLS error that does not appear in the access log — check error.log for 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.