Automation Controller

A collection of Ansible plugins that interact with your Keeper account and can be used in your Automation Controller (formerly Ansible Tower).

Features

• Store Secrets Manager configurations securely in Ansible Automation Controller

• Use Automation Controller 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

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

KSM Configuration

The first step in using Ansible Automation Controller 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 Automation Controller 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.

Creating a credential type and credential

To create Keeper Secrets Manager custom credential type go to Credential Types under Administration and click Add.

Give your credential type a name and set Input configuration to:

---
fields:
  - id: keeper_config
    type: string
    label: Keeper Config (Base64)
    secret: true
  - id: ksm_profile
    type: string
    label: KSM Profile Name
    help_text: Optional. Defaults to 'default'
required:
  - keeper_config

Then set Injector configuration to:

---
extra_vars:
  keeper_config: "{{ keeper_config }}"
  keeper_profile: "{{ ksm_profile | default('default') }}"

Click Save.

Go to Credentials under Resources section and click Add.

Set a Name for your credential, choose Credential Type you created earlier and add your Base64 token to Keeper Config input. Click Save.

The credential will be used when the Template is setup.

Execution Environment

To use the Keeper Secrets Manager plugins in Ansible Automation Controller 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 Automation Controller, 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

Playbook

The directory structure should look like the following.

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

Ansible Automation Controller uses it's own stdout callback plugin. So using keeper_redact will not work. It's important to add no_log: True to tasks that may display secrets in the log.

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

  tasks:
    - 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: "{{ your_record_uid }}/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 created 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, your created project should be synced.

Template

In your instance of Ansible Automation Controller, 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 that contains the Keeper Secrets Manager Tower EE docker image. For Playbook select a playbook from your source repository.

For Credentials select the Keeper Secrets Manager Credential you created. 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.

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.

See the Ansible Plugin documentation for all the Secrets Manager capabilities available to Ansible