Node.js Reference ยท CLI Flags
Node.js NODE_EXTRA_CA_CERTS environment variable
Reference for NODE_EXTRA_CA_CERTS: add corporate or private certificate authorities to Node.js without turning off TLS verification, with a runnable check.
Node.js ships with its own list of trusted root certificate authorities (CAs), copied from Mozilla's list, instead of using the operating system's store. If your company runs a TLS-inspecting proxy, or a staging server uses a certificate signed by a private CA, fetch() and https.request() fail with errors such as UNABLE_TO_VERIFY_LEAF_SIGNATURE or SELF_SIGNED_CERT_IN_CHAIN.
NODE_EXTRA_CA_CERTS fixes that the safe way. Set it to the path of a PEM file containing one or more certificates, and Node adds them to the trusted list for the whole process. Verification stays on; you only widen who is trusted.
// shell: NODE_EXTRA_CA_CERTS=/etc/ssl/company-ca.pem node app.js
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
// NODE_EXTRA_CA_CERTS=/path/to/file.pem // tls.getCACertificates(type?: 'default' | 'system' | 'bundled' | 'extra'): string[] // tls.rootCertificates: string[] // the bundled roots only
| Part | Description |
|---|---|
| File | A PEM file; concatenate several -----BEGIN CERTIFICATE----- blocks to trust several CAs. |
'bundled' |
The Mozilla list built into Node. |
'extra' |
Certificates loaded from NODE_EXTRA_CA_CERTS. |
'default' |
What a new TLS connection trusts: bundled plus extra (and system certificates when --use-system-ca is on). |
Usage notes
- Read once, at process start. Setting
process.env.NODE_EXTRA_CA_CERTSfrom inside the program has no effect. Set it in the shell, the service definition, the DockerfileENV, or theenvoption ofchild_process. - Missing or unreadable file: Node prints a warning and continues with the built-in list. The file is loaded lazily, when TLS certificates are first needed, so the warning can appear later than process start (or never, in a program that never uses TLS). A silent fallback is easy to miss in logs, so check for the warning when a certificate error persists.
- It adds, never removes. You cannot use it to distrust a built-in CA.
- Applies to everything in the process:
https,tls,http2andfetch(). An individual request can still narrow trust with thecaoption, which replaces the default list for that connection. - System store: newer Node releases can also read the OS certificate store through the
--use-system-caflag. Checktls.getCACertificates('system')on your version before relying on it. - Prefer it to disabling checks.
NODE_TLS_REJECT_UNAUTHORIZED=0turns off protection for every connection; adding the one CA you need keeps protection for all others. - File content only. The file must hold public certificates. Never put private keys in it.
- Containers: copy the CA file into the image and set the variable in the Dockerfile; there is no need to run
update-ca-certificatesfor Node.