How to generate custom keys when configuring a Bitbucket Server VCS provider in HCP Terraform and Terraform Enterprise

Introduction

This guide provides the procedure for generating a custom consumer key and a PEM-formatted SSH key pair. You can use these keys to configure a VCS provider connection to Bitbucket Datacenter or Bitbucket Server in HCP Terraform or Terraform Enterprise.

Prerequisites

• An organization in HCP Terraform or an installation of Terraform Enterprise.
• Access to a Bitbucket Datacenter or Bitbucket Server instance.
• A local terminal with access to the openssl and ssh-keygen command-line tools.

Procedure

Follow these steps to generate and use custom keys for your Bitbucket Server VCS provider.

1. Navigate to VCS Provider Settings.

   In your HCP Terraform or Terraform Enterprise organization settings, navigate to Providers and begin adding a new Bitbucket Datacenter & Server provider. When you reach step 5 of the Bitbucket Server VCS provider setup documentation, toggle Use Custom Keys. This action displays three empty fields: Consumer Key, Public Key, and Private Key.

2. Generate the Consumer Key.

   In your terminal, run the following openssl command to generate a secure random key. Copy the output to use as your Consumer Key.

   $ openssl rand -base64 32

   Example Output:

   QO2TjuZ6FzbWMqJcA6uR757NJOi65be1yZBqgl0A9aw=

3. Generate the SSH Key Pair.

   Generate a new RSA SSH key pair in PEM format. Replace the file path and comment with your desired values. When prompted for a passphrase, press Enter to leave it empty.

   $ ssh-keygen -t rsa -m PEM -f "~/.ssh/custom_terraform" -C "custom_terraform_vcs"

   Example Output:

   Generating public/private rsa key pair.
   Enter passphrase (empty for no passphrase): 
   Enter same passphrase again: 
   Your identification has been saved in ~/.ssh/custom_terraform
   Your public key has been saved in ~/.ssh/custom_terraform.pub
   The key fingerprint is:
   SHA256:qC5yFJJ42HJuGqJSML+fUDIu3/Ze+ZIEz/hLEJEy86k custom_terraform_vcs
   The key's randomart image is:
   +---[RSA 3072]----+
   | ..              |
   | + ..            |
   |.+ =..           |
   |O = +o           |
   | Xo...o=S        |
   |o.*+E...+.       |
   |+*o.. o+.        |
   |=o++.. o+.       |
   |.o.+=oo .o.      |
   +----[SHA256]-----+

4. Extract the Public Key in PEM Format.

   Use openssl to convert the public key to the required PEM format. This command reads your private key and outputs the corresponding public key.

   $ openssl rsa -in ~/.ssh/custom_terraform -outform PEM -pubout

   Copy the entire output, including the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- lines, and paste it into the Public Key field in the HCP Terraform UI.

5. Copy the Private Key.

   Display the contents of your private key file.

   $ cat ~/.ssh/custom_terraform

   Copy the entire output, including the -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY----- lines, and paste it into the Private Key field in the HCP Terraform UI.

6. Complete the Setup.

   After you have pasted all three keys into the corresponding fields, continue from Step 2 in the official documentation to create the application link in Bitbucket Server and complete the setup.