icon-unified.svg
Experience Center

Adding Custom Certificate to an Application Specific Trust Store

Whenever Zscaler SSL inspection is enabled to maintain secure connections on the corporate network, admins can use the organization-generated certificate to connect to any secure website. By default, the root and intermediate certificates, which are required to trust the organization's generated certificate, are already added to the end user's system certificate store.

Some applications maintain a custom trust store instead of using the default system trust store. As a result, the application is not able to validate Zscaler-generated server certificates and the TLS connection fails. In such cases, the users need to manually add the custom root CA to the custom trust store, or disable server certificate validation.

You can add custom certificates for the following applications:

If you are an end user, you can get the root CA certificate for your organization from your administrator. If you are an administrator, provide your users with the root CA certificate (i.e., Zscaler root CA certificate or custom root CA certificate) that is applicable to your organization. To learn how to download the Zscaler root CA certificate from the Admin Portal, see Choosing the CA Certificate for SSL Inspection.

  • Data science tools, such as RStudio and PowerBI, can connect to Snowflake's cloud data warehouse using HTTPS. For Snowflake traffic to work seamlessly in any environment over HTTPS in a proxy environment, you must replace the PEM file under C:\Program Files\Snowflake ODBC Driver\etc with your custom CA PEM file.

    Ensure that you rename your custom PEM file to the same name as that of the PEM file originally present in the location.

    Close

  • Different Python modules or installers implement their own certificate stores separately. This section covers the following two modules:

    • Use one of the following methods to configure the custom CA certificate for Python:

      • To add the custom certificates for PIP to the trust store:

        • On macOS and Linux platforms:
        1. Create or download the certificate bundle in PEM format.
        2. Create a new directory and move the bundle to the new location using the following Bash commands:
        mkdir ~/ca_certs
    mv ~/Downloads/custom-ca-bundle.pem ~/ca_certs
        1. Add the custom certificate using the following Bash command:
        pip config set global.cert ~/ca_certs
        • On Windows platform:
        1. Create or download the certificate bundle in PEM format.
        2. Create a new directory and move the bundle to C:\ drive.
        3. Add the certificate to the trust store using the following commands on PowerShell:
        mv $env:HOMEPATH\Downloads\custom-ca-bundle.pem $env:APPDATA
    pip config set global.cert $env:APPDATA\custom-ca-bundle.pem
        Close

      • Run the following commands to set the SSL_CERT_FILE config option:

        export CERT_PATH=/etc/ssl/certs/ZscalerRootCA.pem
    export CERT_DIR=/etc/ssl/certs/
    export SSL_CERT_FILE=${CERT_PATH} 
    export SSL_CERT_DIR=${CERT_DIR}
    export REQUESTS_CA_BUNDLE=${CERT_PATH}
        Close

      • You can install the pip-system-certs package, which patches the PIP and the requests at runtime to use certificates from the default system store rather than the bundled certificates CA.

        Install the system certificates using the following command:

        pip install -trusted-host files.pythonhosted.org pip_system_certs

        After entering the command, PIP trusts HTTPS sites that are trusted by your host OS. It also trusts all the direct uses of the requests library and the other packages that use requests.

        Close

      • Use one of the following methods to configure the CA certificate:

          1. Install the certifi package using the following command:
          pip install certifi | pip install --upgrade certifi
          1. Check for the certificate’s location, python -m certifi
          2. Update the cacert.pem with Zscaler certificate using the following command:
          cat ZscalerRootCA.pem >> $(python -m certifi)

          You can also set the PIP config global certificate using the following command:

          pip config set global.cert $(python -m certifi)
          Close

        • Run the following command:

          export CERT_PATH=$(python -m certifi) 
    export SSL_CERT_FILE=${CERT_PATH} 
    export REQUESTS_CA_BUNDLE=${CERT_PATH}
          Close

        You cannot add a custom CA certificate using the certifi package option. You can only overwrite it when you update the certifi package.

        Close
      Close

    • Requests automatically search for any valid certificate in the REQUESTS_CA_BUNDLE environment variable.

      To configure the REQUESTS_CA_BUNDLE environment variable:

      • On macOS, run the following Bash command:
      echo "export REQUESTS_CA_BUNDLE=<Path to Certificate>/ca-bundle.pem" >> $HOME/.bash_profile
      • On Linux, run the following Bash command:
       echo "export REQUESTS_CA_BUNDLE=<Path to Certificate>/ca-bundle.pem" >> $HOME/.bashrc
      • On Windows, run the following PowerShell command:
      [System.Environment]::SetEnvironmentVariable("REQUESTS_CA_BUNDLE", "<Path to Certificate>\ca-bundle.pem", "Machine")
      Close
    Close

  • Use one of the following methods to configure the custom CA certificate for NPM:

    • Run the following command to set the cafile config option:

      npm config set cafile <Path to Certificate>/ca-bundle.pem

      Ensure that the PEM certificate bundle includes both root and intermediate certificates.

      Close
      • On macOS, run the following Bash command:
      echo "export NODE_EXTRA_CA_CERTS=<Path to Certificate>\bundle.pem" >> $HOME/.bashrc
      • On Windows, run the following PowerShell command:
      [System.Environment]::SetEnvironmentVariable("NODE_EXTRA_CA_CERTS", "C:\<Path to Certificate>\ca-bundle.pem", "Machine")
      Close
    Close

  • On CentOS and a few other Linux-based systems, there is a built-in system command to add self-signed certificates to the trust store.

      1. Copy both root and intermediate certificates as individual files in PEM format into the location, /etc/pki/ca-trust/source/anchors/.
      2. Update the CA store using the following command:
      update-ca-trust
      Close
      1. Copy both root and intermediate certificates as individual files in PEM format into the location, /usr/local/share/ca-certificates/.
      2. Update the CA store using the following command:
      sudo chmod 644 <root certificate file path>
      Close
      1. Copy both root and intermediate certificates as individual files in PEM format into the location, /etc/pki/trust/anchors/.
      2. Update the CA store using the following command:
      sudo update-ca-certificates
      Close
    Close

  • To import a custom certificate for Java:

    1. Download the certificate bundle in DER format to the JAVA_HOME/bin directory using the keytool utility.

    To convert a .crt certificate to DER format, use the command, openssl x509 -in <filename.pem> -inform pem -out <filename.der> -outform der

    1. Run the following keytool command for your certificate:
    keytool  -import  -trustcacerts -alias <certAlias> -file <certFile> -keystore <trustStoreFile>

    For example:

    keytool  -import  -trustcacerts -alias zscalerrootca -file zscalerrootca.der -keystore $JAVA_HOME/jre/lib/security/cacerts
    1. You might be prompted to enter a password if you are running the tool for the first time.
    2. Enter yes to confirm.
    3. Verify if the certificate is imported successfully using the following keytool command:
    keytool -list -v -keystore cacerts

    To learn more about keytool commands, refer to the Oracle documentation.

    Close

  • IntelliJ IDEA provides its own storage for trusted certificates for Windows, Linux, and Mac platforms.

    1. Download the custom certificates (intermediate and root) in PEM format.
    2. Add the certificate to the trust store based on the instructions provided in the IntelliJ IDEA documentation.
    Close

  • To add the custom certificate for Git to the trust store on the following platforms:

      1. Create or download the certificate bundle in PEM format.
      2. Create a new directory and move the bundle to the new location using the following commands:
      mkdir ~/ca_certs
    mv ~/Downloads/custom-ca-bundle.pem ~/ca_certs
      1. Add the certificate to the trust store using the following Git command:
      git config --global http.sslcainfo ~/ca_certs/custom-ca-bundle.pem
      Close
      1. Create or download the certificate bundle in PEM format.
      2. Create a new directory and move the bundle to the C drive using the following commands:
      mv $env:HOMEPATH\Downloads\custom-ca-bundle.pem $env:APPDATA
    git config --global http.sslcainfo $env:APPDATA\custom-ca-bundle.pem
      Close
    Close

  • To add the custom certificate for Ruby to the trust store on the following platforms:

    • Run the following Bash command to set the SSL cert file environment variable:

      echo "export SSL_CERT_FILE=<Path to Certificate>/ZscalerRootCA.pem" >> $HOME/.bashrcrun
      Close
      1. Create or download the certificate bundle in PEM format.
      2. Run the following PowerShell command to move the bundle to the C drive:
      [System.Environment]::SetEnvironmentVariable("SSL_CERT_FILE", 
    "C:\<Path to Certificate>\ZscalerRootCA.pem", "Machine")
      Close
    Close

  • Use one of the following methods to configure the custom CA certificate for Curl:

    Close

  • To add the custom CA certificate for Wget, run the following command to set the ca_certificate environment variable:

    echo "ca_certificate=<Path to Certificate>/ZscalerRootCA.pem" >> $HOME/.wgetrc
    Close

  • On Windows, macOS, and Linux, Docker will use the OpenSSL CA Trust for its connections to allow it to download packages as you instantiate them in your Dockerfile.

    After the Dockerfile is loaded and processed, Docker containers make their connections, which need to trust the Zscaler certificate. Therefore, ensure that your Docker container has the Zscaler certificates installed.

    You can add the custom CA certificate for Docker by using the following three files. In this example, we assume Zscaler is "in path" for the development environment (developers workstation) but "out of path" for the production environment (e.g., AKS/GKS).

    • The environment file (.env) is used to identify if the build is run in a production or development environment.

      Create a docker.env file with the following command:

      BUILD_ENV=production
    OR
    BUILD_ENV=development

      This example sets the variables to be read in the Docker Compose file.

      Close

    • The docker compose file (.yaml) reads the BUILD_ENV variables and passes them to the Dockerfile.

      Create a dockercompse.yaml file with the following command:

      version: '3.1'
    services:
    dotnetconf19:
    image: dockersamples/dotnetconf:19
    build:
    context: .
    args:
    - BUILD_ENV=${BUILD_ENV:-production}
    - CERT_FILE=${CERT_FILE:-/etc/ssl/certs/ca-certificates.crt}
    environment:
    - BUILD_ENV=${BUILD_ENV:-production}
    - CERT_FILE=${CERT_FILE:-/etc/ssl/certs/ca-certificates.crt}

      This example reads the docker.env file created previously. If no variable is set for BUILD_ENV, it is assumed to be production. If no variable is set for CERT_FILE, the default is set to be the local certificate store.

      Close

    • The docker file installs the certificate for the development environments as it requires all traffic to be inspected. The certificate for the production environment can be installed in Kubernetes and be directed to the internet where inspection is not required or moved to a non-Zscaler customer where the certificate is not installed.

      Create a Dockerfile with the following commands:

      FROM mcr.microsoft.com/dotnet/core/sdk:3.0.100-preview9 AS builder
    #No need to install certificates here - no Internet requests made
    WORKDIR /src
    COPY src/WebRequests.csproj .
    RUN dotnet restore
    COPY src/ .
    RUN dotnet publish -c Release -o /out WebRequests.csproj
    FROM mcr.microsoft.com/dotnet/core/runtime:3.0.0-preview9
    #Image runs internet requests over HTTPS - Install Certs if dev environment
    #Set ARG BUILD_ENV default = production
    ARG BUILD_ENV=production
    #Assign the $BUILD_ENV the BUILD_ENV ENV so that it can be accessed
    ENV BUILD_ENV $BUILD_ENV
    #Add the CA Certificate to the container
    ADD src/ZscalerRootCertificate-2048-SHA256.crt /tmp/ZscalerRootCertificate-2048-SHA256.crt
    #Use BUILD_ENV variable within the container to copy the CA certificate into the certificate directory and update
    RUN if [ "$BUILD_ENV" = "production" ] ; then echo "production env"; else echo
    "non-production env: BUILD_ENV"; CERT_DIR=(openssl version -d | cut -f2 -d \")/certs ;
    cp /tmp/ZscalerRootCertificate-2048-SHA256.crt $CERT_DIR ; update-ca-certificates ;
    fi
    #Continue the build where the HTTPS Connections are made
    WORKDIR /app
    ENTRYPOINT ["dotnet", "WebRequests.dll"]
    ENV DotNetBot:Message="docker4theEdge!"
    COPY --from=builder /out/ .

      The Docker file reads the environment variables and copies the Zscaler root certificate from the source folder. If the build is in a production environment, then it proceeds as usual. If the build is in a development environment, then the location of OpenSSL is determined, and the Zscalerroot certificate is added to the trusted root certificate store and updated.

      Close
    Close

  • When Android Studio starts, it may detect and report an untrusted certificate error. You can accept to trust the incoming certificate, and add it to the local keystore.

    If you are using a Gradle plugin, which is a Java app that runs from the JRE embedded in Studio, you need to add the certificates into the JRE local keystore.

    To add the certificate to the JRE local keystore:

    1. Download the certificate bundle in CER format to the JAVA_HOME/bin directory using the keytool utility.
    2. Run the following keytool command for your certificate:
    • On macOS:
    keytool -import -trustcacerts -file <Path to Certificate>/ca-abc_111.cer -alias custom-Root-CA -keystore /Applications/Android\ Studio.app/Contents/jbr/Contents/Home/lib/security/cacerts 
    keytool -import -trustcacerts -file <Path to Certificate>/ca-abc_222.cer -alias custom-Intermediate-CA -keystore /Applications/Android\ Studio.app/Contents/jbr/Contents/Home/lib/security/cacerts
    • On Windows:
    cd "\Program Files\Android\Android Studio\jre\bin" 
    keytool -import -trustcacerts -file <Path to Certificate>/ca-abc_111.cer -alias custom-Root-CA -keystore ..\jre\lib\security\cacerts 
    keytool -import -trustcacerts -file <Path to Certificate>/ca-abc_222.cer -alias custom-Intermediate-CA -keystore ..\jre\lib\security\cacerts

    Ensure that you specify the full path to the Android Studio Keystore.

    1. You may be prompted to enter a password if you are running the tool for the first time.
    2. Enter yes to confirm.
    3. Verify if the certificate is imported successfully using the following keytool command:
    keytool -list -v -cacerts

    To learn more about keytool commands, refer to the Oracle documentation.

    Close
  • Close

  • To import the Zscaler root certificate into the certificate store of Microsoft Edge browser:

    1. Open the Microsoft Edge browser, click the menu icon on the upper-right corner, and go to Settings.

    1. Go to Privacy, search, and services, then scroll down to the Security section and click Manage certificates. Alternatively, use the search field to go to the Manage certificates option.

    1. From the Trusted Root Certification Authorities tab and click Import.

    1. When the Certificate Import Wizard appears, click Next.
    2. Browse and select the Zscaler root certificate from your local directory and then click Next.

    1. Place the Zscaler root certificate in the Trusted Root Certification Authorities store and click Next.

    1. Click Finish to complete the import process. The Zscaler root certificate is successfully imported to the Microsoft Edge browser.
    Close
Related Articles
About Secure Sockets Layer (SSL)About SSL InspectionSupported Cipher Suites in SSL InspectionSafeguarding SSL Keys and Data Collected During SSL InspectionAdding Custom Certificate to an Application Specific Trust StoreAbout SSL Inspection PolicyConfiguring SSL Inspection PolicyAbout Intermediate CA CertificatesChoosing the CA Certificate for SSL InspectionSigning a CSR Using the Active Directory Certificate ServicesDeploying SSL InspectionConfiguring Software Protection Intermediate CA CertificateConfiguring Cloud HSM Protection Intermediate CA CertificateDeployment Scenarios for SSL InspectionCertificate Pinning and SSL InspectionBest Practices for Testing and Rolling Out SSL Inspection