venafi-vcert-gitlab-integration 2.1.0

Venafi Machine Identity Management: Gitlab integration

Venafi Machine Identity Management integration for Gitlab

This plugin integrates Venafi Machine Identity Management with Gitlab-based CI/CD processes.

Table of contents

• Usage overview
• Setting up the TPP
• Setting up executor hosts (shell and SSH executors only)
• Compatibility
• Operations
  • Request certificate
    • Usage with Docker executor
    • Usage with shell or SSH executor
    • Variables: general
    • Variables: subject information
    • Variables: output
  • Download previous certificate
    • Usage with Docker executor
    • Usage with shell or SSH executor
    • Variables
  • Renewing certificate only when expiration is near

Usage overview

You must already have access to either Venafi TLS Protect (part of the Venafi Trust Protection Platform™) or Venafi as a Service. This Gitlab integration product requires you to specify the connection address and authentication details.

You use this Gitlab integration product by defining, inside your Gitlab CI YAML, jobs call operations provided by this Gitlab integration product.

Setting up the TPP

This is not applicable when using Venafi as a Service.

If you plan on using this Gitlab integration product in combination with a TPP, then you must setup an API Application Integration:

1. Go to your TPP's Aperture web interface.

2. Go the Platform product.

3. In the top navbar, click API ➜ API Application Integrations.

4. Click "New Application Integration".

5. Under "Type of Integration", select "Vendor Integration". Paste the following JSON:

   {
       "id": "qensus-vcert-gitlab",
       "name": "Qensus VCert Gitlab",
       "vendor": "Qensus B.V.",
       "description": "Venafi Machine Identity Management integration for Gitlab",
       "scope": "certificate:manage"
   }
   

   Then click Save.

6. Select the "Qensus VCert Gitlab" integration and click "Edit Access". Grant access to the TPP user account that you want to use from Jenkins.

Setting up executor hosts (shell and SSH executors only)

If you plan on using this Gitlab integration product in combination with the shell and SSH executors, then you must install the following software on the hosts on which those executors operate. This Gitlab integration product does not take care of installing these prerequisites for you.

• Install Python >= 3.8. Ensure that it's in PATH.

• Install pip >= 20.2. This is necessary in order to use the 2020 dependency resolver.

• Install our Gitlab integration package:

  • If you're on pip >= 20.2 but < 20.3, then run: pip install venafi-vcert-gitlab-integration --use-feature=2020-resolver
  • If you're on pip >= 20.3, then run: pip install venafi-vcert-gitlab-integration

Compatibility

This product requires Gitlab >= 13.9.

This product supports the following Gitlab runner executors:

• Shell
• SSH
• Docker

Operations

Request certificate

Requests a pair of certificate + private key. The output is to be written to the specified files, in PEM format.

Usage with Docker executor

• Define a job that calls venafi-vcert-request-certificate.
• Ensure the job operates within the image quay.io/venafi-gitlab-integration/tlsprotect-vcert. We recommend that you specify a tag in order to avoid breaking changes introduced by new major versions.
• Specify:
  • Connection and authentication details for either a TPP or for Venafi as a Service.
  • Certificate request parameters.
  • Where to store the output.
• See the variables reference below.

request_cert:
  image: quay.io/venafi-gitlab-integration/tlsprotect-vcert:2-x86_64
  script:
    - venafi-vcert-request-certificate
  variables:
    ## Specify TPP or Venafi as a Service parameters
    TPP_BASE_URL: https://my-tpp
    TPP_USERNAME: my_username
    # TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.

    ## Specify certificate parameters
    ZONE_CONFIG_NAME: Certificates\\VCert
    COMMON_NAME: yourdomain.com
    ORGANIZATION: orgname
    ORGANIZATIONAL_UNIT: orgunit
    LOCALITY: Amsterdam
    PROVINCE: Noord-Holland
    COUNTRY: NL

    ## Specify where you want to store the output
    CERT_OUTPUT: cert.crt
    CERT_CHAIN_OUTPUT: chain.crt
    PRIV_KEY_OUTPUT: priv.key
  artifacts:
    paths:
      - cert.crt
      - chain.crt
      - priv.key

Usage with shell or SSH executor

• Define a job that calls venafi-vcert-request-certificate.
• Specify:
  • Connection and authentication details for either a TPP or for Venafi as a Service.
  • Certificate request parameters.
  • Where to store the output.
• See the variables reference below.

request_cert:
  script:
    - venafi-vcert-request-certificate
  variables:
    ## Specify TPP or Venafi as a Service parameters
    TPP_BASE_URL: https://my-tpp
    TPP_USERNAME: my_username
    # TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.

    ## Specify certificate parameters
    ZONE_CONFIG_NAME: Certificates\\VCert
    COMMON_NAME: yourdomain.com
    ORGANIZATION: orgname
    ORGANIZATIONAL_UNIT: orgunit
    LOCALITY: Amsterdam
    PROVINCE: Noord-Holland
    COUNTRY: NL

    ## Specify where you want to store the output
    CERT_OUTPUT: cert.crt
    CERT_CHAIN_OUTPUT: chain.crt
    PRIV_KEY_OUTPUT: priv.key
  artifacts:
    paths:
      - cert.crt
      - chain.crt
      - priv.key

Variables: general

Required (when using a TPP):

• TPP_BASE_URL: The TPP's base URL. It must not contain the /vedsdk suffix path.
• TPP_USERNAME: A login username for the TPP.
• TPP_PASSWORD or TPP_PASSWORD_BASE64: The password associated with the login username. You can specify it normally, or in Base64 format. The latter is useful for storing the password in a Gitlab variable, in masked form, because Gitlab can only mask variables whose content only consists of Base64 characters.

Required (when using Venafi as a Service):

• VENAFI_AS_A_SERVICE_API_KEY: The Venafi as a Service API key.

Required (no matter what you use):

• ZONE_CONFIG_NAME: the name of the zone configuration to use.

  When using Venafi as a Service, zone names are in the format of app name\api alias

Optional:

• EXPIRATION_WINDOW: number of hours before certificate expiry to request a new certificate. We'll check whether the certificate file referenced by CERT_OUTPUT already exists, and if so, we'll only proceed with requesting a new certificate if the file's expiry date is within EXPIRATION_WINDOW hours. Learn more at Renewing certificate only when expiration is near.

• KEY_TYPE: either 'RSA' (default) or 'ECDSA'.

• DNS_NAMES: a list of DNS names, as part of the certificate's Alternative Subject Names. Separate multiple values with a comma.

  Example:

  DNS_NAMES: host1.com,host2.com
  

• IP_ADDRESSES: a list of IP addresses, as part of the certificate's Alternative Subject Names. Separate multiple values with a comma.

  Example:

  IP_ADDRESSES: 127.0.0.1,127.0.0.2
  

• EMAIL_ADDRESSES: a list of email addresses, as part of the certificate's Alternative Subject Names. Separate multiple values with a comma.

  Example:

  EMAIL_ADDRESSES: [e-mail],[e-mail]
  

Variables: subject information

Required:

• COMMON_NAME: the certificate's common name.

Required or optional, depending on the connector's zone configuration:

• ORGANIZATION
• ORGANIZATIONAL_UNIT
• LOCALITY
• PROVINCE
• COUNTRY

Variables: output

Required:

• PRIV_KEY_OUTPUT: a path to which the private key should be written.
• CERT_OUTPUT: a path to which the certificate should be written.
• CERT_CHAIN_OUTPUT: a path to which the certificate chain should be written.

Download previous certificate

Downloads a previously-requested certificate. This works by calling the Gitlab API, searching for a certificate in the latest successful CI build's artifacts. By default, we search in the CI builds of the same project and branch that the pipeline is running on.

If the previous certificate is not found, then it exits with code 30.

This operation is mainly meant to be used for renewing certificate only when expiration is near. See the example in that section for further explanation of this operation's usage.

Usage with Docker executor

• Define a job that calls exec venafi-vcert-download-prev-cert. Note: the exec keyword is required to ensure that the Gitlab job exits with the correct exit code.
• Ensure the job operates within the image quay.io/venafi-gitlab-integration/tlsprotect-vcert. We recommend that you specify a tag in order to avoid breaking changes introduced by new major versions.
• Ensure a failure due to exit code 30 is allowed.
• Ensure that the certificate to download, is also published as an artifact.
• Specify:
  • The name of the CI job that's responsible for calling venafi-vcert-request-certificate.
  • The certificate's filename.
• See the variables reference below.

download_prev_cert:
  image: quay.io/venafi-gitlab-integration/tlsprotect-vcert
  script:
    - exec venafi-vcert-download-prev-cert
  variables:
    # Specify either one of the following. See the variables reference
    # for info and caveats.
    USE_CI_JOB_TOKEN: 'true'
    # Or set GITLAB_BEARER_TOKEN from the UI, with masking enabled.

    REQUESTER_JOB_NAME: request_cert
    CERT_FILENAME: cert.crt
  allow_failure:
    exit_codes: 30
  artifacts:
    paths:
      - cert.crt

Usage with shell or SSH executor

• Define a job that calls exec venafi-vcert-download-prev-cert. Note: the exec keyword is required to ensure that the Gitlab job exits with the correct exit code.
• Ensure a failure due to exit code 30 is allowed.
• Ensure that the certificate to download, is also published as an artifact.
• Specify:
  • The name of the CI job that's responsible for calling venafi-vcert-request-certificate.
  • The certificate's filename.
• See the variables reference below.

download_prev_cert:
  script:
    - exec venafi-vcert-download-prev-cert
  variables:
    # Specify either one of the following. See the variables reference
    # for info and caveats.
    USE_CI_JOB_TOKEN: 'true'
    # Or set GITLAB_BEARER_TOKEN from the UI, with masking enabled.

    REQUESTER_JOB_NAME: request_cert
    CERT_FILENAME: cert.crt
  allow_failure:
    exit_codes: 30
  artifacts:
    paths:
      - cert.crt

Variables

Required: specify an authentication method. Either one of the following must be set:

• USE_CI_JOB_TOKEN: set to 'true' to use the Gitlab CI/CD job token, fetched from the predefined CI variable CI_JOB_TOKEN. Note: this requires Gitlab Premium >= 13.10.
• GITLAB_BEARER_TOKEN: set to a Personal/Project Access Token, or OAuth2 token.

Required:

• REQUESTER_JOB_NAME: the name of the CI job that's responsible for calling venafi-vcert-request-certificate. This operation will search inside that job's artifacts for the certificate.

  We expect that that job publishes the requested certificate as an artifact.

• CERT_FILENAME: the filename of the certificate to search for. This operation will attempt to download this file and store it in the workspace. You must also publish this same file as an artifact.

  We expect that the job referenced by REQUESTER_JOB_NAME, publishes the requested certificate as an artifact under the specified filename.

Optional:

• GITLAB_API_V4_URL: the base URL of the Gitlab API (version 4) to call. We request artifacts using this API. If not specified, we default to using the predefined CI variable CI_API_V4_URL.
• PROJECT_PATH: the name of the Gitlab project in which to search artifacts, e.g. myusername/myrepo. If not specified, we default to using the predefined CI variable CI_PROJECT_PATH.
• BRANCH_NAME: the name of the branch in which to search artifacts, e.g. main. If not specified, we default to using the predefined CI variable CI_COMMIT_REF_NAME.

Renewing certificate only when expiration is near

Normally, venafi-vcert-request-certificate requests a certificate every time it's called. Sometimes you only want to request a certificate when it's about to expire. The EXPIRATION_WINDOW variable addresses this use case.

EXPIRATION_WINDOW expects that you fetch the previously generated certificate, and store it under the same path as specified by CERT_OUTPUT. The EXPIRATION_WINDOW feature will then check whether that file's expiry date is within EXPIRATION_WINDOW hours. If so, or if there is no previously generated certificate, then it'll proceed with requesting a new certificate. Otherwise it does nothing, and logs this decision.

Here's an example of idiomatic usage.

stages:
 - download_prev_cert
 - request_cert

# Download previous certificate artifact.
download_prev_cert:
  stage: download_prev_cert
  image: quay.io/venafi-gitlab-integration/tlsprotect-vcert:2-x86_64
  script:
    - exec venafi-vcert-download-prev-cert
  variables:
    # Specify either one of the following. See the variables reference
    # for info and caveats.
    USE_CI_JOB_TOKEN: 'true'
    # Or set GITLAB_BEARER_TOKEN from the UI, with masking enabled.

    # The name of the job that's responsible for requesting a certificate.
    REQUESTER_JOB_NAME: request_cert
    # The filename of the certificate to download. This matches the
    # artifact filename as published by the `request_cert` job.
    CERT_FILENAME: cert.crt
  allow_failure:
    # If the certificate can't be found, the script exits with code 30.
    # We allow this failure so that `request_cert` will still be called,
    # just without a previous certificate.
    exit_codes: 30
  artifacts:
    paths:
      # If a previous certificate is downloaded, publish it as an
      # artifact so that the `request_cert` job can consume it.
      - cert.crt

# Only request a new certificate if there is no previous certificate,
# or if the previous certificate expires within 48 hours.
request_cert:
  image: quay.io/venafi-gitlab-integration/tlsprotect-vcert:2-x86_64
  script:
    - venafi-vcert-request-certificate
  variables:
    TPP_BASE_URL: https://my-tpp
    TPP_USERNAME: my_username
    # TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.

    EXPIRATION_WINDOW: 48

    ZONE_CONFIG_NAME: Certificates\\VCert
    COMMON_NAME: yourdomain.com
    ORGANIZATION: orgname
    ORGANIZATIONAL_UNIT: orgunit
    LOCALITY: Amsterdam
    PROVINCE: Noord-Holland
    COUNTRY: NL

    CERT_OUTPUT: cert.crt
    CERT_CHAIN_OUTPUT: chain.crt
    PRIV_KEY_OUTPUT: priv.key
  artifacts:
    paths:
      # Store the certificate file as an artifact. This file could
      # be a newly requested certificate, or it could be the previous
      # certificate. The next pipeline build will attempt to fetch this
      # file.
      - cert.crt
      - chain.crt
      - priv.key