> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure SSL certificates and proxy settings for extractors

> Step-by-step guide to configure self-signed certificates, mTLS, and corporate proxy TLS interception for .NET and Python 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](#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.

<Tabs>
  <Tab title=".NET extractors">
    .NET-based extractors inherit certificate trust directly from the host operating system.

    ### Windows host

    <Steps>
      <Step title="Obtain the certificate">
        Export or obtain the root CA or self-signed server certificate in `.cer`, `.crt`, or `.pfx` format.
      </Step>

      <Step title="Import into the local machine store">
        1. Open the Start menu, search for `Manage computer certificates` (`certlm.msc`), and open it.
        2. Expand **Trusted Root Certification Authorities** > **Certificates**.
        3. Right-click **Certificates**, select **All Tasks** > **Import**, and follow the wizard to import your certificate file into the **Local Machine** store.
      </Step>

      <Step title="Restart the extractor service">
        Restart the extractor Windows service or console application to pick up the updated system trust store.
      </Step>
    </Steps>

    ### Linux host

    <Steps>
      <Step title="Copy the certificate to the system trust directory">
        Copy your CA certificate (`.crt` format) to the system store:

        ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        # 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
        ```
      </Step>

      <Step title="Restart the extractor">
        Restart the extractor process or container.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Python extractors">
    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.

    <Steps>
      <Step title="Create a combined certificate bundle">
        1. Locate the default `certifi` CA bundle or export your standard public certificates:

           ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
           python -c "import certifi; print(certifi.where())"
           ```

        2. Make a copy of the default `cacert.pem` file in a persistent directory accessible by the extractor service user.

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

           ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
           # Linux / macOS
           cat internal-ca.pem >> /opt/cognite/certificates/cacert.pem
           ```

           ```powershell theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
           # Windows PowerShell
           Get-Content .\internal-ca.pem | Add-Content C:\Cognite\certificates\cacert.pem
           ```
      </Step>

      <Step title="Set environment variables">
        Configure the environment variable that matches your extractor's HTTP library:

        <Tabs>
          <Tab title="Modern Python extractors (httpx)">
            Set `SSL_CERT_FILE` to the path of the combined bundle:

            ```powershell theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
            # Windows (System environment variable or PowerShell)
            [Environment]::SetEnvironmentVariable("SSL_CERT_FILE", "C:\Cognite\certificates\cacert.pem", "Machine")
            ```

            ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
            # Linux (/etc/environment or systemd service unit)
            export SSL_CERT_FILE=/opt/cognite/certificates/cacert.pem
            ```
          </Tab>

          <Tab title="Extractors using requests">
            Set `REQUESTS_CA_BUNDLE` to the path of the combined bundle:

            ```powershell theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
            # Windows (System environment variable or PowerShell)
            [Environment]::SetEnvironmentVariable("REQUESTS_CA_BUNDLE", "C:\Cognite\certificates\cacert.pem", "Machine")
            ```

            ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
            # Linux (/etc/environment or systemd service unit)
            export REQUESTS_CA_BUNDLE=/opt/cognite/certificates/cacert.pem
            ```
          </Tab>
        </Tabs>
      </Step>

      <Step title="Verify extractor user permissions">
        Ensure the service account running the extractor has read permissions for the custom `.pem` bundle file.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Verify certificate trust

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

1. Start or restart the extractor.
2. Check the extractor log. A successful TLS handshake does not include `CERTIFICATE_VERIFY_FAILED`, `certificate verify failed`, or `self signed certificate`.
3. If errors persist, use [Troubleshooting certificate and connection errors](#troubleshooting-certificate-and-connection-errors).

<Warning>
  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.
</Warning>

## 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`](/cdf/integration/guides/extraction/configuration/opcua#source.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:

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
# 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"
```

```powershell theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
# 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"
```

<Info>
  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.
</Info>

***

## Troubleshooting certificate and connection errors

<AccordionGroup>
  <Accordion title="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**:

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

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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](#verify-certificate-trust).
  </Accordion>
</AccordionGroup>

***

## Related documentation

* [Allowlist and network requirements](/cdf/admin/allowlist)
* [OPC UA extractor troubleshooting](/cdf/integration/guides/extraction/opc_ua/opc_ua_troubleshooting)
* [SAP extractor setup](/cdf/integration/guides/extraction/sap/sap_setup)