Using VCert Playbooks

An example based upon documentation here

This code has been tested on x86 Ubuntu

Prerequisites

You must have a tenant in TLSPC with at least one active VSatellite instance to allow for service-generated CSRs

Check version

Check here for latest vcert downloads. Ensure you're running v5.1.1 or later

/usr/local/bin/vcert --version

Set environment variables

export VC_TLSPC_KEY="<>"       # see https://<tenant>.venafi.cloud/platform-settings/user-preferences?key=api-keys
export VC_ZONE_APP="<>"        # e.g. vcert5dot0-test-app
export VC_ZONE_CIT="<>"        # e.g. vcert5dot0-test-cit
export VC_POLICY_CA="<>"       # e.g. BUILTIN\\\\Built-In CA\\\\Default Product
export VC_POLICY_USERS="<>"    # e.g. Ecosystem Architects
export VC_POLICY_DOMAIN="<>"   # e.g. example.com
export VC_POLICY_MAX_DAYS="<>" # e.g. 90
export VC_CERT_CN="<>"         # e.g. www.example.com
export VC_MID_PATH="<>"        # e.g. /home/ubuntu/     - change to suit your OS/app
export VC_KEY_PASSPHRASE="<>"  # e.g. newPassphrase987%
export VC_CERT_RENEW_DAYS="<>" # e.g. 89                - (90-89=1) this means expire DAILY, great for TESTING!

Some escape characters were needed there (for example, see VC_POLICY_CA) so check that you've got what you expected.

export | grep VC_

Create your policy document

Note: the term policy is a VCert specific construct that represents the pairing of a Certificate Issuing Template and an Application in TLSPC. The term zone, which takes the form APP\CIT, is used as an identifier for a policy. If you ever need reminding of the struture of a policy document, use the vcert getpolicy command against an existing zone.

cat << EOF | envsubst > policy.json
{
  "users": [
    "${VC_POLICY_USERS}"
  ],
  "policy": {
    "domains": [
      "${VC_POLICY_DOMAIN}"
    ],
    "wildcardAllowed": false,
    "maxValidDays": ${VC_POLICY_MAX_DAYS},
    "certificateAuthority": "${VC_POLICY_CA}",
    "subject": {
      "orgs": [
        ".*"
      ],
      "orgUnits": [
        ".*"
      ],
      "localities": [
        ".*"
      ],
      "states": [
        ".*"
      ],
      "countries": [
        ".*"
      ]
    },
    "keyPair": {
      "keyTypes": [
        "RSA"
      ],
      "rsaKeySizes": [
        2048,
        3072,
        4096
      ],
      "serviceGenerated": true,
      "reuseAllowed": false
    },
    "subjectAltNames": {
      "dnsAllowed": true
    }
  }
}
EOF

Create your policy in TLSPC

/usr/local/bin/vcert setpolicy \
  --apiKey "${VC_TLSPC_KEY}" \
  --zone "${VC_ZONE_APP}\\${VC_ZONE_CIT}" \
  --file policy.json

Review your policy document

/usr/local/bin/vcert getpolicy \
  --apiKey "${VC_TLSPC_KEY}" \
  --zone "${VC_ZONE_APP}\\${VC_ZONE_CIT}"

Also, check the following URLS:

https://<tenant>.venafi.cloud/certificate-issuance/issuing-templates
https://<tenant>.venafi.cloud/applications

Create a VCert playbook

Playbooks are a new feature which debuted in VCert v5.x Check here to learn more.

You should be aware, given that playbooks support the handlebar notation, you could use something like apiKey: '{{ Env "VC_TLSPC_KEY" }} to protect sensitive information, but this would then need to be made available as a "root-visible" env var in order to successfully run as a cron job.

cat <<EOF | envsubst > /home/ubuntu/playbook.yaml
config:
  connection:
    platform: vaas
    credentials:
      apiKey: '${VC_TLSPC_KEY}'
certificateTasks:
  - name: Task001
    renewBefore: ${VC_CERT_RENEW_DAYS}d
    request:
      csr: service
      ############
      # necessary? - log says "csr option is 'service'. Generating random password for certificate request"
      keyPassword: "${VC_KEY_PASSPHRASE}"
      ############
      subject:
        commonName: '${VC_CERT_CN}'
        country: US
        locality: Salt Lake City
        state: Utah
        organization: Venafi Inc
        orgUnits:
          - engineering
          - marketing
      zone: "${VC_ZONE_APP}\\\\${VC_ZONE_CIT}"
    installations:
      - format: PEM
        file: "${VC_MID_PATH}cert.cer"
        chainFile: "${VC_MID_PATH}chain.cer"
        keyFile: "${VC_MID_PATH}key.pem"
        afterInstallAction: "echo Success!!!"
EOF

Test the playbook from the command line

Set the command (used again later)

CMD="/usr/local/bin/vcert run -f /home/ubuntu/playbook.yaml"

Test the command

${CMD}

Schedule the vcert playbook command to run periodically

CRON_SPEC="* * * * *"    # once per minute, great for TESTING
# CRON_SPEC="0 5 * * *"  # 5am daily

(crontab -l 2>/dev/null; echo "${CRON_SPEC} /usr/bin/sudo ${CMD} 2>&1 | logger -t vcert") | crontab -

Observe the cron table

crontab -l

alternatively ...

sudo cat /var/spool/cron/crontabs/ubuntu

Observe the system log

tail -f /var/log/syslog | grep vcert

amcginlay/vcert-playbooks.md