Secrets Manager

Bitbucket Plugin

Keeper Secrets Manager integration into Bitbucket for dynamic secrets retrieval

Features

  • Retrieve secrets from the Keeper Vault within BitBucket Pipelines

  • Set secret credentials as build arguments or environment variables in BitBucket Pipeline scripts

  • Copy secure files from the Keeper Vault

For a complete list of Keeper Secrets Manager features see the Overview

Prerequisites

This page documents the Secrets Manager BitBucket integration. In order to utilize this integration, you will need:

  • Keeper Secrets Manager access (See the Quick Start Guide for more details)

    • Secrets Manager addon enabled for your Keeper account

    • Membership in a Role with the Secrets Manager enforcement policy enabled

  • A Keeper Secrets Manager Application with secrets shared to it

  • An initialized Keeper Secrets Manager Configuration

    • The BitBucket integration accepts JSON and Base64 format configurations

Setup

Getting a configuration

Using Keeper Commander, add a new client to an application and initialize the configuration to a Base64 string. This will be the long text hash that appears after the "Initialized Config:" label.

My Vault> sm client add --app MyApp --config-init b64

Successfully generated Client Device
====================================

Initialized Config: eyJob3N0bmFtZSI6ICJr....OUk1ZTV1V2toRucXRsaWxqUT0ifQ==
IP Lock: Enabled
Token Expires On: 2021-10-19 15:31:31
App Access Expires on: Never

That value can be added to your BitBucket Repository variables, under Repository settings menu, as a secure secret with the name KSM_CONFIG. This will allo the configuration to be available to the Keeper Secrets Manager pipe as a variable.

Adding to bitbucket-pipeline.yml

image: atlassian/default-image:2

pipelines:
  default:
    - step:
        name: 'Build My Stuff'
        script:
          - pipe: keepersecurity/keeper-secrets-manager-pipe:<tag>
            variables:
              KSM_CONFIG: "${KSM_CONFIG}"
              SECRETS: |
                1adh_WZxtbbHWqf6IALMVg/field/login > MY_LOGIN
                V8lFbio0Bs0LuvaSD5DDHA/file/IMG_0036.png > file:my.png
              SCRIPT_TEXT: |
                #!/usr/bin/env bash
                echo "My Login = \${MY_LOGIN}"
                ls my.png
              SHOW_OUTPUT: "True"
              SECRETS_FILE: "secret.env"
              SECRETS_FILE_TYPE: "export"
          - source secret.env

Pipe Integration

The name of the pipe integration is the following.

        script:
          - pipe: keepersecurity/keeper-secrets-manager-pipe:<tag>

The pipe requires you to choose a git tag for the version. The README.md will always have the latest tag in the YAML Definition.

Variables

Required

KSM_CONFIG - The Keeer Secrets Mananger pipe requires configuration information. This can be stored in the Repository variables and pulled into a variable using "${KSM_CONFIG}"

SECRETS - The secrets are a new line separted list of Keeper Notation and destinations. The notation and desitnation are separated by the '>' character.

Optional

SCRIPT_FILE - The script file is an application, or shell script, that you wish to run inside of the pipe. The script will be able to access the secrets.

SCRIPT_TEXT - The script text allows you to hardcode a script inside of the bitbucket-pipeline.yml. It will be used if a SCRIPT_FILE does not exist. If used, you will need to escape any shell related special characters.

SECRETS_FILE - If set, secrets that were to be place into environmental varaibles will also be placed into a file. The format of the file depends on the SECRET_FILE_TYPE.

SECRETS_FILE_TYPE - If a SECRET_FILE is used, this variable will determine it's format. Valid formats are 'json', 'export', 'setenv', and 'set'. The default is 'json'

SHOW_OUTPUT - A boolean flag to show the output from the SCRIPT_FILE or SCRIPT_TEXT. The REDACT variable will determine if you will be able to see your secrets in the ouput. By default, this flag is True.

SAVE_OUTPUT_FILE - If set, the output from the SCRIPT_FILE or SCRIPT_TEXT will be saved to a file.

REDACT - If True, any secret displayed from the SCRIPT_FILE or SCRIPT_TEXT will be replaced with '****'. By default, this flag is True. This does not redact output saved to a file.

REMOVE_FILES - If True, when the pipe exits it will delete any files it created. Those files will not be available outside of the pipe unless the value is set to False. By default, this is True.

CLEANUP_FILE - The name of a shell script that will remove any files created inside of the pipe. While the build workspace is removed when the build finishes, this shell file can be run to make sure the files are deleted. If not set, no clean up file will be created.

DEBUG - Enable debug message inside of the pipe. By default, this is False.

Retrieving Secrets

The SECRETS variable in the YAML contains a list of Keeper Notation and where the value should be stored. Secrets can be stored as an environmental variable or in a file.

The default destination for a variable is a environmental variable. The prefix env: can be added to the front of the environmental variable name, but is not required.

The environmental variable name must be a valid Unix environmental variable name

Saving secrets to an environment variable

The example below will take the login secret and place them into environmental variables. Both lines do the same, one without the env: prefix and one with.

        script:
          - pipe: keepersecuirty/keeper-secrets-manager-pipe:<tag>
            variables:
              KSM_CONFIG: "${KSM_CONFIG}"
              SECRETS: |
                1adh_WZxtbbHWqf6IALMVg/field/login > MY_LOGIN
                1adh_WZxtbbHWqf6IALMVg/field/login > env:SAME_LOGIN

In the example, 1adh_WZxtbbHWqf6IALMVg is a record UID.

Saving secrets to a file

If the secret is binary data it is highly recommended not to store the secret in an environmental variable due to encoding issues. Use the file: destination instead.

        script:
          - pipe: keepersecurity/keeper-secrets-manager-pipe:<tag>
            variables:
              KSM_CONFIG: "${KSM_CONFIG}"
              SECRETS: |
                1adh_WZxtbbHWqf6IALMVg/file/server.xml > file:server.xml
                1adh_WZxtbbHWqf6IALMVg/file/domain.crt > file:config/path/domain.crt

If the variable REMOVE_FILES is True, the file will be removed when the pipe exits. Set this variable to False if you wish to use the files outside of the pipe.

Examples

Example 1 - Docker Build

This example will create a Tomcat server Docker image that contains a custom server.xml config and keystore containing the SSL certs. The server.xml and keystore are stored in the Keeper Vault.

The first step is to create a repo in BitBucket, then add a Dockerfile. This Dockerfile will add two files created by the Keeper Secrets Manager pipe to an official Tomcat Docker image.

FROM tomcat:10-jdk16

ADD /server.xml /usr/local/tomcat/conf/server.xml
ADD /localhost-rsa.jks /usr/local/tomcat/conf/localhost-rsa.jks

# Expose port 8443 for SSL
EXPOSE 8443

Next a configuration is needed for the Keeper Secrets Manager pipe. This can be created using Keeper Commander and initializing the config as Base64.

My Vault> sm client add --app MyApp --config-init b64

Successfully generated Client Device
====================================

Initialized Config: eyJob3N0bmFtZSI6ICJr....OUk1ZTV1V2toRucXRsaWxqUT0ifQ==
IP Lock: Enabled
Token Expires On: 2021-10-19 15:31:31
App Access Expires on: Never

For more options creating a configuration, see the configuration documentation

The Initialized Config: Base64 string needs to be cut-n-pasted into your Repository variables. In this example the name of the variable is KSM_CONFIG. A private Docker Hub username and password are also added to the Repository variables.

Next a bitbucket-pipelines.yml file needs to be added to the repository.

image: atlassian/default-image:2

pipelines:
  default:
    - step:
        name: 'Build Custom Tomcat Server'
        script:
          - pipe: keepersecuirty/keeper-secrets-manager-pipe:<tag>
            variables:
              KSM_CONFIG: "${KSM_CONFIG}"
              SECRETS: |
                3GGclNXOoU0DwZwdn6iZmg/file/server.xml > file:server.xml
                3GGclNXOoU0DwZwdn6iZmg/file/localhost-rsa.jks > file:localhost-rsa.jks
              REMOVE_FILES: "False"
              CLEANUP_FILE: "ksm_cleanup.sh"
          - VERSION="1.$BITBUCKET_BUILD_NUMBER"
          - IMAGE="$DOCKERHUB_USERNAME/$BITBUCKET_REPO_SLUG"
          - docker login --username "$DOCKERHUB_USERNAME" --password "${DOCKERHUB_PASSWORD}"
          - docker image build -t ${IMAGE}:${VERSION} .
          - docker image tag ${IMAGE}:${VERSION} ${IMAGE}:latest
          - docker image push ${IMAGE}
          - git tag -a "${VERSION}" -m "Tagging for release ${VERSION}"
          - git push origin ${VERSION}
          - ./ksm_cleanup.sh
        services:
          - docker

The above is used to build a Docker image and push it to your Docker Hub account. The first step will use the Keeper Secrets Manager pipe to retrieve the two files and place them into the work directory.

The REMOVE_FILES variable is set to False since we don't want to delete them after the pipe has finished.

The CLEANUP_FILE variable is set to ksm_cleanup.sh which will create a script that will remove the two files when we are done.

When we build the Dockerfile, it will add the two files into the correct locations inside the image. When done it will push the image to the Docker Hub account.

The last part is running the ksm_cleanup.sh script that was set by the CLEANUP_FILE variable. This will make sure the two files we created are deleted. BitBucket Pipeline does delete the work space when it is done, however this guarantees the files are deleted.

Example 2 - Using Keeper Secrets Manager pipe with other pipes.

This example will retrieve secrets that are used as variables for another pipe. The other pipe is the AWS S3 Deploy pipe which will copy a local directory into a S3 bucket.

In the Keeper Vault, a record was created that contains our AWS credentials and information about the S3 bucket.

The first step is to create a repo in BitBucket, and then store the Keeper Secrets Manager pipe configuration in the Repository variables. This can be created using Keeper Commander and initializing the config as Base64.

My Vault> sm client add --app MyApp --config-init b64

Successfully generated Client Device
====================================

Initialized Config: eyJob3N0bmFtZSI6ICJr....OUk1ZTV1V2toRucXRsaWxqUT0ifQ==
IP Lock: Enabled
Token Expires On: 2021-10-19 15:31:31
App Access Expires on: Never

For more options creating a configuration, see the configuration documentation

The Initialized Config: Base64 string needs to be cut-n-pasted into your Repository variables. In this example the name of the variable is KSM_CONFIG.

Next a bitbucket-pipelines.yml file needs to be added to the repository.

image: atlassian/default-image:2

pipelines:
  default:
    - step:
        name: 'Copy Image To S3'
        script:
          - pipe: keepersecurity/keeper-secrets-manager-pipe:<tag>
            variables:
              KSM_CONFIG: "${KSM_CONFIG}"
              SECRETS: |
                IumwT1QYRr8TTCtY8rqzhw/custom_field/AWS_ACCESS_KEY_ID > AWS_ACCESS_KEY_ID
                IumwT1QYRr8TTCtY8rqzhw/custom_field/AWS_SECRET_ACCESS_KEY > AWS_SECRET_ACCESS_KEY
                IumwT1QYRr8TTCtY8rqzhw/custom_field/AWS_DEFAULT_REGION > AWS_DEFAULT_REGION
                IumwT1QYRr8TTCtY8rqzhw/custom_field/S3_BUCKET > S3_BUCKET
                V8lFbio0Bs0LuvaSD5DDHA/file/IMG_0036.png > file:to_s3/my_image.png
              SECRETS_FILE: "secrets.env"
              SECRETS_FILE_TYPE: "export"
          - source ./secrets.env
          - pipe: atlassian/aws-s3-deploy:1.1.0
            variables:
              AWS_ACCESS_KEY_ID: "${AWS_ACCESS_KEY_ID}"
              AWS_SECRET_ACCESS_KEY: "${AWS_SECRET_ACCESS_KEY}"
              AWS_DEFAULT_REGION: "${AWS_DEFAULT_REGION}"
              S3_BUCKET: "${S3_BUCKET}"
              LOCAL_PATH: "to_s3"

The bitbucket-pipelines.yml contains the Keeper Secrets Manager pipe which will retrieve our AWS credential from a record and place them into environment variables. It will also get a PNG image and write it into a directory called to_s3. The pipe will create a secrets file called secrets.env.

The SECRETS_FILE_TYPE is export which will allow the contents to be sourced and the secret values placed into environment.

Next the secrets file is sourced. This allows other pipes, and applications, access to the secrets as environmental variables.

The last step is using the aws-s3-deploy pipe to copy the image to the S3 bucket. The variables for the aws-s3-deploy pipe are set using the environmental variables provided by the Keeper Secrets Manager pipe's secret file.

PreviousAzure Key VaultNextDocker Image

Last updated