Configure SSL certificates and proxy settings for extractors

Cognite extractors often need extra TLS trust and proxy settings when they run on-premises or in cloud virtual machines (VMs). You configure trust between the extractor runtime, source systems, your identity provider (IdP), and Cognite Data Fusion (CDF). Use this procedure for these enterprise network scenarios:

Self-signed server certificates on source automation or database systems.
Corporate proxies and firewalls performing TLS inspection by injecting certificates signed by an internal Certificate Authority (CA).
Mutual TLS (mTLS) requiring client authentication certificates.
Forward proxies routing outbound traffic from the extractor host.

Prerequisites

Verify all of the following before you start:

You know which extractor you are running and whether it uses the .NET runtime or Python (httpx or requests). See Identify your extractor runtime.
You have administrator or root access on the extractor host so you can update the certificate store or environment variables.
You have the CA or self-signed server certificate in .cer, .crt, .pem, or .pfx format. For mTLS, you also have the client certificate and private key.
The extractor is installed, and you can restart its Windows service, Linux process, or container.

Identify your extractor runtime

Extractors use different cryptographic trust stores and TLS libraries depending on their underlying runtime:

Extractor runtime	Example extractors	Trust mechanism	Key configuration
.NET runtime	Cognite PI extractor, Cognite PI AF extractor, Cognite OPC UA extractor (Windows)	Operating system certificate store	Windows Certificate Manager (`certlm.msc`) or Linux CA store
Python (`httpx`)	Modern Python extractors and SDK clients	Environment variable or custom bundle	`SSL_CERT_FILE`
Python (`requests`)	Python extractors using `requests` / `certifi`	Environment variable or custom bundle	`REQUESTS_CA_BUNDLE`

Configure trust for self-signed certificates and private CAs

When a source system presents a self-signed certificate, the extractor must trust that certificate to establish an encrypted connection. The same trust is required if a corporate proxy inspects outbound TLS traffic using an internal CA.

.NET extractors
Python extractors

.NET-based extractors inherit certificate trust directly from the host operating system.

Windows host

Obtain the certificate

Export or obtain the root CA or self-signed server certificate in .cer, .crt, or .pfx format.

Import into the local machine store

Open the Start menu, search for Manage computer certificates (certlm.msc), and open it.
Expand Trusted Root Certification Authorities > Certificates.
Right-click Certificates, select All Tasks > Import, and follow the wizard to import your certificate file into the Local Machine store.

Restart the extractor service

Restart the extractor Windows service or console application to pick up the updated system trust store.

Linux host

Copy the certificate to the system trust directory

Copy your CA certificate (.crt format) to the system store:

# Ubuntu / Debian
sudo cp internal-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

# RHEL / Rocky Linux / CentOS
sudo cp internal-ca.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

Restart the extractor

Restart the extractor process or container.

Python extractors rely on bundled CA certificates. To add trust for internal CAs or self-signed certificates, create a combined certificate bundle and point the runtime environment variable to it.

Create a combined certificate bundle

Locate the default certifi CA bundle or export your standard public certificates:
python -c "import certifi; print(certifi.where())"
Make a copy of the default cacert.pem file in a persistent directory accessible by the extractor service user.

Append your PEM-encoded internal CA or self-signed certificate to the end of the copied file:

# Linux / macOS
cat internal-ca.pem >> /opt/cognite/certificates/cacert.pem

# Windows PowerShell
Get-Content .\internal-ca.pem | Add-Content C:\Cognite\certificates\cacert.pem

Set environment variables

Configure the environment variable that matches your extractor’s HTTP library:

Modern Python extractors (httpx)
Extractors using requests

Set SSL_CERT_FILE to the path of the combined bundle:

# Windows (System environment variable or PowerShell)
[Environment]::SetEnvironmentVariable("SSL_CERT_FILE", "C:\Cognite\certificates\cacert.pem", "Machine")

# Linux (/etc/environment or systemd service unit)
export SSL_CERT_FILE=/opt/cognite/certificates/cacert.pem

Set REQUESTS_CA_BUNDLE to the path of the combined bundle:

# Windows (System environment variable or PowerShell)
[Environment]::SetEnvironmentVariable("REQUESTS_CA_BUNDLE", "C:\Cognite\certificates\cacert.pem", "Machine")

# Linux (/etc/environment or systemd service unit)
export REQUESTS_CA_BUNDLE=/opt/cognite/certificates/cacert.pem

Verify extractor user permissions

Ensure the service account running the extractor has read permissions for the custom .pem bundle file.

Verify certificate trust

After you restart the extractor, confirm it connects without certificate errors:

Start or restart the extractor.
Check the extractor log. A successful TLS handshake does not include CERTIFICATE_VERIFY_FAILED, certificate verify failed, or self signed certificate.
If errors persist, use Troubleshooting certificate and connection errors.

Do not leave certificate validation disabled in production. Flags such as source.ignore-certificate-issues: true, source.auto-accept: true, or verify: false expose telemetry and credentials to interception. Use these settings only for short diagnostic tests while you set up certificate trust.

mTLS certificate practices

Some source systems (such as secure OPC UA endpoints, REST APIs, or MQTT brokers) require mutual TLS, where the extractor presents a client certificate to prove its identity. Extractor YAML for client certificates is product-specific — for the Cognite OPC UA extractor, see x509-certificate in the configuration reference.

Secret managers: Store private keys and client certificates in a vault such as Azure Key Vault or AWS Secrets Manager when you can. Many extractors support !keyvault <secret-name> in YAML. See the configuration reference for your extractor.
File-based certificates: If you use local file paths, restrict filesystem permissions so only the extractor service account can read the files.
Certificate renewal: Rotate certificates before they expire so extraction does not stop.

Configure forward proxy settings

If your network routes outbound internet traffic through an HTTP or HTTPS forward proxy to reach CDF APIs and your identity provider (such as Microsoft Entra ID), configure standard proxy environment variables.

Standard proxy environment variables

Most extractors honor standard proxy environment variables:

# Linux / macOS
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.local,.internal-domain.com"

# Windows PowerShell
$env:HTTP_PROXY="http://proxy.example.com:8080"
$env:HTTPS_PROXY="http://proxy.example.com:8080"
$env:NO_PROXY="localhost,127.0.0.1,.local,.internal-domain.com"

Ensure that internal source system hostnames and local IP addresses are included in NO_PROXY so the extractor communicates directly with local data sources without routing through the external proxy.

Troubleshooting certificate and connection errors

SSL: CERTIFICATE_VERIFY_FAILED / certificate verify failed: self signed certificate

Cause: The extractor runtime cannot verify the source system or proxy certificate against its trust store.Solution:

Check whether the source system uses a self-signed certificate or whether an intermediate proxy is intercepting the connection.
Export the root CA or self-signed certificate.
Add the certificate to the OS trust store (for .NET extractors) or configure SSL_CERT_FILE / REQUESTS_CA_BUNDLE (for Python extractors).

Extractor fails to connect when corporate proxy TLS inspection is active

Cause: Corporate firewalls often generate dynamic certificates signed by an internal enterprise CA. The host OS might trust this CA, but Python extractors or containerized workloads may not.Solution: Export your company’s root and intermediate CA certificates from the corporate trust store, append them to the extractor’s certificate bundle, and set SSL_CERT_FILE or REQUESTS_CA_BUNDLE.

Should I use ignore-certificate-issues or auto-accept in production?

Cause: Flags such as source.ignore-certificate-issues: true, source.auto-accept: true, or verify: false disable certificate validation and leave telemetry and credentials open to interception.Solution: Do not use these flags in production. Use them only for short diagnostic tests, then restore validation. See the Warning in Verify certificate trust.

​Prerequisites

​Identify your extractor runtime

​Configure trust for self-signed certificates and private CAs

​Windows host

​Linux host

​Verify certificate trust

​mTLS certificate practices

​Configure forward proxy settings

​Standard proxy environment variables

​Troubleshooting certificate and connection errors

​Related documentation

Prerequisites

Identify your extractor runtime

Configure trust for self-signed certificates and private CAs

Windows host

Linux host

Verify certificate trust

mTLS certificate practices

Configure forward proxy settings

Standard proxy environment variables

Troubleshooting certificate and connection errors

Related documentation