Integrate external secret providers

Use external secret management actions to securely fetch sensitive information such as passwords and API keys from enterprise secret management systems within your CloudBees Unify workflows.

Fetched secret output is automatically masked in CloudBees Unify and cannot be logged or accessed by background processes, ensuring secure handling in downstream workflow steps.

Prerequisites

Before you begin, ensure you have:

A CloudBees Unify workflow configured in your repository.
Access to an external secret management system.
Appropriate credentials and permissions configured in the secret management system.
Understanding of your organization’s secret management policies.

CyberArk Conjur integration

Use the CyberArk Conjur action to fetch secrets from CyberArk Conjur, an enterprise secret management platform.

If you want to use the same secrets in another job, you must call the Conjur action again in that job. Secret values are job-scoped and do not persist across jobs.

Action parameters

Table 1. Input details
Input name	Data type	Required?	Description
`login`	String	Yes	The Conjur workload identity.
`api-key`	String	Yes	The API key for generating a short-lived access token for authentication.
`url`	String	Yes	The Conjur server URL.
`variables`	String	Yes	A comma-separated list of the full paths of each secret to be fetched.

Action outputs

Table 2. Output details
Output name	Data type	Description
`conjur_output`	JSON string	The value of each fetched secret, in JSON format.

Any forward slashes (/) in the variables input are replaced with underscores () by CloudBees Unify in the output, so to refer to full paths, you must replace / with .

Basic usage

The following example shows basic secret fetching from CyberArk Conjur:

    steps:
      - name: Fetch secrets from Conjur
        uses: cloudbees-io/cyberark-conjur-fetch-secrets@v1
        with:
          login: ${{ vars.YOUR_CONJUR_WORKLOAD_ID }}
          api-key: ${{ secrets.YOUR_CONJUR_API_KEY }}
          url: ${{ vars.YOUR_CONJUR_URL }}
          variables: full/path/to/secret-1,full/path/to/secret-2▼

Advanced usage with secret outputs

Access the conjur_output values in downstream steps using the outputs context.

Use the conjur_output output for a single secret value as follows, where <action_step_ID> is the action step ID, and <full_path_no_slashes> is the full path of the secret, with any / replaced with _:

${{ fromJSON(steps.<action_step_ID>.outputs.conjur_output).<full_path_no_slashes> }}▼

The following example demonstrates fetching secrets and using them in downstream steps:

Each echo command outputs * in place of the secret, because the action automatically masks all fetched secrets.

jobs:
  use-conjur-secrets:
    steps:
      - name: Fetch secrets from Conjur
        id: fetch-my-secrets
        uses: cloudbees-io/cyberark-conjur-fetch-secrets@v1
        with:
          login: ${{ vars.YOUR_CONJUR_WORKLOAD_ID }}
          api-key: ${{ secrets.YOUR_CONJUR_API_KEY }}
          url: ${{ vars.YOUR_CONJUR_URL }}
          variables: my-org/my-directory/secret1,my-org/my-directory/secret2

      - name: Use fetched secrets in application deployment
        uses: docker://alpine:latest
        shell: sh
        run: |
          # Use secret1 for database connection
          DATABASE_PASSWORD="${{ fromJSON(steps.fetch-my-secrets.outputs.conjur_output).my-org_my-directory_secret1 }}"

          # Use secret2 for API authentication
          API_KEY="${{ fromJSON(steps.fetch-my-secrets.outputs.conjur_output).my-org_my-directory_secret2 }}"

          # Deploy application with secrets (values are masked in logs)
          ./deploy.sh --db-password="$DATABASE_PASSWORD" --api-key="$API_KEY"▼

Security considerations

When integrating external secret providers:

Secret masking: All fetched secrets are automatically masked in CloudBees Unify logs and cannot be accessed by background processes.
Job scope: Secret values are scoped to individual jobs. If you need the same secrets in multiple jobs, fetch them separately in each job.
Access control: Ensure your secret management system has appropriate access controls and audit trails configured.
Rotation: Consider secret rotation policies and ensure your workflows can handle updated secret values.
Network security: Verify secure network connectivity between CloudBees Unify and your secret management system.

Troubleshooting

If secret fetching is not working correctly:

Authentication failures: Verify the login, api-key, and url parameters are correct and accessible.
Secret path errors: Check that secret paths in the variables parameter exist and are accessible with your credentials.
Network connectivity: Ensure CloudBees Unify can reach your Conjur server URL over the network.
Permission issues: Verify your Conjur workload identity has read access to the specified secret paths.
Output path format: Remember that forward slashes (/) in secret paths are replaced with underscores (_) in the output JSON.