Harness CI Plugin

Keeper Secrets Manager integration into Harness CI for dynamic secrets retrieval.

Features

• Retrieve secrets from the Keeper Vault within the Harness CI pipeline

• Set secret credentials as build arguments in Harness CI pipeline

• Copy secure files from the Keeper Vault

For a complete list of Keeper Secrets Manager features see the Overview

Prerequisites

Keeper Secrets Manager Requirements

Requirement	Description
KSM Access	Active Keeper Secrets Manager subscription (Quick Start Guide)
Add-on Enabled	Secrets Manager add-on enabled for your Keeper account
Role Membership	Member of a Role with Secrets Manager enforcement policy enabled
KSM Application	A configured Keeper Secrets Manager Application with secrets shared to it
KSM Configuration	An initialized configuration (Base64 token or One-Time Access Token or JSON config file)

Harness CI Requirements

• Active Harness account

• A pipeline setup of Harness CI

• Understanding of Harness CI secrets management

Configuration Types

The plugin supports three authentication methods. Choose the one that fits your security requirements:

Type	Harness Secret Type	Use Case
One-Time Access Token (OTAT)	Text Secret	Single-use, highest security
Base64 Token	Text Secret	Reusable, standard security
JSON Config File	File Secret	Full configuration, reusable

Setup Guide

Step 1: Configure Keeper Vault

1. Create a Shared Folder in Keeper Vault

2. Create records containing your secrets inside the shared folder

3. Create a Secrets Manager Application

4. Generate your preferred credential type:

   • One-Time Access Token (OTAT)

   • Base64 Token or JSON Config

Step 2: Create Harness CI Secret

Navigate to: Project → Project Setup → Secrets → + New Secret

Option A: One-Time Access Token (Text Secret)

1. Click + New Secret → Text

2. Configure:

   • Secret Name: keeper_otat_secret

   • Secret Value: Paste the token (e.g., US:xxxxx...)

   • Scope: Project (recommended)

3. Click Save

Note: One-time access tokens are single-use. Generate a new token for each pipeline run.

Option B: Base64 Token (Text Secret)

1. Click + New Secret → Text

2. Configure:

   • Secret Name: keeper_base64_secret

   • Secret Value: Paste the base64-encoded token

   • Scope: Project (recommended)

3. Click Save

Note: Ensure no line breaks or whitespace in the base64 string.

Option C: JSON Config File (File Secret)

1. Click + New Secret → File

2. Configure:

   • Secret Name: keeper_ksm_config_file

   • Upload File: Select your KSM JSON config file

   • Scope: Project (recommended)

3. Click Save

Expected JSON structure:

{
  "hostname": "keepersecurity.com",
  "clientId": "your-client-id",
  "privateKey": "your-private-key"
}

Step 3: Reference in Pipeline

Use the following syntax to reference your secret:

envVariables:
  KSM_CONFIG: <+secrets.getValue("your_secret_identifier_name")>

Quick Start

Pipeline Example

pipeline:
  name: harness_keeper_plugin
  identifier: harness_keeper_plugin
  projectIdentifier: default_project
  orgIdentifier: default
  stages:
    - stage:
        name: HkpCI
        identifier: HkpCI
        type: CI
        spec:
          cloneCodebase: false
          platform:
            os: Linux
            arch: Amd64
          runtime:
            type: Cloud
            spec: {}
          execution:
            steps:
              - step:
                  type: Plugin
                  name: Fetch_Keeper_Secrets
                  identifier: Fetch_Keeper_Secrets
                  spec:
                    image: dhborse/keeper-harness-plugin
                    settings:
                      secrets: |
                        RECORD_UID/field/password > PASSWORD
                        RECORD_UID/field/login > USERNAME
                    envVariables:
                      KSM_CONFIG: <+secrets.getValue("keeper_base64_secret")>
              - step:
                  type: Run
                  name: Use_Secrets
                  identifier: Use_Secrets
                  spec:
                    image: alpine:3.20
                    shell: Sh
                    command: |
                      if [ -f /harness/secrets/USERNAME ] && [ -f /harness/secrets/PASSWORD ]; then
                        USERNAME=$(cat /harness/secrets/USERNAME)
                        PASSWORD=$(cat /harness/secrets/PASSWORD)
                        echo "Username: $USERNAME"
                        echo "Password retrieved successfully"
                      else
                        echo "Error: Secret files not found"
                        exit 1
                      fi

Important: Replace RECORD_UID with the actual Record UID from your Keeper Vault.

Once the pipeline execution end then we will be able to see secrets printed in Print secrets step logs.

Secrets Configuration

Keeper Notation Syntax

The secrets input uses Keeper Notation to specify which secrets to retrieve:

settings:
  secrets: |
    RECORD_UID/field/password > PASSWORD
    RECORD_UID/field/login > USERNAME
    RECORD_UID/custom_field/apiKey > API_KEY
    RECORD_UID/file/certificate.crt > CERT_FILE

Notation Format

<record_uid>/<selector>/<field_name> > <destination_name>

Component	Description
record_uid	The unique identifier of the Keeper record
selector	Type of data: field, custom_field, or file
field_name	Name of the field or file to retrieve
destination_name	Output filename in /harness/secrets/

Selector Types

Selector	Description	Output Location
field	Standard record fields (login, password, etc.)	/harness/secrets/<destination>
custom_field	Custom fields defined in the record	/harness/secrets/<destination>
file	File attachments	/harness/secrets/<destination>

Examples

secrets: |
  # Standard fields
  abc123/field/password > DB_PASSWORD
  abc123/field/login > DB_USERNAME
  
  # Custom fields
  xyz789/custom_field/apiKey > API_KEY
  xyz789/custom_field/endpoint > API_ENDPOINT
  
  # File attachments
  def456/file/server.crt > SERVER_CERT
  def456/file/server.key > SERVER_KEY

Tip: For complex values (arrays, key-value pairs), refer to the Keeper Notation - Predicates documentation.

Local Docker Runner Configuration

When using runtime: type: docker (local runner) instead of Harness Cloud, you must configure Shared Paths to share data between pipeline on local:

spec:
  cloneCodebase: false
  platform:
    os: Linux
    arch: Amd64
  runtime:
    type: docker
    spec: {}
  sharedPaths:
    - /harness
  execution:
    steps:
      # ... your steps

Why? On Harness Cloud, /harness is automatically shared. On local Docker, you must explicitly configure sharedPaths.

Security Best Practices

Practice	Description
Use One-Time Access Tokens	Generate fresh tokens for each pipeline run when possible
Clean Up Secret Files	Delete secret files after use in pipeline steps
Appropriate Scope	Use project-level scope unless broader access is required
Limit Access	Restrict who can edit pipelines (editors can read secrets)

Secret Masking - Hiding Secrets from Logs

Harness CI automatically masks secrets in logs when printed to console. However:

• This only obscures output logs

• Pipeline editors can potentially extract secrets

• Always follow the principle of least privilege

Troubleshooting

Common Issues

Issue	Cause	Solution
KSM config is required	Secret not found or expression incorrect	Verify secret name matches exactly (case-sensitive)
Missing required fields	JSON config incomplete	Ensure JSON contains hostname, clientId, privateKey
Expression not resolved	Secret scope mismatch	Ensure secret scope matches pipeline scope
Token already used	One-time tokens are single-use	Generate a new OTAT for each run

Issue: Pipeline Works on Cloud but Fails Locally

Symptoms: Fetch_Keeper_Secrets succeeds but next step fails reading /harness/secrets/

Causes & Solutions:

1. Secret name mismatch

   • Plugin writes: > USERNAME and > PASSWORD

   • Run step must check: /harness/secrets/USERNAME and /harness/secrets/PASSWORD

2. Workspace not shared

   • Add sharedPaths: /harness to your stage spec (see Local Docker Runner Configuration)

Debugging: Verify Plugin Output

Add a debug step after the plugin:

- step:
    type: Run
    name: Debug_Secrets
    spec:
      image: alpine:3.20
      shell: Sh
      command: |
        echo "Contents of /harness/secrets:"
        ls -la /harness/secrets/ || echo "Directory not found"

If no files appear, check:

• Plugin configuration (secret names)

• Workspace sharing (for local runner)

• KSM_CONFIG environment variable