Make Chrome trust a localhost development certificate

For local development, use mkcert to create a local CA, install its trust, and issue a certificate for the hostnames and IP addresses you use. A certificate needs matching Subject Alternative Name (SAN) entries as well as a trust path accepted by Chrome. Supplying only CN=localhost is insufficient.

Use mkcert

Install mkcert using the instructions for your platform. Common package-manager choices include Homebrew on macOS and Chocolatey on Windows; Ubuntu package availability depends on the release and enabled repositories.

mkcert -install
mkcert localhost 127.0.0.1 ::1

The second command normally creates localhost+2.pem and localhost+2-key.pem. Configure the local HTTPS server to load these as its certificate and private key. mkcert handles the SAN entries and creates certificates signed by your local development CA.

Browser trust integration depends on platform, browser version, and policy. Linux and Firefox setups may need NSS tools and access to the correct browser profile. Follow the mkcert installation and supported-root-store instructions, then verify trust in the actual browser you use.

Generate a certificate manually

For OpenSSL 3.x, this creates a self-signed certificate for localhost and both loopback addresses:

umask 077
openssl req -x509 -newkey rsa:2048 -noenc -days 365 \
  -keyout localhost.key -out localhost.crt \
  -subj "/CN=localhost" \
  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1,IP:::1" \
  -addext "basicConstraints=critical,CA:FALSE" \
  -addext "extendedKeyUsage=serverAuth"

-noenc leaves the private key unencrypted, so keep its permissions restrictive. Older OpenSSL versions use -nodes instead. This example makes a server certificate, not a CA authorized to issue other certificates.

Trusting a self-signed server certificate is platform-dependent. Windows certificate management and macOS Keychain Access expose local trust settings; apply them only to a certificate you generated or independently verified. On Linux, updating the operating system's CA bundle does not by itself guarantee Chrome will use that trust. Check Chrome's certificate manager and the policies for the installed version. Where direct leaf trust is unsupported or awkward, use a proper development CA through mkcert.

After installing the certificate on the server and configuring trust, fully restart Chrome, for example with chrome://restart, and open https://localhost.

Avoid common mistakes

• Include every address you actually visit. localhost and 127.0.0.1 require DNS and IP SAN entries respectively.
• Check Firefox independently when you use it; system-root integration varies by platform and settings.
• Keep this trust local to development. A trusted development CA can issue certificates accepted by that client, so its private key is highly sensitive.
• Never share mkcert's rootCA-key.pem, put private keys in Git, or rely on browser bypass flags as a permanent fix. Remove development trust when it is no longer needed.

Common questions

Why does Chrome still report a certificate error?

Inspect the certificate the server actually serves, not just the file you meant to install. Check SAN entries, validity, the correct browser trust store, and whether the browser was fully restarted:

openssl x509 -in localhost.crt -noout -ext subjectAltName

Do I need HTTPS for localhost at all?

Browsers generally treat http://localhost as a potentially trustworthy origin, so many secure-context APIs work there. HTTPS is useful when reproducing TLS behavior or satisfying an integration's requirements. OAuth redirect rules, cookies, and HTTP/2 behavior still depend on the service and browser.

Does everyone on the team need to set this up?

With separate local mkcert CAs, each developer installs their own CA and issues their own certificate. A project script can standardize the command without distributing any CA private key.

See the OpenSSL request command for certificate-generation options.