Skip to main content

Add custom certificates to a pipeline

Some organizations prefer to use custom SSL certificates instead of certificates generated by a public Certificate Authority (CA). If your organization uses internal certificates, you need to set up Harness to use these certificates.

Harness supports three workflows for using custom certificates. You can add your certs to the delegate, to individual pipelines, or to the container images you use to run your scans.

When to add custom certificates to a pipeline for STO

Harness STO supports three workflows for running scans with custom certificates. This workflow is recommended if either of the following are true:

  • You're using any delegate type other than Kubernetes or Docker, such as a Harness Cloud delegate.

  • You cannot access or customize your delegate directly.

You can also use this workflow if the external scanner requires additional files, such as auth script or license files, to run scans. For example, ZAP scans might require context files as noted below.

Important notes for adding custom certificates to a pipeline for STO

  • You must have root access to perform the workflow documented below.

  • Make sure that your certificates meet all requirements of the external scan tool. Your certificates must be valid, unexpired, and have a complete trust chain.

  • STO supports certificates in PEM and Distinguished Encoding Rules (DER) format.

  • Harness STO does not support certificate bundles. Each certificate should be specified in its own file. If you have a bundle that you want to use with an external scanner, Harness recommends that you split the bundle into individual files.

  • Store each certificate file as a Harness file secret. You can also use third-party managers such as HashiCorp Vault, Azure Key Vault, and AWS Secrets Manager. For more information, go to Harness Secrets Manager Overview.

  • You must include all required files in /shared/customer_artifacts/ or a related subfolder, as described below. You can include any number of certificates or other files in or under this folder.

  • Save each SSL certificate file to /shared/customer_artifacts/certificates/<certificate_name>.

Workflow for adding custom certificates to a pipeline for STO

This workflow applies to all supported build infrastructures. It also applies to STO on SaaS, as well as Harness Self-Managed Platform.

  1. For each artifact that contains sensitive information, such as an SSL certificate, create a Harness secret.

  2. Go to the pipeline where you want to add the artifact.

  3. In the stage where that will use the artifact, go to Overview > Shared Paths and create a folder under /shared such as /shared/customer_artifacts.

  4. Add a Run step to the stage that adds the artifacts to the shared folder. This step needs to run before the scanner step that uses the artifact.

Example workflow for adding custom certificates to a pipeline for STO

This example shows how to include a PEM file in a pipeline that runs a scan using a Security step. This workflow assumes that you have a valid PEM stored as a Harness File Secret.

  1. In your Harness pipeline, go to the Overview tab of the Security stage. Under Shared Paths, enter the following shared path:


    This is the default certificate location for Harness pipelines. You can copy any number of certificates to this folder.

  2. Add a Run step that copies your PEM file to the certificates folder. Here's some example code that does this:

    set -e
    touch /shared/customer_artifacts/certificates/certificate
    printf "%s" "$NEWCERT" > /shared/customer_artifacts/certificates/certificate
  3. Set up the remaining downstream steps in your pipeline. When the pipeline runs a SonarQube scan that requires a PEM, it looks in /shared/customer_artifacts/certificates and proceeds if it finds a valid certificate.

YAML pipeline example for adding custom certificates to a pipeline for STO

The following illustrates an end-to-end pipeline that copies a PEM certificate to the default location, builds an image, and then scans the image using SonarQube (authorized using the certificate).

YAML pipeline example
allowStageExecutions: false
projectIdentifier: STO
orgIdentifier: default
identifier: jsmith_cloud_sq_mvn_with_pem_files
name: "jsmith cloud - sq mvn with pem files " tags: {}
build: <+input>
- stage:
name: build
identifier: build
type: SecurityTests
cloneCodebase: true
- /var/run
- /shared/customer_artifacts
- identifier: dind
name: dind
type: Service
image: docker:dind
privileged: true
- dockerd
memory: 4Gi
cpu: 1000m
- step:
type: Run
name: export path
identifier: export_path
image: alpine
shell: Sh
command: |-
export harness_path
- name: harness_path
- step:
type: Run
name: addcerts
identifier: addcert
image: alpine
shell: Sh
command: |-
set -e
mkdir -p -v /shared/customer_artifacts/certificates

touch /shared/customer_artifacts/certificates/certificate1
printf "%s" "$NEWCERT" > /shared/customer_artifacts/certificates/certificate1

# touch /shared/customer_artifacts/certificates/certificate2
# printf "%s" "$NEWDUMMYCERT" > /shared/customer_artifacts/certificates/certificate2

ls -l /shared/customer_artifacts/certificates
cat /shared/customer_artifacts/certificates/certificate | base64
NEWCERT: <+secrets.getValue("sonarqube_self_signed_cert")>
NEWDUMMYCERT: <+secrets.getValue("my-dummy-pem")>
- step:
type: Run
name: build
identifier: build
image: maven:3.3-alpine
shell: Sh
command: |
mvn clean package
- step:
type: Security
name: sonar
identifier: sonar
privileged: true
policy_type: orchestratedScan
scan_type: repository
product_name: sonarqube
product_config_name: sonarqube-agent
repository_project: dvja
repository_branch: <+codebase.branch>
product_access_token: MY_PROD_TOKEN
product_project_key: dvja
verify_ssl: true
bypass_ssl_check: true
workspace: <>/target
imagePullPolicy: Always
memory: 2Gi
cpu: 1000m
description: sonar
failureStrategies: []
os: Linux
arch: Amd64
type: Cloud
spec: {}
- name: runner_tag
type: String
value: dev