CyberArk Secrets Manager Octopus Deploy Step Template

This repository provides two step templates that allow a workload running in Octopus Deploy or Octopus Server to authenticate with CyberArk Secrets Manager and retrieve secrets, making them available as sensitive output variables in a deployment process.

Step Template	Authenticator	Description
CyberArk Secrets Manager - Retrieve Secrets (JWT)	authn-jwt	Authenticates using a JWT issued by Octopus's Generic OIDC Account. Compatible with Conjur OSS, Secrets Manager Self-Hosted, and Secrets Manager SaaS.
CyberArk Secrets Manager - Retrieve Secrets (Certificate)	authn-cert	Authenticates using an X.509 client certificate via mutual TLS (mTLS). Requires Secrets Manager Self-Hosted (Enterprise) or Secrets Manager SaaS with Edge.

Certification Level

This repo is a Certified level project. It's been reviewed by CyberArk to verify that it will securely work with CyberArk Enterprise as documented. In addition, CyberArk offers Enterprise-level support for these features. For more detailed information on our certification levels, see our community guidelines.

Requirements

• Octopus Deploy or Octopus Server 2025.1 and later
• For JWT authentication: Conjur OSS; CyberArk Secrets Manager, Self-Hosted; or CyberArk Secrets Manager, SaaS
• For Certificate authentication: CyberArk Secrets Manager, Self-Hosted (Enterprise) or CyberArk Secrets Manager, SaaS (with Edge)

---

JWT Authentication (authn-jwt)

This step template authenticates workloads running in Octopus Deploy/Octopus Server by leveraging the Generic OIDC Account feature. This exposes a JWKS endpoint and makes a signed JWT credential available to individual workloads when the account is added to the deployment process as a variable.

NOTE: If using Octopus Server, there may be additional configuration required to expose the JWKS endpoint. Alternatively, you can use the public-keys authenticator variable if Secrets Manager cannot establish connectivity to this endpoint.

Configuration Steps (Octopus)

1. Create the Generic OIDC Account
   • Navigate to: Manage > Accounts > Add Account > Generic OIDC
   • Configure the account (example values provided below)
     • Name: Secrets Manager Account
     • Description: Issues tokens for workload authentication to Secrets Manager
     • Subject Claim: space, project, environment (default, recommended to include at least these three identifiers)
     • Audience: conjur
   • Save the account
2. Add the Generic OIDC Account to a deployment process as a variable
   • Navigate to: Projects > Your Project > Project variables
   • Add a new variable referencing the account created in step 1: Enter Value > Change Type > Generic OIDC Account > Secrets Manager Account
   • Save the project variables

Example JWT

At runtime, the Octopus server will issue a JWT to represent the workload based on the configuration above. Make note of the expected aud, iss, and sub values in order to configure the JWT authenticator and host identity in Secrets Manager. If using the example values from above it may look like:

{
  "aud": "conjur",
  "iss": "https://mycompany.octopus.app",
  "exp": 1745511648,
  "iat": 1745508048,
  "nbf": 1745508048,
  "jti": "4d32d71c71c54f2f8d6cfab506b73981",
  "sub": "space:default:project:get-secrets:environment:development"
}

NOTE: By default, Octopus includes space, project, and environment in the JWT subject, as in the example token above. It is recommended to include at least these three fields to ensure each Octopus workload will have a unique subject identifier. This allows Secrets Manager to enforce fine-grained access control based on host identity.

Authenticator Setup

Example authenticator policy:

- !policy
  id: conjur/authn-jwt/octopus
  body:
    - !webservice

    # Authenticator variables
    - !variable jwks-uri
    - !variable issuer
    - !variable token-app-property
    - !variable identity-path

    # Group of applications that can authenticate using this JWT Authenticator
    - !group authenticatable
    - !permit
      role: !group authenticatable
      privilege: [ read, authenticate ]
      resource: !webservice

Example host identity policy:

- !policy
  id: octopus-apps
  body:
    - !group

    - &hosts
      - !host
          id: space:default:project:get-secrets:environment:development # Replace with the expected `sub` value from the JWT
          annotations:
            authn-jwt/octopus/sub: space:default:project:get-secrets:environment:development
      # Add additional hosts as needed

    - !grant
        role: !group
        members: *hosts

# Allow octopus-apps group to use the authenticator
- !grant
  role: !group authn-jwt/octopus/authenticatable
  members: !group octopus-apps

Input parameters

Field	Variable Name	Input Type & Default	Required	Example Value	Description
Secrets Manager URL	CyberArk.SecretsManager.Url	Single-line text box	Yes	https://conjur.mycompany.com	Base URL for the Secrets Manager server (add /api for CyberArk Secrets Manager, SaaS)
Authenticator Service ID	CyberArk.SecretsManager.ServiceId	Single-line text box (default=octopus)	No	octopus	Service ID of the JWT authenticator instance
Secrets Manager Account	CyberArk.SecretsManager.Account	Single-line text box (default=conjur)	No	conjur	Secrets Manager account specified during configuration (only for OSS/Enterprise)
OIDC Account	CyberArk.SecretsManager.Jwt	Generic OIDC Account	Yes	#{token-account}	Octopus variable referencing the configured Generic OIDC Account
Secrets Manager Variables	CyberArk.SecretsManager.Variables	Multi-line text box	Yes	secrets/db/username | db_username secrets/db/host	Multiline input of Secrets Manager variable IDs and optional output variable names. If none is provided, the Secrets Manager variable ID will be used as output.
Trusted Server Certificate	CyberArk.SecretsManager.Certificate	Multi-line text box	No	-----BEGIN CERTIFICATE----- MIIDdTCC... -----END CERTIFICATE-----	Provide a custom server certificate to trust TLS connection with Secrets Manager (e.g., self-signed certs).
Print Output Variable Names	CyberArk.SecretsManager.PrintVariableNames	Checkbox (default=false)	No	False	Whether to log the output variable names after execution.

Output variables

Sensitive output variables will be populated based on the Variable IDs and optional output variable names provided during configuration. They can be retrieved in subsequent deployment steps using the following methods:

PowerShell:

$OctopusParameters["Octopus.Action[CyberArk Secrets Manager - Retrieve Secrets (JWT)].Output.custom_output_variable_name"]
$OctopusParameters["Octopus.Action[CyberArk Secrets Manager - Retrieve Secrets (JWT)].Output.data/secrets/db/username"]

Bash:

$(get_octopusvariable "Octopus.Action[CyberArk Secrets Manager - Retrieve Secrets (JWT)].Output.custom_output_variable_name")
$(get_octopusvariable "Octopus.Action[CyberArk Secrets Manager - Retrieve Secrets (JWT)].Output.data/secrets/db/username")

Python:

get_octopusvariable("Octopus.Action[CyberArk Secrets Manager - Retrieve Secrets (JWT)].Output.custom_output_variable_name")
get_octopusvariable("Octopus.Action[CyberArk Secrets Manager - Retrieve Secrets (JWT)].Output.data/secrets/db/username")

---

Certificate Authentication (authn-cert)

This step template authenticates workloads to CyberArk Secrets Manager using an X.509 client certificate via mutual TLS (mTLS). The workload presents its certificate during the TLS handshake; Secrets Manager validates it against the configured CA and issues a short-lived access token used to retrieve secrets.

Note: authn-cert is available in CyberArk Secrets Manager Self-Hosted (Enterprise) and SaaS (with Edge). It is not available in Conjur OSS.

How it works

1. The Octopus step writes the client certificate and private key to temporary files.
2. A POST request is sent to /authn-cert/<service-id>/<account>/<workload-id>/authenticate with mutual TLS.
   • When deployed behind a reverse proxy (e.g., nginx), the proxy terminates TLS and forwards the certificate to Secrets Manager via the X-SSL-Client-Cert header.
3. Secrets Manager validates the certificate's fields (CN, SAN) against the workload's annotations and returns a short-lived access token.
4. The access token is used to batch-retrieve secrets from the Secrets Manager REST API.
5. Temporary files holding the private key are securely deleted.

Authenticator Setup

Step 1: Create the authenticator policy

Load into the conjur/authn-cert policy branch:

- !policy
  id: octopus-cert           # This becomes the <service-id> used in the URL
  body:
    - !webservice

    # CA certificate bundle (PEM) that signed the workload's client certificate
    - !variable ca-cert

    - !group authenticatable
    - !permit
      role: !group authenticatable
      privilege: [ read, authenticate ]
      resource: !webservice

Step 2: Create the workload identity policy

Load into the data policy branch. The annotation value must match a field in the client certificate — use common-name for the CN, san-uri for a URI SAN, or san-dns for a DNS SAN.

- !policy
  id: octopus-cert-apps
  body:
    - !group

    - &hosts
      - !host
          id: my-workload
          annotations:
            # Value must match the CN field in the client certificate
            authn-cert/octopus-cert/common-name: my-workload
            # Alternatively, use san-uri or san-dns annotations

    - !grant
        role: !group
        members: *hosts

# Grant the workload group access to the authenticator
- !grant
  role: !group conjur/authn-cert/octopus-cert/authenticatable
  members: !group data/octopus-cert-apps

Step 3: Configure the CA certificate

Set the CA certificate variable so Secrets Manager can validate incoming client certificates:

conjur variable set \
  -i conjur/authn-cert/octopus-cert/ca-cert \
  -v "$(cat /path/to/ca.crt)"

Step 4: Enable the authenticator

conjur authenticator enable --id authn-cert/octopus-cert

Proxy configuration (nginx)

When running Secrets Manager behind an nginx reverse proxy, configure nginx to request client certificates and forward them to the backend via the X-SSL-Client-Cert header:

server {
    listen 443 ssl;
    ssl_certificate     /etc/nginx/certs/server.crt;
    ssl_certificate_key /etc/nginx/certs/server.key;

    # Request optional client certs; Secrets Manager validates them against the configured CA
    ssl_verify_client optional_no_ca;

    location / {
        proxy_pass http://conjur;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-SSL-Client-Cert $ssl_client_escaped_cert;
    }
}

Input parameters

Field	Variable Name	Input Type & Default	Required	Example Value	Description
Secrets Manager URL	CyberArk.SecretsManager.Url	Single-line text box	Yes	https://conjur.mycompany.com	Base URL for the Secrets Manager instance
Authenticator Service ID	CyberArk.SecretsManager.ServiceId	Single-line text box (default=octopus-cert)	No	octopus-cert	Service ID of the authn-cert authenticator instance
Secrets Manager Account	CyberArk.SecretsManager.Account	Single-line text box (default=conjur)	No	conjur	Secrets Manager account name
Workload ID	CyberArk.SecretsManager.WorkloadId	Single-line text box	Yes	host/data/octopus-cert-apps/my-workload	Full Conjur host identity path of the workload (e.g. host/<policy-branch>/<host-id>)
Client Certificate	CyberArk.SecretsManager.ClientCertificate	Multi-line text box	Yes	-----BEGIN CERTIFICATE----- MIIDdTCC... -----END CERTIFICATE-----	X.509 client certificate in PEM format, signed by the CA configured in the authenticator
Client Certificate Private Key	CyberArk.SecretsManager.ClientCertificateKey	Sensitive	Yes	-----BEGIN PRIVATE KEY----- MIIEvgIB... -----END PRIVATE KEY-----	Private key for the client certificate in PEM format. Store as a sensitive Octopus variable.
Secrets Manager Variables	CyberArk.SecretsManager.Variables	Multi-line text box	Yes	secrets/db/username | db_username secrets/db/host	Multiline input of Secrets Manager variable IDs and optional output variable names.
Trusted Server Certificate	CyberArk.SecretsManager.Certificate	Multi-line text box	No	-----BEGIN CERTIFICATE----- MIIDdTCC... -----END CERTIFICATE-----	CA bundle or server certificate to establish a trusted TLS connection with Secrets Manager.
Print Output Variable Names	CyberArk.SecretsManager.PrintVariableNames	Checkbox (default=false)	No	False	Whether to log the output variable names after execution.

Output variables

Sensitive output variables will be populated based on the Variable IDs and optional output variable names provided during configuration.

PowerShell:

$OctopusParameters["Octopus.Action[CyberArk Secrets Manager - Retrieve Secrets (Certificate)].Output.custom_output_variable_name"]
$OctopusParameters["Octopus.Action[CyberArk Secrets Manager - Retrieve Secrets (Certificate)].Output.data/secrets/db/username"]

Bash:

$(get_octopusvariable "Octopus.Action[CyberArk Secrets Manager - Retrieve Secrets (Certificate)].Output.custom_output_variable_name")
$(get_octopusvariable "Octopus.Action[CyberArk Secrets Manager - Retrieve Secrets (Certificate)].Output.data/secrets/db/username")

Python:

get_octopusvariable("Octopus.Action[CyberArk Secrets Manager - Retrieve Secrets (Certificate)].Output.custom_output_variable_name")
get_octopusvariable("Octopus.Action[CyberArk Secrets Manager - Retrieve Secrets (Certificate)].Output.data/secrets/db/username")

---

Usage

It is recommended to retrieve the step templates from the Community step template library.

Limitations

• If multiple secrets are mapped to the same output variable the last secret will be used, with any previous secrets being overwritten.
• If one secret is inaccessible or doesn't exist, the step will fail and no secrets will be retrieved. This is due to the all-or-nothing nature of the batch retrieval endpoint.
• The Certificate authenticator (authn-cert) requires CyberArk Secrets Manager Self-Hosted (Enterprise) or SaaS (with Edge). It is not supported in Conjur OSS.

Contributing

We welcome contributions of all kinds to this repository. For instructions on how to get started and descriptions of our development workflows, please see our contributing guide.

Support

Please open an issue in this repository for any questions or issues you may have. For general support, please visit the CyberArk Commons forum.

Note: Only the CyberArk GitHub repository is actively monitored. Issues opened on the version mirrored to Octopus Deploy's Step Template Library will not be addressed.

License

Copyright (c) 2025 CyberArk Software Ltd. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an " AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

For the full license text see LICENSE.