Keeper Secrets Manager integrates into popular CI/CD platforms and development environments. Use Keeper Secrets Manager to inject secrets into your build processes, and remove hard-coded credentials from your environments.

Ansible

A collection of Ansible plugins that interact with Keeper Secrets Manager

Go to Ansible Documentation

AWS CLI Credential Process

Protect your AWS Access Keys with Keeper Secrets Manager

Go to AWS CLI Credential Process Documentation

AWS Secrets Manager

Sync secrets from the Keeper Vault with AWS Secrets Manager

Go to AWS Secrets Manager Documentation

AWS KMS Encryption

Protect your Keeper Secrets Manager configuration with AWS KMS.

Go to AWS KMS Documentation

Azure DevOps

Securely retrieve secrets from the Keeper Vault and use them in Azure DevOps pipelines. Remove hardcoded values, fetch secure files, and keep all your build credentials in the Keeper Vault.

Go to Azure DevOps Integration

Azure Key Vault Sync

Sync secrets from the Keeper Vault with Azure Key Vault.

Go to Azure Key Vault Sync Documentation

Azure Key Vault Encryption

Protect your Keeper Secrets Manager configuration with Azure Key Vault.

Go to Azure Key Vault Encryption Documentation

BitBucket

Retrieve secrets from the Keeper Vault within BitBucket Pipelines.

Go to BitBucket Plugin Documentation

Docker Image

The Secrets Manager CLI can be used to pull secrets from a Docker image at runtime, or it can be used by building it into the docker image.

Go to Docker Image Documentation

Docker Runtime

Keeper Secrets Manager integrates with the Docker Runtime so that you can dynamically retrieve a secret from the vault when the container executes.

Go to Docker Runtime Documentation

Docker Writer Image

A general purpose docker image to retrieve secrets.

Go to Docker Write Image

Entrust HSM Encryption

Protect your Keeper Secrets Manager connections with the Entrust HSM

Go to Entrust HSM Documentation

Git - Sign Commits with SSH Key

This integration will let you sign git commits with an SSH key in your Keeper Vault (via Keeper Secrets Manager) rather than using a key stored on disk.

Go to Git Integrations

GitHub Actions

This action securely retrieves secrets from Keeper and places them to the desired destination of the GitHub Actions runner such as an environment variable, output parameters of the step or to a file.

Go to Github Actions Integration

GitLab

Bring secret credentials into your GitLab Pipeline builds using Keeper's Secrets Manager GitLab plugin.

Go to GitLab Documentation

Google Cloud Secret Manager Sync

Sync secrets from the Keeper Vault with GCP Secret Manager.

Go to GCP Secret Manager Documentation

Google Cloud Key Management Encryption

Protect your Keeper Secrets Manager connections with GCP Key Management.

Go to GCP Key Management Encryption Documentation

Hashicorp Vault

Use Keeper Secrets Manager with HashiCorp Vault as a Data Source

Go to Hashicorp Vault Documentation

Heroku

Use Keeper Secrets Manager SDKs to bring secret credentials and files securely into Heroku builds.

Go to Heroku Documentation

Jenkins Plugin

The Jenkins plugin for Keeper Secrets Manager allows you retrieve secrets from the Keeper Vault and place the values into environmental variables or files within the builder and workflow pipelines.

Go to Jenkins Plugin Documentation

Keeper Connection Manager

Store connection credentials in the Keeper Vault and easily use them in Connection Manager.

Go to Keeper Connection Manager Documentation

Kubernetes

Keeper Secrets Manager can be integrated into your K8s cluster for accessing Keeper secrets in real-time across all pods.

Go to the Kubernetes External Secrets Operator Documentation

Go to the legacy Kubernetes Documentation

Linux Keyring

Store and retrieve secrets from the Linux Keyring

Go to the Linux Keyring Documentation

Model Context Protocol (MCP) for AI Agents (Docker)

Integrate Keeper Secrets Manager into AI agents using this Docker container

Go to the MCP Documentation for Docker

Model Context Protocol (MCP) for AI Agents (Node)

Integrate Keeper Secrets Manager into AI agents using this Node module

Go to the MCP Documentation for Node

Octopus Deploy

Use credentials from your Keeper Vault in Octopus Deploy workflows. Integrate with Keeper Secrets Manager to securely access all the platforms and services you connect to with Octopus Deploy.

Go to Octopus Documentation

Oracle Key Vault Encryption

Protect your Keeper Secrets Manager connections with Oracle Key Vault.

Go to Oracle Key Vault Encryption Documentation

PowerShell

Utilize PowerShell's Secret Management module to access secrets from Keeper.

Go to PowerShell Documentation

ServiceNow

Retrieve credentials from the vault from the ServiceNow Management, Instrumentation, and Discovery (MID) Server integration.

Go to ServiceNow Documentation

TeamCity

Use secrets from the Keeper vault in TeamCity builds.

Go to TeamCity Documentation

Teller

Retrieve secrets from the Keeper Vault within Teller environments.

Go to Teller Documentation

Terraform

The Keeper Terraform Plugin utilizes Keeper Secrets Manager to provide access to secret credentials saved in the Keeper Vault. The Keeper Terraform plugin allows for injecting secrets directly into Terraform builds securely using Keeper's zero-knowledge infrastructure.

Go to Terraform Documentation

Windows Credential Manager

Store and retrieve secrets from the Windows Credential Manager

Go to the Windows Credential Manager Documentation

XSOAR

Use credentials from your Keeper Vault in XSOAR workflows. Integrate with Keeper Secrets Manager to securely access all the platforms and services you connect to with XSOAR.

Go to XSOAR Documentation

CLI Tools

Use Keeper Secrets Manager in a CLI environment. Build scripts that securely utilize your secrets, or easily access Secrets Manager functionality from your terminal.

PowerShell

The Keeper Secrets Manager PowerShell plugin utilizes Microsoft PowerShell's Secret Management module to inject secrets from the Keeper Vault into your PowerShell scripts.

Go to PowerShell Documentation

Secrets Manager CLI

The Keeper Secrets Manager CLI ("KSM CLI") provides core Secrets Manager Vault interaction from a terminal, shell script or any software that can be launched from a shell.

Go to Secrets Manager CLI

Features

• Retrieve secrets from the Keeper vault to use in Ansible Playbooks

• Update the value of secrets in the Keeper Vault from Ansible

• Copy files from the Keeper Vault

• Use Keeper Secrets Manager within Ansible Tower to fetch secret credentials and files in your Ansible Playbooks.

Ansible Integrations

Check out the nested pages for using Secrets Manager with Ansible

Ansible Plugin

How to use Keeper Secrets Manager to fetch secret credentials and files in your Ansible Playbooks

Ansible Tower

Store Keeper Secrets Manager configuration credentials in Ansible Tower and create reusable playbook templates that utilize Keeper Secrets Manager features.

Features

• Retrieve secrets from the Keeper vault to use in Ansible Playbooks

• Update the value of secrets in the Keeper Vault from Ansible

• Create records from Ansible

• Copy files from the Keeper Vault

Prerequisites

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

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

  • Secrets Manager add-on 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

  • See the Quick Start Guide for instructions on creating an Application

• An initialized Keeper Secrets Manager Configuration

  • The Ansible integration accepts both Base64 and JSON format configurations

Installation

Due to the flexibility of Ansible, where you install the plugins depends on your Ansible installation and playbook locations.

Install Keeper Ansible Module

Installation via Ansible Galaxy

The collection can be found on the Ansible Galaxy website. You can install the collection with the follow command line.

$ ansible-galaxy collection install keepersecurity.keeper_secrets_manager

Ansible Galaxy collection uses long plugin names. The name is the collection name combined with the plugin name. For example, the keeper_copy plugin name when using Ansible Galaxy is keeper_security.keeper_secrets_manager.keeper_copy. If you want to use the short plugin name, add keepersecurity.keeper_secrets_manager to the collections block of your playbook.

- name: Keeper Copy
  hosts: my_hosts
  collections: 
    - keepersecurity.keeper_secrets_manager
  
  tasks:
    - name: Copy a password
      keeper_copy:
        uid: RECORD UID
        ...

Installation via Pypi

The Ansible module for Keeper is installed with the command below. Make note of the location where the module is installed, as this will be needed in the Ansible playbook configuration.

$ pip3 install -U keeper_secrets_manager_ansible

Find the Keeper Secrets Manager Ansible Plugin source code in the GitHub repository.

The Keeper ansible plugins are installed in the site-packages directory of your version of Python or your current virtual environment. You can find the plugin locations using the following command:

$ keeper_ansible --config

# Below are the directory paths to action and lookup plugins.
ANSIBLE_ACTION_PLUGINS=...site-packages/keeper_secrets_manager_ansible/plugins/action_plugins
ANSIBLE_LOOKUP_PLUGINS=...site-packages/keeper_secrets_manager_ansible/plugins/lookup_plugins

Those paths can be used in your ansible.cfg.

[defaults]
action_plugins = ...site-packages/keeper_secrets_manager_ansible/plugins/action_plugins
lookup_plugins = ...site-packages/keeper_secrets_manager_ansible/plugins/lookup_plugins

Generate a Config File

Prior to proceeding with this guide, make sure you meet all the prerequisites and have the following:

• KSM Application and it's One-Time Access Token

• Keeper Ansible module installed

In order to use the Ansible plugin for Keeper Secrets Manager, a Keeper config file is required. Once you have a config file, the configuration values can be placed into the Ansible variable files. These variable files can be encrypted with Ansible vault.

Using the Keeper Ansible module and the generated One-Time Access Token, generate a Configuration file:

$ keeper_ansible --token XX:XXXXXX
Config file create at location client-config.json

This will generate the Keeper JSON configuration file in the current directory.

If you do not have your Python module bin path added your PATH environment variable, you can create a config with the following command.

$ python3 -m keeper_secrets_manager_ansible --token XX:XXXXXX
Config file create at location client-config.json

The default name for the JSON configuration file is client-config.json. The content of the file will look like the following:

{
    "appKey" : "XXXXXXXX",
    "appOwnerPublicKey": "XXXXXXX",
    "clientId": "XXXXXXXX",
    "hostname": "XXXXX",
    "privateKey": "XXXXXXXX",
    "serverPublicKeyId": "XX"
}

This config file allows your Ansible playbook to authenticate and retrieve designated secrets from the vault.

Ansible Variables

The Keeper Secrets Manager plugins can use multiple configuration methods. For example, the Base64 encode configuration can be used.

---
keeper_config: U09NRVRFc2R ... GFzZGFzZGFzZHNhWFQK==

Ansible can use the client-config.json config file directly. It can be specified in the Ansible variables using the keeper_config_file variable key.

---
keeper_config_file: /path/to/client-config.json

Another solution is to place the values in your client-config.json file into an Ansible variable file. For example, the values can be placed into the group_vars, host_vars, or in the task files:

---
keeper_app_key: XXXXX
keeper_client_id: XXXXX
keeper_token: XXXXX
keeper_private_key: XXXXX
keeper_app_owner_public_key: XXXXX
keeper_server_public_key_id: XX

For security, the group_vars or host_vars files can be encrypted with ansible-vault.

A list of valid Ansible Variables for the Keeper plugin are below:

Command Line Variables

As an optional method, values can be passed in through the ansible-playbook command. Example:

$ ansible-playbook my_playbook.yml \
    -e "keeper_app_key=XXXXX" \
    -e "keeper_client_id=XXXXX" \
    -e "keeper_token=XXXXX" \
    -e "keeper_private_key=XXXXX"

Ansible Plugin Usage

There are three Keeper action plugins and one lookup plugin.

For all the plugins, the following arguments are used. Either the uid or title is required.

• uid - The Record UID of the desired record.

• title - The Record Title of the desired record.

• field - Retrieve the value with specified label from the record.

• custom_field - Retrieve the value with the specific custom field name.

• file - Retrieve the file with the specified name from the record.

The uid value is required, and you need either field or file populated.

Actions can either use Keeper Notation or the record UID or Title, combined with the task attributes array_index and value_key to get a specific value.

For example, a complex value like Phone number is an array of objects.

[
    {
        'number': '(555) 123-1234', 
        'type': 'Work', 
        'ext': '11'
    }, 
    {
        'region': 'AD', 
        'number': '111-2223333', 
        'ext': '5555', 
        'type': 'Mobile'
    }
]

The example, below is show how to use Keeper Notation and array_index and value_key to get the same result.

---
- name: Keeper Get
  hosts: my_hosts
  # Include line below if installed via ansible galaxy or use long plugin names.
  # collections: 
  #   - keepersecurity.keeper_secrets_manager
  
  tasks:
    - name: Get the second phone number using Keeper Notation
      keeper_get:
        notation: "RECORD UID/field/phone[1][number]"
      register: second_number_notation
      
    - name: Get the second phone number using array_index and value_key
      keeper_get:
        uid: "RECORD UID"
        field: phone
        array_index: 1
        value_key: "number"
      register: second_number_non_notation

Plugin: keeper_cache_records

The plugin keeper_cache_records is used to retrieve a select amount of records to be stored in a cache. The cache can then be used by other actions. This is used to reduce the number of API calls by getting all required record up front.

---
- name: Cache records
  hosts: my_hosts
  # Include line below if installed via ansible galaxy or use long plugin names.
  # collections: 
  #   - keepersecurity.keeper_secrets_manager
  
  tasks:
    - name: Generate a Keeper Record Cache secret
      keeper_password:
        length: 64
      register: keeper_record_cache_secret
      no_log: True

    - name: Store the Keeper Record Cache secret into variables.
      set_fact:
        keeper_record_cache_secret: "{{ keeper_record_cache_secret.password }}"
      no_log: True
      
    - name: Cache records. Will use keeper_record_cache_secret from above.
      keeper_cache_records:
        uids:
          - RECORD UID
          - RECORD UID
        titles:
          - My Record Title
          - My Record Title Too
      register: my_records
      no_log: True
        
    - name: Copy a file
      keeper_copy:
        cache: "{{ my_records.cache }}"
        uid: RECORD UID
        file: my_cert_file.crt
        dest: /etc/special.crt
        owner: root
        group: root
        mode: "0644"
        backup: yes

The records can be retrieved by the record UID or by the record title. The result of the action is an encrypted serialization of the records. The result should be stored in Ansible by using the register variable so it can be used by other actions. The encrypted serialization of the records can be quite long. For security and reducing log noise, it is recommended to set no_log to True.

keeper_cache_records caches records only. It does not cache attached files. If an action attempts to retrieve an attached file from a record that came from the cache, an API call will be made to download the file.

Use templating to set the attributes in other actions. For example cache: "{{ my_records.cache }}"

keeper_cache_records requires the keeper_record_cache_secret to be set. This can be done in the host, group, task variables, or generated in a task and then set as a fact (variable). In the example above, the keeper_password action is used to generate a password which is then stored as keeper_record_cache_secret. The no_log attribute is set to True to prevent the secret from being logged.

The cache will not update. The cache will not contain records created or updated after it has been generated. To get new records or changes in the cache, keeper_cache_records will need to be called again.

Required Attributes

• uids - A list of Keeper Vault record UID.

• titles - A list of titles of Keeper Vault records.

The attributes uids and titles can be used at the same time. At least one of them needs to be set.

Plugin: keeper_copy

The plugin keeper_copy is an extension of the built-in copy plugin. Example:

---
- name: Keeper Copy
  hosts: my_hosts
  # Include line below if installed via ansible galaxy or use long plugin names.
  # collections: 
  #   - keepersecurity.keeper_secrets_manager
  
  tasks:
    - name: Copy a password.
      keeper_copy:
        uid: RECORD UID
        field: password
        dest: /tmp/my_password
        mode: "0600"

    - name: Copy a file
      keeper_copy:
        uid: RECORD UID
        file: my_cert_file.crt
        dest: /etc/special.crt
        owner: root
        group: root
        mode: "0644"
        backup: yes

In the examples, a password will be copied from the Keeper vault record and stored in the file /tmp/my_password on the remote system. It will use the Ansbile built-in copy plugin's mode attributes to changed the permissions of the file.

The last task example from above, the file "my_cert_file.crt" will be coped from the Keeper vault record and stored at the location "/tmp/special.crt". Several of the built-in copy plugin functions will be applied to the file.

Required Attributes

• uid - A Keeper Vault record UID.

• title - Title of a Keeper Vault records.

• notation - Use Keeper Notation to get the field from a record.

The attributes uids and titles can be used at the same time. At least one of them needs to be set.

Optional Attributes

• cache - The record cache from the keeper_cache_records action.

• field - Get the content from the standard Keeper Vault record.

• custom_field - Get the content from the custom Keeper Vault record.

• file - Get the content from the files attach to the Keeper Vault record by file title.

• array_index - Defaults to 0. If the field value contains multiple values, this attribute will allow you to select which item to return. The first item will have the array_index of 0, and the next will be 1, etc.

• value_key - If the field value is a complex object, this will allow you to select the key of the key/value pair to return.

Additional optional attributes are the same as the built-in copy plugin attributes. The attributes src, remote_src, and content are not allowed and will be ignored.

Plugin: keeper_get

The plugin keeper_get will retrieve a field or file from a Keeper vault record. Example:

---
- name: Keeper Get
  hosts: my_hosts
  # Include line below if installed via ansible galaxy or use long plugin names.
  # collections: 
  #   - keepersecurity.keeper_secrets_manager
  
  tasks:
    - name: Get login name. Loading record from Keeper Vault.
      keeper_get:
        uid: RECORD UID
        field: login
      register: my_login
      
    - name: Print login name
      debug:
        var: my_login.value
        verbosity: 0
        
    - name: Make a sudoer
      copy:
        dest: "/etc/sudoers.d/{{ my_login.value }}"
        content: |
          # Auto added by Ansible
          {{ my_login.value }} ALL=(ALL:ALL) ALL

The keeper_get plugin returns a dictionary. The key "value" in the dictionary will contain the desired field or file content. This plugin is normally paired with the Ansible register instruction and the returned value is stored in memory so it can be accessed by other tasks.

In the example above, a record containing user's login name is retrieved. The login name is then stored under the name my_login. The second task will print the login name to your console for debug purposes. The third task will add a sudoer file for the login name with ability to execute all applications.

Required Attributes

• uid - A Keeper Vault record UID.

• title - Title of a Keeper Vault records.

• notation - Use Keeper Notation to get the field from a record.

The attributes uids and titles can be used at the same time. At least one of them needs to be set.

Optional Attributes

• cache - The record cache from the keeper_cache_records action.

• field - Get the value from the standard Keeper Vault record.

• custom_field - Get the value from the custom Keeper Vault record.

• file - Get the value from the files attach to the Keeper Vault record by file title.

• allow_array - By default is False. If set to True, an array of values will be returned. This is needed if the field contains multiple values such as Phone numbers. If True, array_index and value_key will be ignored.

• array_index - Defaults to 0. If the field value contains multiple values, this attribute will allow you to select which item to return. The first item will have the array_index of 0, and the next will be 1, etc.

• value_key - If the field value is a complex object, this will allow you to select the key of the key/value pair to return.

Plugin: keeper_get_record

The plugin keeper_get_record will retrieve all the fields in the record and return them in a dictionary. Example:

---
- name: Keeper Get Record
  hosts: my_hosts
  # Include line below if installed via ansible galaxy or use long plugin names.
  # collections: 
  #   - keepersecurity.keeper_secrets_manager
  
  tasks:
    - name: Get a record from the vault.
      keeper_get_record:
        uid: RECORD UID
        allow:
          - login
          - password
      register: my_record
      
    - name: Print login name
      debug:
        var: my_record.record.login[0]
        verbosity: 0

The keeper_get_record plugin returns a dictionary. The keys of the dictionary are the normalized field labels, or types. The keys will be alphanumeric and the underscore characters. If there are duplicate key, a number will be appended to the end of the key.

In the example above, a record is retrieved using the UID. The fields will be stored in a dictionary, in memory, using the register instruction. Since the allow attribute is used, the dictionary will only contain login and password .The field values can be accessed using the normal the templating in Ansible. The values will be stored as arrays. This is due to some fields returning arrays of the values, such as phone.

Required Attributes

• uid - A Keeper Vault record UID.

• title - Title of a Keeper Vault records.

Either uids and titles is required.

Optional Attributes

• cache - The record cache from the keeper_cache_records action.

• allow - A list of keys to allow. If set, if the key is not in the list, it will not be inclued in the dictionary.

Plugin: keeper_set

The keeper_set plugin has the ability to write a value into an existing Keeper vault record. Example:

___
- name: Keeper Set
  hosts: my_hosts
  # Include line below if installed via ansible galaxy or use long plugin names.
  # collections: 
  #   - keepersecurity.keeper_secrets_manager
  
  tasks:
    - name: Get login name of new user.
      keeper_get:
        uid: RECORD UID
        field: login
      register: my_login
      
    - name: Add new user of remote machine.
      user:
        name: "{{ my_login.value }}"
        comment: "User {{ my_login.value }}"
      register: new_user
        
    - name: Update record with user's home directory in the Keeper Vault
      keeper_set:
        uid: RECORD UID
        custom_field: my_home_directory
        value: "{{ new_user.home }}"

In this example, a new user's login name is retreived. The new user is created on the remote system with the login name from the record. The home directory on the remote machine is then updated in the record.

The keeper_set action does not have the ability of set individual values of an array or complex values. It simplely replaces the existing value with a new value. For example, for a Hostname and Port field type there is no way to just update the port. The entire value including the hostName needs to be included in the object value.

keeper_set will set the update the record in the vault. It will not update the cache, if used. To update the cache, a step will need to run the keeper_cache_records action again with the UID or Title of the record that was updated.

Required Attributes

• uid - A Keeper Vault record UID.

• title - Title of a Keeper Vault records.

• notation - Use Keeper Notation to get the field from a record.

The attributes uids and titles can be used at the same time. At least one of them needs to be set.

Optional Attributes

• cache - The record cache. Used for getting the record, will not update the cache.

• field - Update the existing standard Keeper Vault record field.

• custom_field - Update the existing custom Keeper Vault record field.

Plugin: keeper_create

The keeper_create plugin creates a record in the Keeper vault. See the Field/Record Types document for available record types, and the field types used to build the records. The action plugin will return the record_uid upon successful creation.

Example:

---
- name: Keeper Create
  hosts: my_hosts
  
  tasks:
    - name: "Create A Record"
      keeper_create:
        shared_folder_uid: XXXXXX
        record_type: login
        generate_password: True
        password_complexity:
          length: 64
          allow_symbols: False
        title: "My New Record"
        note: "Created by Ansible"
        fields:
          - type: login
            value: johndoe@localhost
          - type: url
            value: https://localhost
        custom_fields:
          - type: text
            label: "My Custom Label"
            value: "My custom value"
      register: my_new_record

    - name: "New Record UID"
      debug:
        msg: "New record uid is {{ my_new_record.record_uid }}"

The following fields are required.

• shared_folder_uid - The Shared Folder UID from the vault. The record will be created within this folder.

• record_type - The type of record. This will included all the default record types. If the keeper_record_types is set, those record types can be used.

• title - The title of record

The following fields are optional.

• generate_password - If set to true, any password field where the password has not been set, will be populated with a random generated password.

• password_complexity - Sets the complexity of the password. All parameters of password_complexity are optional.

  • length - Length of password. Defaults to 64.

  • allow_lowercase - Defaults to True. If set to False, no lowercase letters will be used.

  • allow_uppercase - Defaults to True. If set to False, no uppercase letters will be used.

  • allow_digits - Defaults to True. If set to False, no digits will be used.

  • allow_symbols - Defaults to True. If set to False, no symbols will be used.

  • filter_characters - A list of characters to exclude from the password. This allows to remove characters a services will reject. For example, '%' in SQL. If not set, the password will not be filtered.

• notes - Attach a note to the record.

Based on the Record Types, certain fields maybe required. Custom fields are optional. Both fields and custom_fields are an array of values.

• fields/custom_fields

  • type - Field type

  • label - Label to display with the value.

  • value - Field value. Can be a string or dictionary based on field type.

Creating Custom Record Types

To create a record with a particular Custom Record Type, first export the custom record types using Keeper Commander and the record-type-info command. KSM does not sync down the custom type definitions, so this must be added directly to the playbook as a variable.

Keeper Commander will output a JSON Array ("content"). Only the JSON object is required.

Example:

My Vault> record-type-info --format json -lr "My Custom"
[
  {
    "recordTypeId": 18,
    "content": "{\"$id\":\"My Custom\",\"categories\":[\"login\"],
      \"description\":\"SSH key template\",\"fields\":[
        {\"$ref\":\"login\"},
        {\"$ref\":\"keyPair\"},
        {\"$ref\":\"password\",\"label\":\"passphrase\"},
        {\"$ref\":\"host\"},
        {\"$ref\":\"fileRef\"}]}"
  }
]

In your Ansible YAML file, add the value of the "content" object to the variable key called keeper_record_types. The variable is an array, and the JSON is to be treated as a string value. The pipe, after the array item, will treat the following JSON as a string. The variable will accept multiple record types.

Example:

- name: My Playbook
  collections:
   - keepersecurity.keeper_secrets_manager
  hosts: "my_hosts"
  vars:
    keeper_record_types:
      - |
        {
          "recordTypeId": 35,
          "content": "{\"$id\":\"My Custom\",\"fields\":[{\"$ref\":\"fileRef\",\"label\":\"File or Photo\"},{\"$ref\":\"login\",\"label\":\"Login\"},{\"$ref\":\"password\",\"label\":\"Password\",\"required\":true,\"enforceGeneration\":false,\"privacyScreen\":false,\"complexity\":{\"length\":8,\"caps\":0,\"lowercase\":0,\"digits\":0,\"special\":0}},{\"$ref\":\"text\",\"label\":\"System Login\",\"required\":true},{\"$ref\":\"secret\",\"label\":\"System Password / Pin Code\"},{\"$ref\":\"url\",\"label\":\"Keeper VPN Wiki\",\"required\":true},{\"$ref\":\"url\",\"label\":\"Password Best Practices FAQ's and Tips\",\"required\":true}]}"
        }

To check if this worked, the keeper_info plugin can be used to show which record types are available.

When creating a record of a particular custom type, the Ansible task will reference the record type name in the record_type parameter as seen below:

- name: "Create A Custom Record"
      keeper_create:
        shared_folder_uid: XXXXXXXXXXXX
        record_type: "My Custom"
        title: "Example Custom Record"
        note: "Created by Ansible"
        fields:
          - type: login
            label: Login
            value: johndoe@localhost
          - type: password
            label: Password
            value: "ABC123"
      register: my_new_record

Plugin: keeper_remove

v1.2.1 Released on: 10/27/2023

The keeper_remove plugin will remove a record from the Keeper vault.

---
- name: Keeper Remove
  hosts: my_hosts
  
  tasks:
    - name: Remove by UID
      keeper_remove:
        uid: RECORD UID
        
    - name: Remove by Title
      keeper_remove:
        title: RECORD TITLE
     

Required Attributes

• uid - A Keeper Vault record UID.

• title - Title of a Keeper Vault records.

The attributes uid and title cannot be used at the same time. At least one of them needs to be set.

Optional Attributes

• cache - The record cache from the keeper_cache_records action. The record will not be removed from the cache. The cache will be used for looking up the record title.

Plugin: keeper_password

The keeper_password plugin will generate a random password. The action plugin will return the password.

Example:

---
- name: Keeper Password
  hosts: my_hosts
  
  tasks:
    - name: Generate a long password
      keeper_password:
        length: 128
      register: long_password
    - name: Show long password
      debug:
        msg: "Long password {{ long_password.password }}"
        
    - name: Generate an all digit password
      keeper_password:
        length: 32
        allow_lowercase: False
        allow_uppercase: False
        allow_symbols: False
      register: digit_password
    - name: Show digit password
      debug:
        msg: "Digit password {{ digit_password.password }}"
        
    - name: Generate a PostgreSQL password (no % character)
      keeper_password:
        length: 64
        filter_characters: 
          - "%"
      register: pg_password
    - name: Show PostgreSQL password
      debug:
        msg: "PG password {{ pg_password.password }}"    

All parameters are optional. If no parameters are set, the defaults will be used.

• length - Length of password. Defaults to 64.

• allow_lowercase - Defaults to True. If set to False, no lowercase letters will be used.

• allow_uppercase - Defaults to True. If set to False, no uppercase letters will be used.

• allow_digits - Defaults to True. If set to False, no digits will be used.

• allow_symbols - Defaults to True. If set to False, no symbols will be used.

• filter_characters - A list of characters to exclude from the password. This allows to remove characters a services will reject. For example, '%' in SQL. If not set, the password will not be filtered.

Based of record types, certain fields maybe required. Custom fields are optional. Both fields and custom_field are an array of values.

Plugin: keeper_lookup

The keeper_lookup plugin retrieves a field from the Keeper vault record and inserts the value into a text string. Example:

---
- name: Keeper Lookup
  hosts: my_hosts
  
  tasks:
    - name: Write login to file. Get record from the Keeper Vault
      copy:
        content: "My login is {{ lookup('keeper', uid='RECORD UID', field='login') }}"
        dest: "/tmp/my_login.txt"
      no_log: True
      
    - name: Using the array_index and value_key on complex values
      debug:
        msg: >-
          Second phone number is 
          {{ lookup('keeper', uid='RECORD UID', custom_field='My Phone', array_index=1, value_key='number') }}
 

In the example above, the first task the content of a file is created by templating the login name of a user from a Keeper record.

The second task displays as debug the second phone of number from a field with a complex value using the array_index and value_key task attributes. An array_index starts at 0, the next item in the araray will be 1, the next is 2, a so on. The value_key is the name of key in a key/pair dictionary.

Required Attributes

• uid - A Keeper Vault record UID.

• title - Title of a Keeper Vault records.

• notation - Use Keeper Notation to get the field from a record.

The attributes uids and titles can be used at the same time. At least one of them needs to be set.

Optional Attributes

• cache - The record cache. Used for getting multiple records, will not update the cache.

• field - Update the existing standard Keeper Vault record field.

• custom_field - Update the existing custom Keeper Vault record field.

• file - Get the value from the files attach to the Keeper Vault record by file title.

• allow_array - By default is False. If set to True, an array of values will be returned. This is needed if the field contains multiple values such as Phone numbers. If True, array_index and value_key will be ignored.

• array_index - Defaults to 0. If the field value contains multiple values, this attribute will allow you to select which item to return. The first item will have the array_index of 0, and the next will be 1, etc.

• value_key - If the field value is a complex object, this will allow you to select the key of the key/value pair to return.

Important Notes

• To avoid leaking secret values when using the lookup plugin, add 'no_log: True' to the task. The stdout information will not be logged if the value is True.

• If the plugin was installed by Ansible Galaxy the longer name is required for the lookup plugin (i.e. keepersecurity.keeper_secrets_manager.keeper). Listing collections appears not to work with lookup plugins.

• To find out what fields and custom fields are available for a specific vault secret, use the Keeper Secrets Manager CLI "ksm secret get -u XXXX" command. More info here.

Plugin: keeper_init

The keeper_init plugin initialize a configuration from a one time access token. This is similar to the keeper_ansible --keeper_token command. The plugin accepts the following options.

• token - The one time access token. It's best to template this value and pass in the value.

• filename - The configuration file name to generate with config values. If not included, the configuration will not be created.

• show_config - A flag to indicate if the configuration values should be returned in the task log. By default this is False. Only set to True if you are unable to generate the configuration via other methods or do not have access to a generated configuration file. If True, the configuration will be logged. This might not be a problem if running the playbook via the command line, however if running via Ansible Tower to will be log file which is retained.

---
- name: Keeper Lookup
  hosts: localhost
  connection: local
  
  tasks:
    - name: Init the one time access token
      keeper_init:
        token: "{{ keeper_token }}"
        filename: "{{ keeper_config_file }}"
        show_config: False

It's best not to hard code the token into the playbook since it's only good once. The token and the configuration file name can be passed into the playbook using the extra vars.

$ ansible-playbook my_init_playbook.yml \
  -e "keeper_token=US:XXX" \
  -e "keeper_config_file=my_keeper_config.yml"

The above will generate a file similar to the one below. The content of the file can be copied into a configuration file used by ansible, and optionally encrypted by ansible-vault.

keeper_app_key: +U5Ja ... 5FmXymVI=
keeper_client_id: Fokc ... WBdUPxPlBwzAKlMUgFZHqLg==
keeper_hostname: US
keeper_private_key: MIGHA ... yA7Oy
keeper_server_public_key_id: '10'

Ansible Galaxy Role

If the Keeper Secret Manager plugins were installed via Ansible Galaxy, a role called keeper_init_token was installed to initialize the one-time access token. This role can be used in a playbook.

---
- name: Initialize One Time Access Token
  hosts: localhost
  connection: local
  collections: keepersecurity.keeper_secrets_manager

  roles:
    - keeper_init_token

The role will use the following options set via extra variables.

• keeper_token - Required one-time access token.

• keeper_config_file - Generate a file containing the configuration. If not set, no file will be created.

• keeper_show_config = Default False. If set to True, it will show the config in the log if verbosity is enabled.

Either keeper_config_file or keeper_show_config should be used, else the token will initialize and you will not be able to view the resulting configuration.

Plugin: keeper_info

The keeper_info action will display information about the Keeper ansible plugin. The results include a list of record types, field types, and versions of Python modules. In order to see the results, the verbosity level needed to be set at 1 or higher.

---
- name: Keeper Info
  hosts: localhost
  connection: local
  
  tasks:
    - name: Display Keeper Info
      keeper_info:

This can be used to verify custom record types are being picked up by the plugins.

Plugin: keeper_cleanup

The keeper_cleanup plugin is used to clean up any files created by the keeper plugins. This is mainly used to delete a cache file, if you are using it. Disaster Recovey cache files are used when there are network problems as a fall back to get records. If you are running Ansible secret environment, there is no need to remove the Disaster Recovey cache. However this plugin gives you the ability to do so.

- name: Keeper Lookup
  hosts: localhost
  connection: local
  vars:
    keeper_use_cache: True
  
  tasks:
    ... bunch of tasks
    
    - name: Remove the cache file
      keeper_cleanup:
    

Plugin: keeper_redact

The keeper_redact stdout callback plugin is used to redact secrets from the standard out logs. This will work for the keeper_redact stdout callback plugin is used to redact secrets from the standard out logs. This will work for the keeper_copy and keeper_get plugins. It will not redact secret values for keeper_lookup. For keeper_lookup, use the no_log: True directive.

To use the keeper_redact plugin, enable it in your ansible.cfg.

[defaults]
stdout_callback = keeper_redact
# Use long name if install via Ansible Galaxy
# stdout_callback = keepersecurity.keeper_secrets_manager.keeper_redact

For example, the following task would return all the phone numbers in the custom field MyPhoneNumbers and place them into the variable phone_numbers.

    - name: "Get Phone Numbers"
      keeper_get:
        uid: OlLZ6JLjnyMOS3CiIPHBjw
        custom_field: MyPhoneNumbers
        allow_array: True
      register: phone_numbers

If the playbook was run with any verbosity, the values being placed into the variable would be displayed. This would leak the secrets to the log. If the keeper_redact stdout callback plugin is enabled, the values in the log would be redacted.

TASK [Get Phone Numbers] **************************************************
ok: [my_server] => {
    "value": [
        {
            "number": "****",
            "type": "****",
            "ext": "****"
        },
        {
            "region": "****",
            "number": "****",
            "ext": "****",
            "type": "****"
        }
    ],
    "changed": false
}

Ansible Vault Password Retrieval

You can use the Keeper Secret Manager CLI ("ksm") to provide the decryption password for your Ansible vaults. This is done using the ANSIBLE_VAULT_PASSWORD_FILE environment variable or the vault_password_file in the ansible.cfg field to specify an executable file that will return a password.

A executable shell script can be created that returns the password using the "ksm" secret notation (learn more about ksm secret notation). For example, the below script will output a specific secret password for the given Record UID:

#!/bin/sh
ksm secret notation keeper://XXXX/field/password

Replace XXXX with the Vault Record UID. Running this script simply outputs the secret password.

To override the environmental variable "ANSIBLE_VAULT_PASSWORD_FILE", execute the following, replacing /path/to/script with the location of the above script.

$ ANSIBLE_VAULT_PASSWORD_FILE=/path/to/script.sh ansible-playbook playbook_with_vault.yml

Now, when Ansible needs to decrypt any vaults used by playbook_with_vault.yml, it will execute that shell script. The shell script will retrieve the password from the Keeper Vault.

Logging

By default, the Ansible plugins will only display errors. If you use the Ansible verbosity level, different SDK logging will be displayed. An Ansible verbosity level of -v will display any SDK messages INFO and higher, while a verbosity level of -vvv will display any SDK messages DEBUG and higher.

Troubleshooting

__NSPlaceholderDate in progress in another thread when fork() called error.

This appears to be specific to Ansible running on MacOS. While running a playbook you may get the following error:

objc[6763]: +[__NSPlaceholderDate initialize] may have been in progress in 
another thread when fork() was called. We cannot safely call it or ignore 
it in the fork() child process. Crashing instead. Set a breakpoint on 
objc_initializeAfterForkError to debug

This is known problem with Ansible. This can be fixed with the following environmental variable.

OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES ansible-playbook ...

Missing Configuration file

TASK [Copy file from Keeper into the file] ********************************************************************************************
An exception occurred during task execution. To see the full traceback, use -vvv. The error was: Exception: Keeper Ansible error: There is no config file and the Ansible variable contain no config keys. Will not be able to connect to the Keeper server.
fatal: [localhost]: FAILED! => {"msg": "Unexpected failure during module execution.", "stdout": ""}

Features

• Store Secrets Manager configurations securely in Ansible Tower

• Use Ansible Tower to manager and launch Ansible projects utilizing the Secrets Manager Ansible plugin which features:

  • Retrieving secrets from the Keeper vault to use in Ansible Playbooks

  • Updating the value of secrets in the Keeper Vault from Ansible

  • Copying files from the Keeper Vault

KSM Configuration

The first step in using Ansible Tower with Keeper Secrets Manager is to get and initialize a Base64 configuration. The Secret Manager Configuration document will explain how to get a configuration using the Keeper Secret Manager CLI or Commander CLI.

Using Commander CLI, add a new device can generate a Base64 configuration without using a one time access token.

keeper secrets-manager client add --app MyApp --config-init b64

The Keeper Secrets Manager CLI requires a one-time access token. This can be obtained from the Web Vault by adding a new device to an application.

$ ksm init default US:XXXX

Another way using the keeper_init_token role included in the Keeper Secrets Manager collection, which can used after Ansible Tower is setup. An example will appear at the end of this document.

The Base64 configuration can be added to the inventories, hosts, or templates variables sections. It can also be added to the playbook repository as an Ansible secret. The variable name is keeper_config.

Vault Credential

With the Base64 KSM configuration we need to create a vault credential. Under the Resources menu, select Credentials and click Add.

Give your Vault Credential a name, select Vault from the Credential Type drop-down, type in the password that was used to encrypt the secrets.yml file into the Vault Password field, then click Save.

The credential will be used when the Template is setup.

Execution Environment

To use the Keeper Secrets Manager plugins in Ansible Tower an Execution Environment containing the Keeper Secrets Manager SDK is required. This SDK is included in the Docker image keeper/keeper-secrets-manager-tower-ee. In your instance of Ansible Tower, select Execution Environment in the Administration menu, then click Add.

The Image value is docker.io/keeper/keeper-secrets-manager-tower-ee:latest or docker.io/keeper/keeper-secrets-manager-tower-ee:<tag> if there is a specific tag version.

The value for Pull should be set to Always pull container before running is you are using the latest tag. If you pin the tag to a specific tag version of keeper/keeper-secrets-manager-tower-ee then set the value to Only pull the image if not present before running.

Projects

Playbook Repository

Using the Keeper Security Manager collection from Ansible Galaxy

To use the Keeper Secrets Manager plugins in your projects, create a collections directory in your source repository, if one does not already exists. Then create, or add to, the file requirements.yml the following value.

---
collections:
  - keepersecurity.keeper_secrets_manager

Storing the KSM Configuration

The Base64 KSM configuration can be stored in numerous places inside of Ansible Tower like in the inventories, hosts, and templates. The configuration is encrypted when stored in these locations.

For this project, the KSM configuration will be stored as an encrypted secret in the source repository. Add a YAML file called secrets.yml in a directory called defaults located in the root directory of the repository.

In this file add a key called keeper_config with the Base64 configuration as it's value.

---
keeper_config: ewogICAgImNsaWVudElk ... Y0tleUlkIjogIjEwIgp9

Then encrypt the secrets.yml file using ansible-vault.

$ ansible-vault encrypt secret.yml
New Vault password:
Confirm New Vault password:
Encryption successful

At this point, if you look at your secrets.yml file, it should be encrypted.

Playbook

The directory structure should look like the following.

$ tree
.
├── collections
│   └── requirements.yml
├── defaults
│   └── secrets.yml
├── playbook_1.yml
└── playbook_2.yml

For our playbooks, the Keeper Secrets Manager collection is added to the playbook collections. The first task is to include the secrets.yml using the built-in action include_vars. That task also includes no_log: True to prevent the KSM configuration from being logged. This task needs to be performed before any of the plugins from the Keeper Secrets Manager collection.

---
- name: Playbook One
  hosts: all
  collections: 
    - keepersecurity.keeper_secrets_manager

  tasks:
    - include_vars:
        file: "defaults/secrets.yml"
      no_log: True

    - name: "Make User SSH Directory, if does not exists"
      file:
        path: "/home/user/.ssh"
        state: directory
        recurse: yes

    - name: "Copy SSH Keys"
      keeper_copy:
        notation: "OlLZ6JLjnyMOS3CiIPHBjw/field/keyPair[{{ item.notation_key }}]"
        dest: "/home/user/.ssh/{{ item.filename }}"
        mode: "0600"
      loop:
        - { notation_key: "privateKey", filename: "id_rsa" }
        - { notation_key: "publicKey",  filename: "id_rsa.pub" }

Project

Once you have added the collection to your source repository, a new Project can be created.

Make sure to select the Execution Environment that you create that uses the keeper/keeper-secrets-manager-tower-ee image.

In the example above, the source repository was Git with the appropriate details. Your company may use a different source control.

After it is saved, sync the playbooks to your Ansible Tower instance.

Template

In your instance of Ansible Tower, select Templates in the Resources menu, then click Add.

For Projects select the project that was just created that contain the playbooks. For Execution Environment select the execution environment what contains the Keeper Secrets Manager Tower EE docker image. For Playbook select a playbook from your source repository.

For Credentials select the Vault credential that will be used to decrypt the secrets.yml file in the Project's source repository. You can also select the credential to use for connection to your inventory servers.

Finish by clicking the Save button at the bottom of the page.

Launching a Template

The last step is to launch a template to create a job.

The include_vars task will import the KSM Base64 Configuration and decrypt it. The no_log: True will hide the configuration from the log. If it is not included, the configuration will be logged and viewable by anyone who has access to Ansible Tower.

With the configuration now in the available variables, the keeper_copy action can retrieve the public and private SSH key from the Keeper Vault and copy them into location on the remote machine.

About

By default, the AWS CLI uses credentials stored in plaintext in ~/.aws/credentials. With this credential process, you can now use the Keeper Vault to store your AWS credentials, removing the need to have them on disk.

Instead, AWS will use this executable to securely fetch your AWS credential from your Vault using the Keeper Secrets Manager (KSM).

Features

• Use a vaulted AWS Access Key to authenticate to the AWS CLI.

Prerequisites

In order to utilize this integration, you will need:

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

  • Secrets Manager add-on enabled for your Keeper account

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

• A Keeper Secrets Manager Application with an Access Key shared to it

  • See the Quick Start Guide for instructions on creating an Application

• An initialized Keeper Secrets Manager Configuration

  • This integration only accepts JSON format configurations

• The AWS CLI v2 installed

Setup

Vault

The first step in the setup of the integration is to add you AWS Access Key ID and your Secret Access Key to a record in your Vault. There is no built-in record type for this kind of secret; however, you can create a custom record for this purpose alone.

Note: Field names are case-sensitive.

Once you have created your custom field, you can now use it to create a record for your AWS Access Key. This record should be stored in a shared folder that your KSM application has permission to access.

Once safely stored, you can delete the Access Key credentials from your AWS credential file.

KSM

The integration expects a KSM Application Configuration file at either .config/keeper/aws-credential-process.json or aws-credential-process.json relative to the user's home directory. It must have access to a Shared Folder containing the required AWS Access key.

For help in obtaining a KSM configuration in JSON format, follow these instructions. After creating a new device get corresponding config.json and copy it into user's home folder as aws-credential-process.json

AWS Config

Download the latest version of the keeper-aws-credential-process executable from the GitHub releases page and store that in a convenient location.

Now in your AWS configuration file, which is usually located at ~/.aws/config, add the following line to any profile you are using via the CLI.

# Add the UID for your AWS Access Key
#credential_process = /path/to/keeper-aws-credential-process --uid <Record UID>
credential_process = /opt/keeper-aws-credential-process-v0.1.1_linux_amd64  --uid <Record UID>

Usage

Once configured as above, the AWS CLI will automatically fetch your authentication credential from the Keeper Vault. You can test that it works by using any CLI command in which you have an appropriate IAM role for, such as:

# List all s3 buckets
aws s3 ls

If the command completes without error, congratulations, you are now fully set up.

Feature Request / Report an Issue

This Credential Process is open source and can be found on GitHub. If you need to report a bug or would like to request a feature to support more authentication use cases, please create a GitHub issue.

About

The Keeper Secrets Manager CLI tool sync command allows you to push secrets from the Keeper Vault to a target AWS Secrets Manager account, overwriting the existing values in the target location. This allows the Keeper Vault to be the single source of truth for any services or scripts in AWS that utilize AWS Secrets Manager.

Features

• Use secrets from the Keeper Vault as the source of truth for AWS Secrets Manager

• Seamlessly start using secrets from the Keeper Vault with your existing AWS scripts and services

Prerequisites

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

  • Secrets Manager add-on enabled for your Keeper subscription

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

• A Keeper Secrets Manager Application with secrets shared to it

  • See the Quick Start Guide for instructions on creating an Application

• An AWS account with AWS Secrets Manager, and the ability to create IAM security credentials

Setup

1. Configure Keeper Secrets Manager CLI

To configure the KSM CLI tool, a profile needs to be created with the Keeper Secrets Manager One Time Access Token.

The simplest way to do this is to initialize the default profile with the following command:

ksm profile init <TOKEN>

For information on creating multiple profiles and other options, see the profile documentation

2. Set AWS Permissions

To use the KSM sync to AWS, AWS Secrets Manager requires standard IAM security credentials with SecretsManagerReadWrite enabled for the entire vault or on individual keys to sync.

arn:aws:iam::aws:policy/SecretsManagerReadWrite

See the Amazon instructions for creating Access Keys:

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html

3. Create AWS Credentials Record

The KSM CLI needs the credentials for the AWS account to set secrets. These credentials are stored in a Keeper record which the CLI tool can access using Keeper Secrets Manager.

Record fields with the following labels are required on the credentials record:

"AWS Access Key ID" "AWS Secret Access Key" "AWS Region Name"

(Method 1) Create an AWS Credentials Custom Record Type

A custom record type can be created with the required fields, which makes it easy and clean to create a record.

To create a custom record type, go to the "Custom Record Types" tab in the Keeper Vault and hit "Create Type". Create a new record type with hidden fields that have the correct field label, then click "Publish" to create the new record type.

Then simply create a new record of the AWS Credentials type and enter the details into the corresponding fields.

Make sure this new record is moved to a Shared Folder that is associated with your Secrets Manager application.

(Method 2) Add Custom Fields

To create a credentials record without creating a new record type, the required fields can be added as custom fields to a standard record.

Create a new record of any type, then add Custom Fields of the 'Hidden Field' type for each required AWS field. Click "Edit Label" to change the labels to the corresponding field name.

Then fill in each custom field and hit "Save" to save the record.

4. Create Value Mappings

The KSM CLI sync command identifies which values to set using mappings that are defined on the command call. For each mapping passed to the command, a value with the given name will be populated with the given value from the Keeper Vault.

These mappings follow this format:

--map "VALUE KEY" "KEEPER NOTATION"

VALUE KEY is the key name that the value will be assigned in AWS Secrets Manager

KEEPER NOTATION is a Keeper notation query of a value from a keeper record to set to the key

Keeper notation is a query notation used by Keeper Secrets Manager to identify specific record values. The notation follows the general format of: UID/[field|custom_field]/fieldname for example: ae3d[...]d22e/field/password

See the Keeper Notation documentation for more information

Full Mapping Example: --map "MySQL_PWD" "jd3[...]i-fd/field/password"

Multiple mappings can be added to a single sync command --map "MySQL_PWD" "jd3[...]i-fd/field/password" --map "MySQL_Login" "jd3[...]i-fd/field/login"

Run Sync

To run the sync, use the KSM CLI sync command with the credentials record and value mapping.

1. Construct the Command

Put together the KSM sync command with the AWS type. The format looks like the following:

ksm sync --type aws --credentials [UID] --map [...] --map [...]

2. Run a Dry-Run

The sync command supports running a dry-run which will identify all changes that will be made to your AWS Secrets Manager values without actually pushing the values or making changes. Use this to make sure your mapping queries are constructed properly.

ksm sync --type aws --credentials [UID] --map [...] --map [...] --dry-run

3. Run the Sync

When ready, run the sync command without the dry-run option. This will push values from your Keeper Vault to AWS Secrets Manager

ksm sync --type aws --credentials [UID] -m [...] -m [...]

Keeper Secrets Manager integrates with AWS KMS in order to provide encryption for Keeper Secrets Manager configuration files. With this integration, you can protect connection details on your machine while taking advantage of Keeper's zero-knowledge encryption of all your secret credentials.

Features

• Encrypt and Decrypt your Keeper Secrets Manager configuration files with AWS KMS

• Protect against unauthorized access to your Secrets Manager connections

• Requires only minor changes to code for immediate protection. Works with all Keeper Secrets Manager SDK functionality

Prerequisites

Setup

1. Install Module

repositories {
  mavenCentral()
}

dependencies {
  implementation("com.keepersecurity.secrets-manager:aws:1.0.0")
  implementation("com.keepersecurity.secrets-manager:core:17.0.0")
  implementation ("software.amazon.awssdk:kms:2.20.28")
  implementation ("software.amazon.awssdk:auth:2.20.28")
  implementation("com.fasterxml.jackson.core:jackson-databind:2.18.2")
  implementation("com.fasterxml.jackson.core:jackson-core:2.18.2")
  implementation("com.google.code.gson:gson:2.12.1")
  implementation("org.slf4j:slf4j-api:1.7.32"){
      exclude("org.slf4j:slf4j-log4j12")
  }
  implementation("ch.qos.logback:logback-classic:1.2.6")
  implementation("ch.qos.logback:logback-core:1.2.6")
  implementation("org.bouncycastle:bc-fips:1.0.2.4")
}

<!-- KMS-core -->
<dependency>
 <groupId>com.keepersecurity.secrets-manager</groupId>
 <artifactId>aws</artifactId>
 <version>1.0.0</version>
</dependency>
<dependency>
 <groupId>com.keepersecurity.secrets-manager</groupId>
 <artifactId>core</artifactId>
 <version>17.0.0</version>
</dependency>

<!-- aws-kms -->
   	<dependency>
   		<groupId>software.amazon.awssdk</groupId>
   		<artifactId>kms</artifactId>
   		<version>2.20.28</version>
   	</dependency>
   		
   	<!-- aws-auth -->
   	<dependency>
   		<groupId>software.amazon.awssdk</groupId>
   		<artifactId>auth</artifactId>
   		<version>2.20.28</version>
   	</dependency>
   	
   	<!--gson -->
   	<dependency>
   	    <groupId>com.google.code.gson</groupId>
   	    <artifactId>gson</artifactId>
   	    <version>2.12.1</version>
   	</dependency>

   	<!--jackson-core -->
   	<dependency>
   		<groupId>com.fasterxml.jackson.core</groupId>
   		<artifactId>jackson-core</artifactId>
   		<version>2.18.2</version>
   	</dependency>
   	
   	<!--jackson-databind -->
   	<dependency>
   		<groupId>com.fasterxml.jackson.core</groupId>
   		<artifactId>jackson-core</artifactId>
   		<version>2.18.2</version>
   	</dependency>
   	
   	<!-- slf4j-api -->
   	<dependency>
   		<groupId>org.slf4j</groupId>
   		<artifactId>slf4j-api</artifactId>
   		<version>1.7.32</version>
   		<scope>runtime</scope>
   	</dependency>

   	<!-- logback-classic -->
   	<dependency>
   		<groupId>ch.qos.logback</groupId>
   		<artifactId>logback-classic</artifactId>
   		<version>1.2.6</version>
   		<scope>compile</scope>
   	</dependency>

   	<!-- logback-core -->
   	<dependency>
   		<groupId>ch.qos.logback</groupId>
   		<artifactId>logback-core</artifactId>
   		<version>1.2.6</version>
   		<scope>compile</scope>
   	</dependency>
   	
   	<!-- bc-fips -->
   	<dependency>
   		<groupId>org.bouncycastle</groupId>
   		<artifactId>bc-fips</artifactId>
   		<version>1.0.2.4</version>
   	</dependency>
   	

npm install @keeper-security/secrets-manager-aws

pip3 install keeper-secrets-manager-storage

pip install boto3

dotnet add package Keeper.SecretsManager.AWSKeyManagement

go get github.com/keeper-security/secrets-manager-go/integrations/aws

2. Configure AWS Connection

By default the boto3 library will utilize the default connection session setup with the AWS CLI with the aws configure command. If you would like to specify the connection details, the two configuration files located at ~/.aws/config and ~/.aws/credentials can be manually edited.

Alternatively, configuration variables can be provided explicitly as an access key using the AwsSessionConfig data class and providing aws_access_key_id , aws_secret_access_key and aws_session_token variables.

3. Add AWS KMS Storage to Your Code

Once AWS connection has been configured, You can fetch the Key to encrypt / decrypt KSM configuration using integration and you need to tell the Secrets Manager SDK to utilize the KMS as storage. Using Specified Connection credentials

import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;
import com.keepersecurity.secretmanager.aws.kms.AwsKeyValueStorage;
import com.keepersecurity.secretmanager.aws.kms.AwsSessionConfig;
import com.keepersecurity.secretsManager.core.InMemoryStorage;
import com.keepersecurity.secretsManager.core.SecretsManager;
import com.keepersecurity.secretsManager.core.SecretsManagerOptions;
import static com.keepersecurity.secretsManager.core.SecretsManager.initializeStorage;

import software.amazon.awssdk.regions.Region;

import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;

class Test {
	public static void main(String args[]){
		String keyId = "<Key ID>";
		String awsAccessKeyId = "<AWS Access ID>";
		String awsSecretAccessKey = "<AWS Secret>";
		String oneTimeToken = "[One Time Token]";
		Region region = Region.<cloud-region>;
		String profile = null OR "DEFAULT";     //set profile (ex. DEFUALT/UAT/PROD) if ~/.aws/config is set
		String configFileLocation = "client_config_test.json";
		try{
			//set AWS configuration, It can be null if profile is set for aws credentials
			AwsSessionConfig sessionConfig = new AwsSessionConfig(awsAccessKeyId, awsSecretAccessKey);
			//Get Storage 
			AwsKeyValueStorage awskvstorage =  new AwsKeyValueStorage(keyId, configFileLocation, profile, null, region);
			initializeStorage(awskvstorage, oneTimeToken);
			SecretsManagerOptions options = new SecretsManagerOptions(awskvstorage);
			//getSecrets(OPTIONS);
		}catch (Exception e) {
			System.out.println(e.getMessage());
		}
	}
}

import { AWSKeyValueStorage, AWSSessionConfig, LoggerLogLevelOptions } from "@keeper-security/secrets-manager-aws";
import { initializeStorage, getSecrets } from "@keeper-security/secrets-manager-core";


const getKeeperRecordsAWS = async () => {

	const accessKeyId = "<YOUR AWS ACCESS KEY>>";
	const secretAccessKey = "<YOUR AWS SECRET_ACCESS_KEY>";
	const regionName = "<YOUR AWS REGION>";
	const logLevel = LoggerLogLevelOptions.Debug;
	const configPath = "client-config-path.json";
	
	const awsSessionConfig = new AWSSessionConfig(accessKeyId, secretAccessKey, regionName);
	const keyId = 'arn:aws:kms:ap-south-1:<accountName>:key/<keyId>';
	const storage = await new AWSKeyValueStorage(keyId, configPath, awsSessionConfig, logLevel).init();
	
	const oneTimeToken = "<one time token>";

	await initializeStorage(storage, oneTimeToken);
	const { records } = await getSecrets({ storage: storage });

	const firstRecord = records[0]
	const firstRecordPassword = firstRecord.data.fields.find(x => x.type === 'password')
	console.log(firstRecordPassword.value[0])
};
getKeeperRecordsAWS();

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_hsm.storage_aws_kms import AwsKmsKeyValueStorage
 
aws_session_cfg = AwsSessionConfig(
    aws_access_key_id="AK[...]FIF",
    aws_secret_access_key="/[...]/g3",
    region_name="us-east-2")

config = AwsKmsKeyValueStorage(
   key_id='e9[...]567',
   config_file_location='client-config.json',
   aws_session_config=aws_session_cfg)
 
secrets_manager = SecretsManager(config=config, verify_ssl_certs=True)
all_records = secrets_manager.get_secrets()

using System;
using System.Linq;
using System.Threading.Tasks;
using SecretsManager;
using AWSKeyManagement;

public class Program
{
	private static async Task getOneIndividualSecret()
	{
		var accessKeyId = "<ACCESS_KEY_ID>";
		var secretAccessKey = "<SECRET_ACCESS_KEY>";
		var regionName = "<AWS_REGION_STRING";

		var keyId = "<KEY_ID_1>";
		var path = "<KEEPER_CONFIG_FILE_PATH>";
		var dotnet_access_token = "<ONE_TIME_TOKEN>";

		var awsSessionConfig = new AWSSessionConfig(accessKeyId, secretAccessKey, regionName);

		var aws_storage = new AWSKeyValueStorage(keyId, path, awsSessionConfig);

		SecretsManagerClient.InitializeStorage(aws_storage, dotnet_access_token);

		var options = new SecretsManagerOptions(aws_storage);
		var records_1 = await SecretsManagerClient.GetSecrets(options);
		records_1.Records.ToList().ForEach(record => Console.WriteLine(record.RecordUid + " - " + record.Data.title));
	}

	static async Task Main()
	{
		await getOneIndividualSecret();
	}
}

package main

import (
	"encoding/json"
	"fmt"

	"github.com/keeper-security/secrets-manager-go/core"
	awskv "github.com/keeper-security/secrets-manager-go/integrations/aws"
)

func main() {

	clientID := "<Some Client ID>"
	clientSecret := "<Some Client Secret>"
	region := "<Cloud Region>"
	keyARN := "arn:<partition>:kms:<region>:<account-id>:key/<key-id>"
	oneTimeToken := "one time token"
	ksmConfigFileName := ""

	// Initialize the AWS Key Vault Storage
	cfg := awskv.NewAWSKeyValueStorage(ksmConfigFileName, keyARN, &awskv.AWSConfig{
		ClientID:     clientID,
		ClientSecret: clientSecret,
		Region:       region,
	})

	clientOptions := &core.ClientOptions{
		Token:  oneTimeToken,
		Config: cfg,
	}

	fmt.Printf("Client ID in config: %v\n", cfg.Get(core.KEY_CLIENT_ID))

	secrets_manager := core.NewSecretsManager(clientOptions)
	// Fetch secrets from Keeper Security Vault
	record_uids := []string{}
	records, err := secrets_manager.GetSecrets(record_uids)
	if err != nil {
		// do something
		fmt.Printf("Error while fetching secrets: %v", err)
	}

	for _, record := range records {
		// do something with record
		fmt.Println(record.Title())
	}

}

Using Default Connection

import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;
import com.keepersecurity.secretmanager.aws.kms.AwsKeyValueStorage;
import com.keepersecurity.secretmanager.aws.kms.AwsSessionConfig;
import com.keepersecurity.secretsManager.core.InMemoryStorage;
import com.keepersecurity.secretsManager.core.SecretsManager;
import com.keepersecurity.secretsManager.core.SecretsManagerOptions;
import static com.keepersecurity.secretsManager.core.SecretsManager.initializeStorage;

import software.amazon.awssdk.regions.Region;

import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;

class Test {
	public static void main(String args[]){
		String keyId = "<Key ID>";
		String awsAccessKeyId = "<AWS Access ID>";
		String awsSecretAccessKey = "<AWS Secret>";
		String oneTimeToken = "[One Time Token]";
		Region region = Region.<cloud-region>;
		String profile = null OR "DEFAULT";     //set profile (ex. DEFUALT/UAT/PROD) if ~/.aws/config is set
		String configFileLocation = "client_config_test.json";
		try{
			//set AWS configuration, It can be null if profile is set for aws credentials
			AwsSessionConfig sessionConfig = new AwsSessionConfig(awsAccessKeyId, awsSecretAccessKey);
			//Get Storage 
			AwsKeyValueStorage awskvstorage =  new AwsKeyValueStorage(keyId, configFileLocation, profile, sessionConfig, region);
			initializeStorage(awskvstorage, oneTimeToken);
			SecretsManagerOptions options = new SecretsManagerOptions(awskvstorage);
			//getSecrets(OPTIONS);
		}catch (Exception e) {
			System.out.println(e.getMessage());
		}
	}
}

import { AWSKeyValueStorage } from "@keeper-security/secrets-manager-aws";
import { initializeStorage, getSecrets } from "@keeper-security/secrets-manager-core";


const getKeeperRecordsAWS = async () => {

	const configPath = "client-config-path.json";
	
	const keyId = 'arn:aws:kms:ap-south-1:<accountName>:key/<keyId>';
	const storage = await new AWSKeyValueStorage(keyId, configPath).init();
	
	const oneTimeToken = "<one time token>";

	await initializeStorage(storage, oneTimeToken);
	const { records } = await getSecrets({ storage: storage });

	const firstRecord = records[0]
	const firstRecordPassword = firstRecord.data.fields.find(x => x.type === 'password')
	console.log(firstRecordPassword.value[0])
};
getKeeperRecordsAWS();

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_hsm.storage_aws_kms import AwsKmsKeyValueStorage

key_id = 'c5[...]576'
    
config = AwsKmsKeyValueStorage(key_id, 'client-config.json') # default session
 
secrets_manager = SecretsManager(config=config, verify_ssl_certs=True)
all_records = secrets_manager.get_secrets()

using System;
using System.Linq;
using System.Threading.Tasks;
using SecretsManager;
using AWSKeyManagement;

public class Program
{
	private static async Task getOneIndividualSecret()
	{
		var keyId = "<KEY_ID_1>";
		var path = "<KEEPER_CONFIG_FILE_PATH>";
		var dotnet_access_token = "<ONE_TIME_TOKEN>";

		var aws_storage = new AWSKeyValueStorage(keyId, path);

		SecretsManagerClient.InitializeStorage(aws_storage, dotnet_access_token);

		var options = new SecretsManagerOptions(aws_storage);
		var records_1 = await SecretsManagerClient.GetSecrets(options);
		records_1.Records.ToList().ForEach(record => Console.WriteLine(record.RecordUid + " - " + record.Data.title));
	}

	static async Task Main()
	{
		await getOneIndividualSecret();
	}
}

package main

import (
	"fmt"

	"github.com/keeper-security/secrets-manager-go/core"
	awskv "github.com/keeper-security/secrets-manager-go/integrations/aws"
)

func main() {

	keyARN := "arn:<partition>:kms:<region>:<account-id>:key/<key-id>"
	oneTimeToken := "one time token"
	ksmConfigFileName := "<config file name>"

	// Initialize the AWS Key Vault Storage
	cfg := awskv.NewAWSKeyValueStorage(ksmConfigFileName, keyARN, nil)

	clientOptions := &core.ClientOptions{
		Token:  oneTimeToken,
		Config: cfg,
	}

	fmt.Printf("Client ID in config: %v\n", cfg.Get(core.KEY_CLIENT_ID))

	secrets_manager := core.NewSecretsManager(clientOptions)
	// Fetch secrets from Keeper Security Vault
	record_uids := []string{}
	records, err := secrets_manager.GetSecrets(record_uids)
	if err != nil {
		// do something
		fmt.Printf("Error while fetching secrets: %v", err)
	}

	for _, record := range records {
		// do something with record
		fmt.Println(record.Title())
	}

}

Using the AWS KMS Integration

Once setup, the Secrets Manager AWS KMS integration supports all Secrets Manager SDK functionality. Your code will need to be able to access the AWS KMS APIs in order to manage the decryption of the configuration file when run.

Additional Options

Change Key

We can change key that is used for encrypting the configuration, examples below show the code needed to use it

String newkeyId = "<New-Key-ID>";
AwsKeyValueStorage awskvstorage =  new AwsKeyValueStorage(keyId, configFileLocation, profile, sessionConfig, region);
awskvstorage.changeKey(newkeyId)

const storage = await new AWSKeyValueStorage(keyId,config_path).init()
await initializeStorage(storage, oneTimeToken);

// do all process needed if any or change directly
await storage.changeKey(keyId2);

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_hsm.storage_aws_kms import AwsKmsKeyValueStorage
 
aws_session_cfg = AwsSessionConfig(
    aws_access_key_id="AK[...]FIF",
    aws_secret_access_key="/[...]/g3",
    region_name="<region>")

new_key_id = "<new_key_id>"
config = AwsKmsKeyValueStorage(
   key_id='e9[...]567',
   config_file_location='client-config.json',
   aws_session_config=aws_session_cfg)
 
secrets_manager = SecretsManager(config=config, verify_ssl_certs=True)
all_records = secrets_manager.change_key(new_key_id)

    using Microsoft.Extensions.Logging;

    var awsSessionConfig2 = new AWSSessionConfig();
    var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder.SetMinimumLevel(LogLevel.Debug);
            builder.AddConsole();
        });

    var logger = loggerFactory.CreateLogger<AWSKeyValueStorage>();

    var aws_storage = new AWSKeyValueStorage(keyId, path, awsSessionConfig2,logger);

updatedKeyARN := "arn:<partition>:kms:<region>:<account-id>:key/<key-id>"
isChanged, err := cfg.ChangeKey(updatedKeyARN, nil)
if err != nil {
    fmt.Printf("Error while changing key: %v", err)
}

Decrypt Config

We can decrypt the config if current implementation is to be migrated onto a different cloud or if you want your raw credentials back. The function accepts a boolean which when set to true will save the decrypted configuration to file and if left false, will just return decrypted configuration.

AwsKeyValueStorage awskvstorage =  new AwsKeyValueStorage(keyId, configFileLocation, profile, sessionConfig, region);
awskvstorage.decryptConfig(true) // Set true as a parameter to extract plaintext and save config as a plaintext.
//OR 
awskvstorage.decryptConfig(false); // Set false as a parameter to extract only plaintext.

const storage = await new AWSKeyValueStorage(keyId,config_path).init();
await storage.decryptConfig(); 

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_hsm.storage_aws_kms import AwsKmsKeyValueStorage
 
aws_session_cfg = AwsSessionConfig(
    aws_access_key_id="AK[...]FIF",
    aws_secret_access_key="/[...]/g3",
    region_name="<region>")

config = AwsKmsKeyValueStorage(
   key_id='e9[...]567',
   config_file_location='client-config.json',
   aws_session_config=aws_session_cfg)
 
secrets_manager = SecretsManager(config=config, verify_ssl_certs=True)
all_records = secrets_manager.decrypt_config(True)

var conf = await aws_storage.DecryptConfigAsync(false);
Console.WriteLine(conf);   

cfg := awskv.NewAWSKeyValueStorage(ksmConfigFileName, keyARN, &awskv.AWSConfig{
		ClientID:     clientID,
		ClientSecret: clientSecret,
		Region:       region,
	})
decryptedConfig, err := cfg.DecryptConfig(true)

Features

• Retrieve secrets from the Keeper Vault from an Azure DevOps pipeline

• Set secret credentials as build arguments or environment variables

• Copy secure files from the Keeper Vault

Prerequisites

This page documents the Secrets Manager Azure DevOps 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

  • See the Quick Start Guide for instructions on creating an Application

• An initialized Keeper Secrets Manager Configuration

  • The Azure DevOps integration accepts JSON and Base64 format configurations

Installation

Install the Keeper Secrets Manager Extension

Download from the Visual Studio Marketplace here or search for "Keeper Secrets Manager"

Enable the extension for your Azure organization by selecting an organization and clicking "Download".

Access Secrets From Azure Pipelines

In order to access secrets from the Keeper Vault, add a task to your Azure Pipelines YAML configuration file. Then query your records for the desired fields. Secret queries use Keeper Notation and have the following syntax KeeperNotation > destination where the destination location is defined by its prefix var:, out: or file: see the examples below.

Create a Keeper Secrets Manager Task

Keeper Secrets Manager tasks look like this:

- task: ksmazpipelinetask@1
  inputs:
    keepersecretconfig: $(secret_config)
    secrets: |
      6ya_fdc6XTsZ7i4x9Jcodg/field/password > var:var_password
      6ya_fdc6XTsZ7i4x9Jcodg/field/password > out:out_password
      6ya_fdc6XTsZ7i4x9Jcodg/field/password > out_password2
      6ya_fdc6XTsZ7i4x9Jcodg/file/cert.pem > file:/tmp/mycert.pem

In this example, 6ya_fdc6XTsZ7i4x9Jcodg is the Record UID. In order to add a task, you can create a task using a Task Form, or add it manually.

Add Task Using a Task Form

Search the Tasks menu for "Keeper Secrets Manager" to open the task form.

To fill in the task form and create a Keeper Secrets Manager Task, you will need:

• A Keeper Secrets Manager Configuration

  • The Azure DevOps Extension accepts JSON and base64 configurations.

• One or more Secret queries (See query syntax below)

While it is possible to simply copy a Keeper Secrets Manager configuration into the pipeline, we recommend keeping the Secrets Manager configuration in an Azure Key Vault that is accessible to your Azure Pipeline. See Microsoft's documentation to learn more about Azure Key Vault.

Submit the form to add a task to your configuration automatically.

Manually add Task

To add a task manually to the pipeline configuration, follow this syntax:

- task: <Task Name>
  inputs:
    keepersecretconfig: <Secrets Manager Configuration>
    secrets: |
      <Secrets Queries>

- task: ksmazpipelinetask@1
  inputs:
    keepersecretconfig: $(secret_config)
    secrets: |
      6ya_fdc6XTsZ7i7x9Jcodg/field/password > pazzword
      6ya_fdc6XTsZ7i7x9Jcodg/field/login > LOGIN
      6ya_fdc6XTsZ7i7x9Jcodg/file/build-vsix.sh > file:/tmp/build-vsix.sh

Keeper Secret Queries

Queries for secrets in the Keeper Vault use the following syntax:

Get a Standard Field Value

Syntax

[UID]/field/[FIELD NAME] > [VARIABLE NAME]

Example

6ya_fdc6XTsZ7i7x9Jcodg/field/password > my_password

Get a Custom Field Value

Syntax

[UID]/custom_field/[FIELD NAME] > [VARIABLE NAME]

Example

6ya_fdc6XTsZ7i7x9Jcodg/custom_field/notes > MyNotes

Get a Two-Factor Code

Syntax

[UID]/field/oneTimeCode > [VARIABLE NAME]

Example

6ya_fdc6XTsZ7i7x9Jcodg/field/oneTimeCode > MyOneTimeCode

Get a File

Syntax

[UID]/file/[SECRET FILE NAME] > file:[OUTPUT FILE NAME]

Example

6ya_fdc6XTsZ7i7x9Jcodg/file/cert.pem > file:secret-cert.pem

Variable Types

When saving a secret from the Keeper vault as a variable on your Pipeline, there are a few options for how to set those variables, depending on your needs.

OUT

out (default) sets the secret to a variable which is accessible in any jobs in the pipeline. If you do not define a variable type, out will be used by default.

6ya_fdc6XTsZ7i7x9Jcodg/field/password > pazzword
6ya_fdc6XTsZ7i7x9Jcodg/field/password > out:my_password

VAR

var sets the secret to a local variable, usable within the same pipeline job.

6ya_fdc6XTsZ7i7x9Jcodg/field/password > var:my_password

FILE

file sets the contents to a file. Usually used to access certificates and other files from the Keeper Vault.

6ya_fdc6XTsZ7i7x9Jcodg/file/build-vsix.sh > file:/tmp/build-vsix.sh

ENVIRONMENT VARIABLE

env set the secret as an environment variable which the build machine can access.

To do this, you first need to set the secret to a pipeline variable, then set it as an environment variable in the bash task.

- task: ksmazpipelinetask@1
  name: getKeeperSecrets
  inputs:
    keepersecretconfig: $(sm-config)
    secrets: |
      6ya_fdc6XTsZ7i7x9Jcodg/field/password > var:var_password
      
- bash: |
        echo "Using the mapped env variable: $MY_MAPPED_ENV_VAR_PASSWORD"
    env:
        $MY_MAPPED_ENV_VAR_PASSWORD: $(var_password)

Example Usage

Get Secrets From Keeper

This example pipeline sets secrets from the Keeper Vault to variables and echoes them. Note that echoed passwords are masked.

trigger:
- master

pool:
  vmImage: ubuntu-latest

steps:

- task: ksmazpipelinetask@1
  name: setKsmSecretsStep
  inputs:
    keepersecretconfig: $(sm-config)
    secrets: |
      6ya_fdc6XTsZ7i7x4Jcodg/field/password > var:var_password
      6ya_fdc6XTsZ7i7x4Jcodg/field/password > out_password2
      6ya_fdc6XTsZ7i7x4Jcodg/field/password > out:out_password
      6ya_fdc6XTsZ7i7x4Jcodg/field/oneTimeCode > var:MyOneTimeCode
      6ya_fdc6XTsZ7i7x4Jcodg/file/build-vsix.sh > file:/tmp/build-vsix.sh

- bash: |
    echo "Using an input-macro works                : $(var_password)"
    echo "Using an output variable (default method) : $(setKsmSecretsStep.out_password2)"
    echo "Using an output variable                  : $(setKsmSecretsStep.out_password)"
    echo "Using an output variable for totp         : $(setKsmSecretsStep.out_password)"
    echo "Using the mapped env var                  : $(MyOneTimeCode)"
    echo "Check injected secret file                : $(file /tmp/build-vsix.sh)"
  env:
    MY_MAPPED_ENV_VAR_PASSWORD: $(var_password) # the recommended way to map to an env variable
  name: display_secret_values

Use Secrets in Multiple Jobs

This example gets passwords and files from Keeper, and utilizes those passwords and files in another job.

trigger:
- master

pool:
  vmImage: ubuntu-latest

jobs:
- job: ksmSecrets
  displayName: "Inject KSM Secrets"

  steps:

  - task: ksmazpipelinetask@1
    name: setKsmSecretsStep
    inputs:
      keepersecretconfig: $(sm-config)
      secrets: |
        6ya_fdc6XTsZ7i7x9Jcodg/field/password > var:var_password
        6ya_fdc6XTsZ7i7x9Jcodg/field/password > out:out_password
        6ya_fdc6XTsZ7i7x9Jcodg/field/password > out_password2
        6ya_fdc6XTsZ7i7x9Jcodg/file/mykey.pub > file:/tmp/public_key.pem
        6ya_fdc6XTsZ7i7x9Jcodg/file/mykey.pem > file:/tmp/private_key.pem

  - bash: |
      echo "Using an input-macro works                : $(var_password)"
      echo "Using an output variable (default method) : $(setKsmSecretsStep.out_password2)"
      echo "Using an output variable                  : $(setKsmSecretsStep.out_password)"
      echo "Using the mapped env var                  : $MY_MAPPED_ENV_VAR_PASSWORD"
      echo "Check injected secret file                : $(file /tmp/public_key.pem)"
    env:
      MY_MAPPED_ENV_VAR_PASSWORD: $(var_password) # the recommended way to map to an env variable
    name: display_secret_values

  - bash: |
      cat << EOF > decrypted.txt
      This is a decrypted message
      EOF
    name: create_text_file

  - bash: cat decrypted.txt
    name: view_decrpyted_content


  - bash: openssl rsautl -encrypt -inkey /tmp/public_key.pem -pubin -in decrypted.txt -out ecrypted.bin
    name: encrypte_file

  - bash: cat ecrypted.bin
    name: view_encrpyted_content

  - bash: openssl rsautl -decrypt -inkey /tmp/private_key.pem -in ecrypted.bin -out decrypted2.txt
    name: decrpyt_content

  - bash: cat decrypted2.txt
    name: view_decrpyted2_content


- job: encryptFileTest
  dependsOn: ksmSecrets
  variables:
    # map the output variable from A into this job
    # Note:
    #   that files can't be shared between jobs each agent can run only one job at a time
    #   one job is an independent running individual, the communication between different 
    #   jobs requires the use of "middleware", like variable, artifact and etc.
    pwdFromKsmSecrets: $[ dependencies.ksmSecrets.outputs['setKsmSecretsStep.out_password'] ]

  steps:
    - bash: |
        echo "password retrieved from job 'ksmSecrets', step 'pwdFromKsmSecrets', out variable 'setKsmSecretsStep.out_password':$(pwdFromKsmSecrets)"

About

The Keeper Secrets Manager CLI tool sync command allows you to push secrets from the Keeper Vault to a target Azure Key Vault account, overwriting the existing values in the target location. This allows the Keeper Vault to be the single source of truth for any services or scripts in Azure which utilize the Key Vault.

Features

• Use secrets from the Keeper Vault as the source of truth for Azure Key Vault

• Seamlessly start using secrets from the Keeper Vault with your existing Azure scripts and services

Prerequisites

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

  • Secrets Manager add-on 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

  • See the Quick Start Guide for instructions on creating an Application

• An Azure account with Key Vault, and the ability to create security principals

Setup

1. Configure Keeper Secrets Manager CLI

To configure the KSM CLI tool, a profile needs to be created with the Keeper Secrets Manager One Time Access Token.

The simplest way to do this is to initialize the default profile with the following command:

ksm profile init <TOKEN>

For information on creating multiple profiles and other options, see the profile documentation

2. Set Azure Permissions

To use KSM sync with Azure, the Azure account needs to be configured to accept the connection. The Azure account with Key vault needs to enable a service principal with authorization to perform key operations in the Key Vault.

Follow the Microsoft guide for setting up a service principal: https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals

3. Create Azure Credentials Record

The KSM CLI needs the credentials for the Azure account to set secrets. These credentials are stored in a Keeper record which the CLI tool can access using Keeper Secrets Manager.

Record fields with the following labels are required on the credentials record:

"Azure Tenant ID" "Azure Client ID" "Azure Client Secret" "Azure Key Vault Name"

(Method 1) Create an Azure Credentials Custom Record Type

A custom record type can be created with the required fields, which makes it easy and clean to create a record.

To create a custom record type, go to the "Custom Record Types" tab in the Keeper Vault and hit "Create Type". Create a new record type with hidden fields that have the correct field label, then click "Publish" to create the new record type.

Then simply create a new record of the Azure Credentials type and enter the details into the corresponding fields.

Make sure this new record is in a shared folder that is shared to your Secrets Manager application.

(Method 2) Add Custom Fields

To create a credentials record without creating a new record type, the required fields can be added as custom fields to a standard record.

Create a new record of any type, then add Custom Fields of the 'Hidden Field' type for each required Azure field. Click "Edit Label" to change the labels to the corresponding field name.

Then fill in each custom field and hit "Save" to save the record.

4. Create Value Mappings

The KSM CLI sync command identifies which values to set using mappings that are defined on the command call. For each mapping passed to the command, a value with the given name will be populated with the given value from the Keeper Vault.

These mappings follow this format:

--map "VALUE KEY" "KEEPER NOTATION"

VALUE KEY is the key name that the value will be assigned in Azure Key Vault

KEEPER NOTATION is a Keeper notation query of a value from a keeper record to set to the key

Keeper notation is a query notation used by Keeper Secrets Manager to identify specific record values. The notation follows the general format of: UID/[field|custom_field]/fieldname for example: ae3d[...]d22e/field/password

See the Keeper Notation documentation for more information

Full Mapping Example: --map "MySQL_PWD" "jd3[...]i-fd/field/password"

Multiple mappings can be added to a single sync command --map "MySQL_PWD" "jd3[...]i-fd/field/password" --map "MySQL_Login" "jd3[...]i-fd/field/login"

Run Sync

To run the sync, use the KSM CLI sync command with the credentials record and value mapping

1. Construct the Command

Put together the KSM sync command with the Azure type. The format looks like the following:

ksm sync --type azure --credentials [UID] --map [...] --map [...]

2. Run a Dry-Run

The sync command supports running a dry-run which will identify all changes that will be made to your Azure Key Vault values without actually pushing the values or making changes. Use this to make sure your mapping queries are constructed properly.

ksm sync --type azure --credentials [UID] --map [...] --map [...] --dry-run

3. Run the Sync

When ready, run the sync command without the dry-run option. This will push values from your Keeper Vault to Azure Key Vault

ksm sync --type azure --credentials [UID] -m [...] -m [...]

Keeper Secrets Manager integrates with Azure Key Vault in order to provide encryption for Keeper Secrets Manager configuration files. With this integration, you can protect connection details on your machine while taking advantage of Keeper's zero-knowledge encryption of all your secret credentials.

Features

• Encrypt and Decrypt your Keeper Secrets Manager configuration files with Azure Key Vault.

• Protect against unauthorized access to your Secrets Manager connections.

• Requires only minor changes to code for immediate protection. Works with all Keeper Secrets Manager SDK functionality.

• supports RSA Asymmetric keys from Azure.

Prerequisites

Setup

1. Install Module

repositories {
  mavenCentral()
}

dependencies {
  implementation("com.keepersecurity.secrets-manager:azurekv:1.0.0")
  implementation("com.keepersecurity.secrets-manager:core:17.0.0")
  implementation("com.azure:azure-identity:1.15.0")
  implementation("com.azure:azure-security-keyvault-keys:4.9.2")
  implementation("com.fasterxml.jackson.core:jackson-databind:2.18.2")
  implementation("com.fasterxml.jackson.core:jackson-core:2.18.2")
  implementation("com.google.code.gson:gson:2.12.1")
  implementation("org.slf4j:slf4j-api:1.7.32"){
        exclude("org.slf4j:slf4j-log4j12")
    }
  implementation("ch.qos.logback:logback-classic:1.2.6")
  implementation("ch.qos.logback:logback-core:1.2.6")
  implementation("org.bouncycastle:bc-fips:1.0.2.4")
}

<!-- KMS-core -->
 <dependency>
     <groupId>com.keepersecurity.secrets-manager</groupId>
     <artifactId>azurekv</artifactId>
     <version>1.0.0</version>
</dependency>
<dependency>
     <groupId>com.keepersecurity.secrets-manager</groupId>
     <artifactId>core</artifactId>
     <version>17.0.0</version>
 </dependency>

 <!-- Azure-identity -->
   <dependency>
       <groupId>com.azure</groupId>
       <artifactId>azure-identity</artifactId>
       <version>1.15.0</version>
        <scope>compile</scope>
   </dependency>
  <!-- Azure-keyvault -->
   <dependency>
       <groupId>com.azure</groupId>
       <artifactId>azure-security-keyvault-keys</artifactId>
       <version>4.9.2</version>
   </dependency>
      	
   <!--gson -->
   <dependency>
   	<groupId>com.google.code.gson</groupId>
   	<artifactId>gson</artifactId>
   	<version>2.12.1</version>
   </dependency>

   <!--jackson-core -->
   <dependency>
   	<groupId>com.fasterxml.jackson.core</groupId>
   	<artifactId>jackson-core</artifactId>
   	<version>2.18.2</version>
   </dependency>
   	
   <!--jackson-databind -->
   <dependency>
   	<groupId>com.fasterxml.jackson.core</groupId>
   	<artifactId>jackson-core</artifactId>
   	<version>2.18.2</version>
   </dependency>
   <!-- slf4j-api -->
	<dependency>
	   <groupId>org.slf4j</groupId>
	   <artifactId>slf4j-api</artifactId>
	   <version>1.7.32</version>
	   <scope>runtime</scope>
	</dependency>	
  <!-- logback-classic -->
   <dependency>
	<groupId>ch.qos.logback</groupId>
	<artifactId>logback-classic</artifactId>
	<version>1.2.6</version>
	<scope>compile</scope>
  </dependency>
<!-- logback-core -->
   <dependency>
      <groupId>ch.qos.logback</groupId>
      <artifactId>logback-core</artifactId>
      <version>1.2.6</version>
      <scope>compile</scope>
   </dependency>  	
   <!-- bc-fips -->
   <dependency>
   	<groupId>org.bouncycastle</groupId>
   	<artifactId>bc-fips</artifactId>
   	<version>1.0.2.4</version>
   </dependency>
   	

npm install @keeper-security/secrets-manager-azure

pip3 install keeper-secrets-manager-storage

dotnet add package Keeper.SecretsManager.AzureKeyVault

go get github.com/keeper-security/secrets-manager-go/integrations/azure

2. Configure Azure Key Vault Connection

Ensure that you have an Azure Key Vault instance available, The following param needed to connect azure key vault AZURE_TENANT_ID: The Microsoft Entra tenant (directory) ID.

AZURE_CLIENT_ID: The client (application) ID of an App Registration in the tenant.

AZURE_CLIENT_SECRET: A client secret that was generated for the App Registration.

You will need an Azure App directory App to use the Azure Key Vault integration.

3. Add Azure Key Vault Storage to Your Code

Once azure connection has been configured, You can fetch the Key to encrypt / decrypt KSM configurations using azure key and you need to tell the Secrets Manager SDK to utilize the key vault as storage.

Using Azure Key Vault Integration

Once setup, the Secrets Manager Azure Key Vault integration supports all Secrets Manager SDK functionality. Your code will need to be able to access the Azure Keys in order to manage the encryption and decryption of the KSM configuration file. Using Specified Connection credentials

import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;
import static com.keepersecurity.secretsManager.core.SecretsManager.initializeStorage;
import com.keepersecurity.secretmanager.azurekv.AzureKeyValueStorage;
import com.keepersecurity.secretmanager.azurekv.AzureSessionConfig;
import com.keepersecurity.secretsManager.core.SecretsManagerOptions;


class Test {
	public static void main(String args[]){
		String oneTimeToken = "[One_Time_Token]";
		String keyId = "https://<vault-name>.vault.azure.net/keys/<keyname>/<keyversion>";
		String configFileLocation="<KSM-client-config.json>";
		String azTenantId = "<azure-tenant-id>";
		String azClientId = "<azure-client-id>";
		String azClientSecret = "<azure-client-secret>";
		String keyVaultUrl = "https://<vault-name>.vault.azure.net/";
		Security.addProvider(new BouncyCastleFipsProvider());
		try{
			//set azure KV configuration, 
			AzureSessionConfig azConfig= new AzureSessionConfig(azTenantId, azClientId, azClientSecret, keyVaultUrl);
			//Get Storage 
			AzureKeyValueStorage azkvstorage =  AzureKeyValueStorage.getInternalStorage(keyId, configFileLocation, azConfig);
			initializeStorage(azkvstorage, oneTimeToken);
			SecretsManagerOptions options = new SecretsManagerOptions(azkvstorage);
			//getSecrets(options)
		}catch (Exception e) {
			System.out.println(e.getMessage());
		}
	}
}

 import { getSecrets, initializeStorage, localConfigStorage } from '@keeper-security/secrets-manager-core';
 import {AzureKeyValueStorage, AzureSessionConfig} from "@keeper/secrets-manager-azure";
 
     const getKeeperRecords = async () => {
        const tenant_id="<tenant_id>" 
        const client_id="<client_id>"
        const client_secret="<client-secret>"
        const azureSessionConfig = new AzureSessionConfig(tenant_id, client_id, client_secret)
        
        let config_path = "<path to ksm-client-config.json>"
        const logLevel = LoggerLogLevelOptions.info;
        // oneTimeToken is used only once to initialize the storage
        // after the first run, subsequent calls will use ksm-config.txt
        const oneTimeToken = "[One Time Token]";
        
        const keyId = 'https://<vault_name>.vault.azure.net/keys/<key_name>/<version>'
        const storage = await new AzureKeyValueStorage(keyId,config_path,azureSessionConfig,logLevel).init();
        await initializeStorage(storage, oneTimeToken);
        
        const {records} = await getSecrets({storage: storage});
        console.log(records)
    }
    getKeeperRecords()

from keeper_secrets_manager_storage.storage_azure_keyvault import AzureSessionConfig,AzureKeyValueStorage
from keeper_secrets_manager_core import SecretsManager

tenant_id = "<Tenant_ID>"
client_id = "<CLIENT_ID>"
client_secret = "<CLIENT_SECRET>"

azure_session_config = AzureSessionConfig(tenant_id, client_id, client_secret)
config_path = "<path_to_client_config_python.json>"

token="<One Time Token>"

key_id = "<key_id>"

azure_key_value_storage = AzureKeyValueStorage(key_id=keyId,config_file_location=config_path ,az_session_config=azure_session_config)
    
secrets_manager = SecretsManager(token = token,config=azure_key_value_storage)
    
records  = secrets_manager.get_secrets()
    
for record in records:
    print(record)

using System;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
using OracleKeyManagement;
using SecretsManager;

public class Program
{
   private static async Task getOneIndividualSecret()
    {
        var tenant_id = "<TENANT_ID>";
        var client_secret = "<CLIENT_SECRET>";
        var client_id = "<CLIENT_ID>";
        var keyId = "<KEY_ID>";
        var path = "ksmConfigDotnet.json";
        var dotnet_access_token = "<ACCESS_TOKEN>";
        var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder.SetMinimumLevel(LogLevel.Debug);
            builder.AddConsole();
        });
        var logger = loggerFactory.CreateLogger<AzureKeyValueStorage>();
        var azure_session_config = new AzureSessionConfig(tenant_id, client_id, client_secret);
        AzureKeyValueStorage azure_storage = new AzureKeyValueStorage(keyId, path, azure_session_config, logger);
        SecretsManagerClient.InitializeStorage(azure_storage, dotnet_access_token);
        
        var options = new SecretsManagerOptions(azure_storage);
                    var records_list = await SecretsManagerClient.GetSecrets(options);
        records_list.Records.ToList().ForEach(record => Console.WriteLine(record.RecordUid + " - " + record.Data.title));
    }
	static async Task Main()
	{
		await getOneIndividualSecret();
	}
}

package main

import (
	"encoding/json"
	"fmt"

	"github.com/keeper-security/secrets-manager-go/core"
	azurekv "github.com/keeper-security/secrets-manager-go/integrations/azure"
)

func main() {
	
	ksmConfigFile := ""
	oneTimeToken := "oneTimeToken"
	keyURL := "<Key URL>"   	}
	
	//Initialize the Azure Key Vault Storage
	cfg := azurekv.NewAzureKeyValueStorage(ksmConfigFileName, keyURL, &azurekv.AzureConfig{
		TenantID:     "<Azure Tenant ID>",
		ClientID:     "<Azure Client ID>",
		ClientSecret: "<Azure Client Secret>",
	})
	// create a new secrets manager client
	secrets_manager := core.NewSecretsManager(
		&core.ClientOptions{
			Config: cfg,
			Token:  oneTimeToken,
		},
	)
	// Fetch all the secrets from the vault
	secrets, err := secrets_manager.GetSecrets([]string{})
	if err != nil {
		// do something
		fmt.Printf("Error: %s\n", err)
	} else {
		for _, secret := range secrets {
			fmt.Printf("Recieved secret: %s\n", secret.Title())
		}
	}

}

Additional Options

Change Key

We can change key that is used for encrypting the KSM configuration, examples below show the code needed to use it

//The method changeKey(newKeyID) will be used to encrypt the KSM config file with new azure key. 
....
 String newKeyID = "https://<vault-name>.vault.azure.net/keys/<keyname>/<keyversion>";
 AzureKeyValueStorage azkvstorage =  AzureKeyValueStorage.getInternalStorage(keyId, configFileLocation, azConfig);
 boolean isChanged = azkvstorage.changeKey(newKeyID);	 // Change the key for encryption/decryption
....

// To change the Azure Key Vault key used for encryption, you can call the `changeKey` method on the `OciKeyValueStorage` instance.
.....
 const keyId = 'https://<vault_name>.vault.azure.net/keys/<key_name>/<version>'
 const keyId2 = "https://<vault_name>.vault.azure.net/keys/<key_name>/<version>"
 const storage = await new AzureKeyValueStorage(keyId,config_path,azureSessionConfig).init();
 await storage.changeKey(keyId2);

.....

azure_key_value_storage = AzureKeyValueStorage(key_id=keyId,config_file_location=config_path ,az_session_config=azure_session_config)
new_key_id = "<new key id>"
isChanged = azure_key_value_storage.change_key(new_key_id = new_key_id)
print("Key is changed " + isChanged)

// To change the Azure key used for encryption, you can call the `ChangeKeyAsync` method on the `AzureKeyValueStorage` instance.
 using Microsoft.Extensions.Logging;
 ....
     var keyId2 = "<KEY_ID_2>";
     var loggerFactory = LoggerFactory.Create(builder =>
            {
                builder.SetMinimumLevel(LogLevel.Debug);
                builder.AddConsole();
            });
    var logger = loggerFactory.CreateLogger<AzureKeyValueStorage>();
    AzureKeyValueStorage azure_storage = new AzureKeyValueStorage(keyId, path, azure_session_config, logger);
    azure_storage.ChangeKeyAsync(keyId2).Wait();
 ....

	....	
		updatedConfig := &azurekv.AzureConfig{
			TenantID:     "<Updated Tenant ID>",
			ClientID:     "<Updated Client ID>",
			ClientSecret: "<Updated Client Secret>",
		}
		updatedKeyURL := "<Updated Key URL>"		
		// Changes the key
		// If you don't want to change Config, pass nil as a paramter
		isChanged, err := cfg.ChangeKey(updatedKeyURL, updatedConfig)
		if err != nil {
			fmt.Printf("Error while changing key: %v", err)
		} else {
			fmt.Printf("Key changed: %v\n", isChanged)
		}
		.....

Decrypt Config

We can decrypt the config if current implementation is to be migrated onto a different cloud or if you want your raw credentials back. The function accepts a boolean which when set to true will save the decrypted configuration to file and if it is false, will just return decrypted configuration. This function accepts a boolean, when set to true will save the decrypted configuration to file and when set to false will return decrypted configuration.

....
 AzureKeyValueStorage azkvstorage =  AzureKeyValueStorage.getInternalStorage(keyId, configFileLocation, azConfig);
 azkvstorage.decryptConfig(false); // Set false as a parameter to extract only plaintext.
 //OR 
 azkvstorage.decryptConfig(true); // Set true as a parameter to extract plaintext and save config as a plaintext.
....

 //To decrypt the config file and save it again in plaintext, you can call the `DecryptConfigAsync` method on the `AzureKeyValueStorage` instance.
.... 
 const storage = await new AzureKeyValueStorage(keyId,config_path,azureSessionConfig).init();
 const decryptedConfig = storage.DecryptConfigAsync(true).wait(); // return decrypted and Saves to file
  //OR
 const decryptedConfig = await storage.decryptConfig(false); // returns the decrypted config 
.... 

storage = AzureKeyValueStorage(key_id=keyId,config_file_location=config_path ,az_session_config=azure_session_config)
storage.decrypt_config() #saved plain config to file
 # or
storage.decrypt_config(False)# returns config as return value, file will stay encrypted

//To decrypt the config file and save it again in plaintext, you can call the `DecryptConfigAsync` method on the `AzureKeyValueStorage` instance.
.... 
var keyId2 = "<KEY_ID_2>";
 AzureKeyValueStorage azure_storage = new AzureKeyValueStorage(keyId, path, azure_session_config, logger);
await azure_storage.DecryptConfigAsync(true); // return decrypted and Saves to file
//OR
await azure_storage.DecryptConfigAsync(false); // returns the decrypted config 
.... 

		.....
		configs := make(map[core.ConfigKey]interface{})
		plainText, err := cfg.DecryptConfig(true)
		if err != nil {
			// do something
			fmt.Printf("Error while decrypting config: %v", err)
		} else {
			if err := json.Unmarshal([]byte(plainText), &configs); err != nil {
				fmt.Printf("Error while unmarshalling: %v", err)
			}
			fmt.Printf("Decrypted data: %v\n", configs["clientId"])
		}
		.....

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

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

  • See the Quick Start Guide for instructions on creating an Application

• 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>

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.

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

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

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.

Docker Secrets Management

Features

• Pass secret credentials from the Keeper Vault to Docker images

• Build Docker Images with secret credentials from the Keeper Vault using build arguments

• Copy files from the Keeper vault into Docker containers

Prerequisites

This page documents the Secrets Manager Docker Image b Actions 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

  • See the Quick Start Guide for instructions on creating an Application

• A One Time Access Token

• The Keeper Secrets Manager (KSM) CLI Tool

  • See instructions on setting up the KSM CLI here

About

The Secrets Manager CLI can be used to pull secrets from a Docker image at runtime, or it can be used by building it into the docker image. Several use cases are described in this document.

Example 1: Build an Image with Secrets using BuildKit

Secrets from the Keeper Vault can be built into a Docker container using Docker BuildKit. As of Docker 18.09 or later, image building supports the ability to pass secrets in via a mounted file system. As a simple example demonstrating this capability, we will be creating a user account in the destination image with a username and password from Keeper Secrets Manager.

Step 1: Set Environmental Variables with Keeper notation for the secrets that are needed. For more notation examples click here.

export MY_UID="SOAsfj_lIg0VenDr83gjDw"
export MY_USER="keeper://${MY_UID}/field/login"
export MY_PASS="keeper://${MY_UID}/field/password"

Step 2: Using the ksm exec command, the Docker build is created with the 2 secrets (login and password). The --secret parameters will pull values from the environmental variables that have been substituted with Keeper secrets.