Skip to main content

Bitbucket On-Premise Configuration

Overview​

This page contains all the information needed to create a Guardrails Bitbucket user and application link on your Bitbucket server (or Bitbucket data center) instance. This is needed to allow guardrails to seamlessly integrate into the development workflow and makes onboarding all repositories in your organization easy and quick.

Only required for Bitbucket deployments.

IMPORTANT: For this guide we will assume that <YOUR_HOST> will be the configured dns (i.e.: guardrails.your-company.com). So whenever you see a <YOUR_HOST> remember this.

Create private/public keys​

The goal of this step is to create a private and a public key that will be used to secure the communication between Guardrails and the Bitbucket server.

Generate the private/public key pairs by executing the following commands

mkdir guardrails-keys && cd guardrails-keys
openssl genrsa -out privatekey.pem 2048
openssl rsa -in privatekey.pem -outform PEM -pubout -out publickey.pem

You can view the private key by executing the following command:

cat privatekey.pcks8

We will refer to this output as <YOUR_PRIVATE_KEY> in the steps below.

You can view the public key by executing the following command:

cat publickey.pem

We will refer to this output as <YOUR_PUBLIC_KEY> in the steps below.

The goal of this step is to create a Bitbucket server application link that we are going to use to connect to GuardRails to allow for a seamless integration of the security scanning across all repositories. GuardRails is tightly integrated into the workflow and provides a pleasant developer experience.

Create a Bitbucket application link for GuardRails in your Bitbucket server instance by following the instructions below:

  1. Login to <bitbucket-domain> as an administrative user
  2. Go to <bitbucket-domain>/plugins/servlet/applinks/listApplicationLinks
  3. Enter https://<YOUR_HOST> into the input box
  4. Click on Create new link
  5. Click on Continue. (Even if you get an error message that no response was received from the URL)
  6. Fill out the details like below:
    • Application Name: Guardrails
    • Application Type: Generic Application
    • (leave the rest of the fields blank)
  7. Click on Continue
  8. In the application list, click on the edit (pencil icon) on the right hand side of the Guardrails list item
  9. Click on Incoming Authentication
  10. Fill out the details like below:
    • Consumer Key: (enter random characters, but you need to remember it as you will need it in a later step, we will refer to this as the <CONSUMER_KEY>)
    • Consumer Name: Guardrails
    • Description: (leave this blank)
    • Public Key: <YOUR_PUBLIC_KEY>
    • Consumer Callback URL: (leave this blank)
    • Allow 2-Legged OAuth: (leave unchecked)
  11. Click on Save
  12. Click on Close

Self-signed Certificates​

If you are using self-signed certificates for the GuardRails instance, then Bitbucket will not be able to connect to it by default and require some custom configuration steps to make it work.

The steps needed to set it up can be found at this Atlassian resource.

Create a Bitbucket User​

The goal of this step is to create a privileged Bitbucket GuardRails user that will allow for a seamless integration of the security scanning across all repositories. We will also need the details to allow for a single-sign on authentication using your Bitbucket on-premise instance. Because of this step, GuardRails is tightly integrated into the workflow and provides a pleasant developer experience.

Create a Bitbucket user for GuardRails in your Bitbucket server instance by following the instructions below:

  1. Login to <bitbucket-domain> as an administrative user
  2. Go to <bitbucket-domain>/admin/users?create
  3. Fill out the user details like below:
    • Username: guardrails
    • Full name: GuardRails
    • Email: [email protected], this has to be filled out, but a valid email address is not required.
    • Password: (enter a password)
  4. Click on Create user

Give user admin permission​

  1. Go to <bitbucket-domain>/admin/permissions
  2. Click on the input box under "User access" that says "Add Users"
  3. Enter guardrails in the input box
  4. In the dropdown list that says "Bitbucket User" select Admin
  5. Click on Add

Create a PAT for the new user​

PAT = Personal Access Token

  1. Login to Bitbucket server as the user (guardrails) that you just created
  2. Navigate to <bitbucket-domain>/plugins/servlet/access-tokens/manage
  3. Click on Create a token
  4. Under Token details enter the following:
    • Token name: guardrails-pat
  5. Under Permissions select the following:
    • Projects: Admin
    • Repositories: Admin
  6. Click on Create
  7. Now you will see your personal access token which you need to save for later use we will refer to this token as <YOUR_PAT> in later steps.
  8. Click on Continue

If you followed and completed the steps of this guide, you should have collected the following data in order to continue:

  • Private Key For Communication Between Guardrails And Bitbucket
  • Bitbucket Consumer Key For The Application Link
  • Bitbucket User Personal Access Token (PAT)

Make sure you have this before you proceed to Setup & Deploy

Configure Pre-Receive Hooks​

You can configure pre-receive hooks for Bitbucket on-premise versions by following the instructions here.

Last updated on by Stefan Streichsbier