github.com/Venafi/vcert/v5@v5.10.2/README-PLAYBOOK.md (about) 1 # VCert Playbook 2 3 VCert Playbook functionality solves the "last mile" problem. VCert has historically done a great job fetching 4 certificates, but getting those certificates installed in the right location usually required custom scripting. The 5 Playbook functionality addresses this use case natively. 6 7 > Throughout this article, we use _TLS Protect Datacenter (TLSPDC)_ to refer to Trust Protection Platform and 8 > _TLS Protect Cloud (TLSPC)_ to refer to Venafi Control Plane. 9 10 ## Key features of VCert playbook 11 12 - **Simplified commands**: With VCert Playbook, you can avoid long command-line arguments. Instead, use playbook YAML 13 files with VCert to enhance automation and maintenance ease. 14 15 - **Flexible certificate placement**: You can designate where to place the certificate and the format in which you 16 want it once received from Venafi. VCert Playbook supports common keystore formats like PEM, JKS, PKCS#12, accommodating 17 folder locations and the Windows CAPI store. 18 19 - **Post-installation actions**: Specify any actions that must be carried out after the certificate is installed. This 20 includes restarting services like Apache or Nginx, or running any other scripts needed once the certificate is in the 21 right location. 22 23 - **Smart certificate renewals**: VCert Playbook checks if a certificate already exists and whether it's due for 24 renewal before requesting a new one. This functionality lets you run a script regularly without unnecessarily renewing 25 certificates. 26 27 - **Compatibility**: VCert Playbook works seamlessly with the three Venafi platforms: TLS Protect Cloud, TLS Protect 28 Datacenter, and Firefly, ensuring it fits your particular environment. 29 30 ## Example use cases 31 32 - **Automated certificate renewal**: You can set renewal parameters to have VCert automatically renew certificates 33 before expiration. This approach assumes that VCert is part of a daily cronjob or is executed routinely through other 34 automation methods. By default, renewal occurs at 10% of the remaining certificate lifetime. 35 36 - **Effortless API access updates**: When using TLS Protect Datacenter, VCert will automatically update API access and 37 refresh tokens within the playbook. This feature ensures continuous operation without manual intervention. It leverages 38 a refresh token to acquire a new access token when needed, an approach that's particularly effective when paired with a 39 long-lasting refresh/grant token and a short-lived access token, such as a 3-year refresh token and a 1-hour access 40 token. 41 42 ## Getting started 43 VCert Playbook functionality is invoked using the `vcert run` command. 44 45 1. Create a YAML playbook file. 46 - This readme contains all the valid options and formatting for the YAML playbook. 47 - Sample YAML playbook files are also available in the [examples folder](./examples/playbook) 48 2. Execute the playbook using the `vcert run` command: 49 ```sh 50 vcert run -f path/to/my/playbook.yaml 51 ``` 52 3. Set up a cronjob (or Windows scheduled task) to execute the playbook on a regular basis (usually daily). Sample 53 cronjob entry: 54 ``` 55 0 23 * * * /usr/bin/sudo /usr/local/bin/vcert run -f ~/playbook.yaml >> /var/log/vcert-playbook.log 2>&1 56 ``` 57 > **Recommended**: For a detailed walkthrough for automating certificate lifecycle management using a VCert Playbook 58 for NGINX, check out the guide on [Dev Central](https://developer.venafi.com/tlsprotectcloud/docs/vcert-auto-cert-mgt-using-tlspc)! 59 60 ## Usage 61 62 VCert run playbook functionality is invoked using the `vcert run` command with additional arguments: 63 ```sh 64 vcert run [OPTIONAL ARGUMENTS] 65 ``` 66 For example, the following command will execute the playbook in ./path/to/my/playbook.yaml with debug output enabled: 67 ```sh 68 vcert run --file path/to/my/playbook.yaml --debug 69 ``` 70 71 ### VCert playbook arguments 72 The following arguments are available with the `vcert run` command: 73 74 | Argument | Short | Type | Description | 75 |---------------|-------|---------|------------------------------------------------------------------------------------------| 76 | `debug` | `-d` | boolean | Enables more detailed logging. | 77 | `file` | `-f` | string | The playbook file to be run. Defaults to `playbook.yaml` in current directory. | 78 | `force-renew` | | boolean | Requests a new certificate regardless of the expiration date on the current certificate. | 79 80 ## Playbook samples 81 82 Several playbook samples are provided in the [examples folder](./examples/playbook): 83 * [Playbook for CAPI store](./examples/playbook/sample.capi.yaml) 84 * [Playbook for JKS](./examples/playbook/sample.jks.yaml) 85 * [Playbook for PEM](./examples/playbook/sample.pem.yaml) 86 * [Playbook for PKCS12](./examples/playbook/sample.pkcs12.yaml) 87 * [Playbook for multiple installations](./examples/playbook/sample.multi.yaml) 88 * [Playbook for TLSPC](./examples/playbook/sample.tlspc.yaml) 89 * [Playbook for Firefly using client secret authorization](./examples/playbook/sample.firefly.client-secret.yaml) 90 * [Playbook for Firefly using user/password authorization](./examples/playbook/sample.firefly.user-password.yaml) 91 92 ## Playbook file structure and options 93 The playbook file is a YAML file that provides access information to either TLS Protect Cloud or TLS Protect Datacenter, 94 defines the details of the certificate to request, and specifies the locations where the certificate should be installed. 95 96 The top-level structure of the file is described as follows: 97 98 ### Playbook 99 100 | Field | Type | Required | Description | 101 |------------------|------------------------------------------------------|----------------|-----------------------------------------------------------------------------------------------------------------| 102 | certificateTasks | array of [CertificateTak](#certificatetask) objects | ***Required*** | One or more [CertificateTask](#certificatetask) objects to be executed by VCert. | 103 | config | [Config](#config) object | ***Required*** | Contains one [Connection](#connection) object to either TLS Protect Cloud, TLS Protect Datacenter, or Firefly. | 104 105 ### Config 106 107 | Field | Type | Required | Description | 108 |------------|----------------------------------|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| 109 | connection | [Connection](#connection) object | ***REQUIRED*** | Defines the parameters required to make a connection to one of the following Venafi platforms:<br/>TLS Protect Cloud, TLS Protect Datacenter, or Firefly. | 110 111 ### Connection 112 113 | Field | Type | TLSPDC | TLSPC | FIREFLY | Description | 114 |-------------|------------------------------------|----------------|----------------|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 115 | credentials | [Credentials](#credentials) object | ***Required*** | ***Required*** | ***Required*** | A [Credential](#credentials) object that defines the credentials used to authenticate to the selected provider `platform`. | 116 | platform | string | ***Required*** | ***Required*** | ***Required*** | For TLS Protect Datacenter, either `tpp` or `tlspdc`.<br/>For TLS Protect Cloud, either `vaas` or `tlspc`.<br/>For Firefly, use `firefly`. | 117 | trustBundle | string | *Optional* | n/a | *Optional* | Used when [Connection.platform](#connection) is `tlspdc` or `firefly`.<br/>Defines path to PEM-formatted trust bundle that contains the root (and optionally intermediate certificates) to use to trust the TLS connection. If omitted, will attempt to use operating system trusted CAs. | 118 | url | string | ***Required*** | *Optional* | ***Required*** | URL of the Venafi platform to connect to.<br/>If url string does not include `https://`, it will be added automatically.<br/>For connection to TLS Protect Datacenter, `url` must include the full API path (for example `https://tpp.company.com/vedsdk/` <br/> For TLS Protect Cloud you can specify the url using this parameter. Currently we support the following regions:<br/>- `https://api.venafi.cloud` (US region).<br/>- `https://api.venafi.eu` (EU region).<br/>- `https://api.au.venafi.cloud` (AU region).<br/> - `https://api.uk.venafi.cloud` (UK region).<br/> - `https://api.sg.venafi.cloud` (SG region).<br/> - `https://api.ca.venafi.cloud` (CA region).<br/> If not set, will default to US region. | 119 120 ### Credentials 121 122 | Field | Type | TLSPDC | TLSPC | FIREFLY | Description | 123 |--------------|----------------------------------------------|------------|------------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 124 | accessToken | string | *Optional* | *Optional* | n/a | Used when [Connection.platform](#connection) is `tlspdc` for authenticating to the REST API.<br/>If omitted, invalid, or expired, vcert will attempt to use the [Credential.p12Task](#credentials) or [Credential.refreshToken](#credentials) to get a valid accessToken.<br/>Upon successful refresh, this value will be overwritten with the new valid accessToken. | 125 | apiKey | string | n/a | *Optional* | n/a | Used when [Connection.platform](#connection) is `tlspc` for authenticating to the REST API. | 126 | clientId | string | *Optional* | n/a | *Optional* | Used when [Connection.platform](#connection) is `tlspc` to map to the API integration to be used. If omitted, uses `vcert-sdk` as default.<br/><br/>Used when [Connection.platform](#connection) is `firefly` along with `clientSecret` to follow a `credentials authorization flow`. | 127 | clientSecret | string | n/a | n/a | *Optional* | Used when [Connection.platform](#connection) is `firefly` along with `clientId` to follow a `credentials authorization flow` to get an authorization token from the OAuth2 Provider. | 128 | externalJWT | string | n/a | *Optional* | n/a | Used when [Connection.platform](#connection) is `tlspc` along with `tokenURL` to request a new authorization token from a service account. | 129 | idP | [IdentityProvider](#identityprovider) object | n/a | n/a | ***Required*** | Used when [Connection.platform](#connection) is `firefly` to request a new authorization token to the OAuth2 Provider. | 130 | p12Task | string | *Optional* | n/a | n/a | Used when [Connection.platform](#connection) is `tlspdc` to reference a configured [CertificateTasks.name](#certificatetask) to be used for certificate authentication.<br/>Will be used to get a new accessToken when `accessToken` is missing, invalid, or expired.<br/>Referenced `certificateTask` must have an installation of type `pkcs12`. | 131 | password | string | n/a | n/a | *Optional* | Used when [Connection.platform](#connection) is `firefly` along with `user` to follow a `password authorization flow` to request a new authorization token from the OAuth2 Provider. | 132 | refreshToken | string | *Optional* | n/a | n/a | Used when [Connection.platform](#connection) is `tlspdc` to refresh the `accessToken` if it is missing, invalid, or expired.<br/>If omitted, the `accessToken` will not be refreshed when it expires.<br/>When a refresh token is used, a new accessToken *and* refreshToken are issued and the previous refreshToken is then invalid (one-time use only).<br/>vCert will attempt to update the refreshToken and accessToken fields upon refresh. | 133 | scope | string | *Optional* | n/a | *Optional* | Used when [Connection.platform](#connection) is `tlspdc` to determine the scope of the token when refreshing the access token, or when getting a new grant using a `pkcs12` certificate. Defaults to `certificate:manage` if omitted.<br/><br/>Used when [Connection.platform](#connection) is `firefly` to determine the scope of the token to be requested to the OAuth2 provider. Some providers may have default scopes while others dont. | 134 | tokenURL | string | n/a | *Optional* | n/a | Used when [Connection.platform](#connection) is `tlspc` along with `externalJWT` to request a new authorization token from a service account. | 135 | user | string | n/a | n/a | *Optional* | Used when [Connection.platform](#connection) is `firefly` along with `password` to follow a `password authorization flow` to request a new authorization token from the OAuth2 Provider. | 136 137 ### IdentityProvider 138 139 | Field | Type | TLSPDC | TLSPC | FIREFLY | Description | 140 |----------|--------|--------|-------|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 141 | audience | string | n/a | n/a | *Optional* | Used when [Connection.platform](#connection) is `firefly` to map the audience for the authorization token request from the OAuth2 Provider. Not all OAuth2 providers require this value. | 142 | tokenURL | string | | n/a | ***Required*** | Used when [Connection.platform](#connection) is `firefly` to request a new authorization token to the OAuth2 Provider. | 143 144 ### CertificateTask 145 146 | Field | Type | Required | Description | 147 |---------------|------------------------------------------------|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 148 | installations | array of [Installation](#installation) objects | ***Required*** | Specifies one or more locations in which format and where the certificate requested will be stored. | 149 | name | string | ***Required*** | The name of the certificate task within the playbook. Used in output messages to distinguish tasks when multiple certificate tasks are defined.<br/>Also, referred to by [Credential.p12Task](#credentials) when specifying a certificate to use to refresh [Credential.accessToken](#credentials).<br/>If more than one [CertificateTask](#certificatetask) exists, each name must be unique. | 150 | renewBefore | string | *Optional* | Configure auto-renewal threshold for certificates. Either by days, hours, or percent remaining of certificate lifetime.<br/>For example, `30d` renews certificate 30 days before expiration, `10h` renews the certificate 10 hours before expiration, or `15%` renews when 15% of the lifetime is remaining.<br/>Use `0` or `disabled` to disable auto-renew.<br/>Default is `10%`. | 151 | request | [Request](#request) object | ***Required*** | The [Request](#request) object specifies the details about the certificate to be requested such as CommonName, SANs, etc. | 152 | setEnvVars | array of strings | *Optional* | Specify details about the certificate to be set as environment variables before the [Installation.afterInstallAction](#installation) is executed.<br/>Supported options are `thumbprint`, `serial`, and `base64` (which sets the entire base64 of the certificate retrieved as an environment variable).<br/>Environment variables will be named `VCERT_TASKNAME_THUMBPRINT`, `VCERT_TASKNAME_SERIAL`, or `VCERT_TASKNAME_BASE64` accordingly, where `TASKNAME` is the uppercased [CertificateTask.name](#certificatetask). | 153 154 ### Installation 155 156 | Field | Type | Format<br/>PEM | Format<br/>JKS | Format<br/>PKCS12 | Format<br/>CAPI | Description | 157 |---------------------|---------|----------------|----------------|-------------------|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 158 | afterInstallAction | string | *Optional* | *Optional* | *Optional* | *Optional* | Execute this command after this installation is performed (both enrollment and renewal).<br/>On *nix, this uses `/bin/sh -c '<afterInstallAction>'`.<br/>On Windows, this uses `powershell.exe '<afterInstallAction>'`. | 159 | backupFiles | boolean | *Optional* | *Optional* | *Optional* | n/a | When `true`, backup existing certificate files before replacing during a renewal operation.<br/>Defaults to `false`. | 160 | capiFriendlyName | string | n/a | n/a | n/a | *Optional* | Specifies the friendly name to be used for the installed certificate in Windows CAPI store.<br/>If not set, the certificate Common Name will be used instead.<br/>**STRONGLY RECOMMENDED** to set this field as it will be made ***Required*** in a future release | 161 | capiIsNonExportable | boolean | n/a | n/a | n/a | *Optional* | When `true`, private key will be flagged as 'Non-Exportable' when stored in Windows CAPI store.<br/>Defaults to `false`. | 162 | capiLocation | string | n/a | n/a | n/a | ***Required*** | Specifies the Windows CAPI store to place the installed certificate. Typically `"LocalMachine\My"` or `"CurrentUser\My"`.<br/>**NOTE:** If the location is contained within `"`, the backslash `\` must be properly escaped (i.e. `"LocalMachine\\My"`). | 163 | chainFile | string | ***Required*** | n/a | n/a | n/a | Specifies the file path and name for the chain PEM bundle (Example `/etc/ssl/certs/myChain.cer`). | 164 | file | string | ***Required*** | ***Required*** | ***Required*** | n/a | Specifies the file path and name for the certificate file (PEM) or PKCS#12 / JKS bundle.<br/>Example `/etc/ssl/certs/myPEMfile.cer`, `/etc/ssl/certs/myPKCS12.p12`, or `/etc/ssl/certs/myJKS.jks`. | 165 | format | string | ***Required*** | ***Required*** | ***Required*** | ***Required*** | Specifies the format type for the installed certificate.<br/>Valid types are `PKCS12`, `PEM`, `JKS`, and `CAPI`. | 166 | jksAlias | string | n/a | ***Required*** | n/a | n/a | Specifies the certificate alias value within the Java Keystore. | 167 | jksPassword | string | n/a | ***Required*** | n/a | n/a | Specifies the password for the Java Keystore. | 168 | keyFile | string | ***Required*** | n/a | n/a | n/a | Specifies the file path and name for the private key PEM file (Example `/etc/ssl/certs/myKey.key`). | 169 | keyPassword | string | *Optional* | n/a | n/a | n/a | Specifies the password to encrypt the private key for PEM type. If not specified, the private key will be stored in an unencrypted PEM format. | 170 | useLegacyP12 | boolean | n/a | n/a | *Optional* | *Optional* | Default is false. Instructs vcert to use legacy encryption (3DES-SHA1 instead of AES-256-CBC) when encoding the keystore to maintain compatibility with Windows 2016 and earlier & OpenSSL versions 1.1/1.2. This is required for CAPI installs on Windows 2016. | 171 | ~~location~~ | string | n/a | n/a | n/a | ***DEPRECATED*** | Use `capiLocation` instead. | 172 | p12Password | string | n/a | n/a | ***Required*** | n/a | Specifies the password to encrypt the PKCS12 bundle. | 173 174 ### Request 175 176 | Field | Type | Required | Description | 177 |-------------|----------------------------------------------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 178 | appInfo | string | *Optional* | - Sets the origin attribute on the certificate object in TPP. Only valid when [Connection.platform](#connection) is `tpp`. | 179 | cadn | string | *Optional* | - Specify the DN path to the CA Template to use when requesting the certificate. (i.e. "\VED\Policy\CA Templates\internal-ca"). Only valid when [Connection.platform](#connection) is `tpp`. | 180 | chain | string | *Optional* | - Determines the ordering of certificates within the returned chain. Valid options are `root-first`, `root-last`, or `ignore`. Defaults to `root-last`. | 181 | csr | string | *Optional* | - Specifies where the CSR and PrivateKey are generated: use `local` to generate the CSR and PrivateKey locally, or `service` to have the PrivateKey and CSR generated by the specified [Connection.platform](#connection). Defaults to `local`. | 182 | fields | array of [CustomField](#customfield) objects | *Optional* | - Sets the specified custom field on certificate object. Only valid when [Connection.platform](#connection) is `tpp`. | 183 | issuerHint | string | *Optional* | - Used only when [Request.validDays](#request) is specified to determine the correct Specific End Date attribute to set on the TPP certificate object. Valid options are `DIGICERT`, `MICROSOFT`, `ENTRUST`, `ALL_ISSUERS`. If not defined, but `validDays` are set, the attribute 'Specific End Date' will be used. Only valid when [Connection.platform](#connection) is `tpp`. | 184 | keyCurve | string | ***Required*** | when [Request.keyType](#request) is `ECDSA`, `EC`, or `ECC`. Valid values are `P256`, `P384`, `P521`, `ED25519`. | 185 | keySize | integer | *Optional* | - Specifies the key size when specified [Request.keyType](#request) is `RSA`. Supported values are `1024`, `2048`, `3072`, `4096`, and `8192`. Defaults to 2048. | 186 | keyType | string | *Optional* | - Specify the key type of the requested certificate. Valid options are `RSA`, `ECDSA`, `EC`, `ECC` and `ED25519`. Default is `RSA`. | 187 | location | [Location](#location) object | *Optional* | - Use to provide the name/address of the compute instance and an identifier for the workload using the certificate. This results in a device (node) and application (workload) being associated with the certificate in the Venafi Platform.<br/>Example: `node:workload`. | 188 | nickname | string | *Optional* | - Specify the certificate object name to be created in TPP for the requested certificate. If not specified, TPP will use the [Subject.commonName](#subject). Only valid when [Connection.platform](#connection) is `tpp`. | 189 | sanDNS | array of string | *Optional* | - Specify one or more DNS SAN entries for the requested certificate. | 190 | sanEmail | array of string | *Optional* | - Specify one or more Email SAN entries for the requested certificate. | 191 | sanIP | array of string | *Optional* | - Specify one or more IP SAN entries for the requested certificate. | 192 | sanUPN | array of string | *Optional* | - Specify one or more UPN SAN entries for the requested certificate. | 193 | sanURI | array of string | *Optional* | - Specify one or more URI SAN entries for the requested certificate. | 194 | subject | [Subject](#subject) object | ***Required*** | - defines the [Subject](#subject) information for the requested certificate. | 195 | validDays | string | *Optional* | - Specify the number of days the certificate should be valid for. Only supported by specific CAs, and only if [Connection.platform](#connection) is `tpp`. The number of days can be combined with an "issuer hint" to correctly set the right parameter for the desired CA. For example, `"30#m"` will specify a 30-day certificate from a Microsoft issuer. Valid hints are `m` for Microsoft, `d` for Digicert, `e` for Entrust. If an issuer hint is not specified, the generic attribute 'Specific End Date' will be used. | 196 | zone | string | ***Required*** | - Specifies the Policy Folder (for TPP) or the Application and Issuing Template to use (for VaaS). For TPP, exclude the "\VED\Policy" portion of the folder path. **NOTE:** if the zone is not contained within `"`, the backslash `\` must be properly escaped (i.e. `Certificates\\vCert`). | 197 198 ### CustomField 199 > Custom Fields are only supported by _TLS Protect Datacenter (TLSPC)_ platform 200 201 | Field | Type | Required | Description | 202 |-------|--------|----------------|-----------------------------------------------------------------------------------------------------------------| 203 | name | string | ***Required*** | Adds a custom-field entry with name to the certificate object. The custom field must already be defined in TPP. | 204 | value | string | ***Required*** | Specifies the custom-field value to the certificate object. | 205 206 207 ### Location 208 209 | Field | Type | Required | Description | 210 |------------|---------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 211 | instance | string | ***Required*** | Specifies the name of the installed node (typically the hostname). | 212 | replace | boolean | *Optional* | Replace the current object with new information. Defaults to `false`. | 213 | tlsAddress | string | ***Required*** | Specifies the IP address or hostname and port where the certificate can be validated by the Venafi Platform. <br/>Example: `192.168.100.23:443`. | 214 | workload | string | *Optional* | Use to provide an identifier for the workload using the certificate. Example: `workload`. | 215 | zone | string | *Optional* | Use to provide a different policy folder for the device object to be created in, when platform is TPP. If excluded, the device object is created in the same policy folder as the certificate. Example: `Installations\Agentless\Datacenters\PHX` | 216 217 ### Subject 218 219 | Field | Type | Required | Description | 220 |--------------|-----------------|----------------|---------------------------------------------------------------------------------------| 221 | commonName | string | ***Required*** | Specifies the CN= (CommonName) attribute of the requested certificate. | 222 | country | string | *Optional* | Specifies the C= (Country) attribute of the requested certificate. | 223 | locality | string | *Optional* | Specifies the L= (City) attribute of the requested certificate. | 224 | organization | string | *Optional* | Specifies the O= (Organization) attribute of the requested certificate. | 225 | orgUnits | array of string | *Optional* | Specifies one or more OU= (Organization Unit) attribute of the requested certificate. | 226 | state | string | *Optional* | Specifies the S= (State) attribute of the requested certificate. |