Ansible Plugin
A collection of Ansible plugins that interact with your Keeper account and can be used in your automations.

Prerequisites

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

Installation

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

Install Keeper Ansible Module

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.
1
$ pip3 install keeper_secrets_manager_ansible
Copied!

Configure Location of Plugin Modules

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 usign the following command:
1
$ keeper_ansible --config
2
3
# Below are the directory paths to action and lookup plugins.
4
ANSIBLE_ACTION_PLUGINS=...site-packages/keeper_secrets_manager_ansible/plugins/action_plugins
5
ANSIBLE_LOOKUP_PLUGINS=...site-packages/keeper_secrets_manager_ansible/plugins/lookup_plugins
Copied!
Those paths can be used in your ansible.cfg.
1
[defaults]
2
action_plugins = ...site-packages/keeper_secrets_manager_ansible/plugins/action_plugins
3
lookup_plugins = ...site-packages/keeper_secrets_manager_ansible/plugins/lookup_plugins
Copied!

Generate a Config File

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 Ansible variable files. These variable files can be encrypted with Ansible vault.
Generate a One Time Access Token from the Commander interface:
1
My Vault> secrets-manager client add --app MyApplication
2
3
------------------------------------------------------------------
4
One Time Access Token: XXXXXXXXXXX
5
------------------------------------------------------------------
Copied!
If you have not configured any devices, make sure to check out the Quick Start Guide.
Using the Keeper Ansible module, generate a Configuration file using the provided One Time Access Token. For example:
1
$ keeper_ansible --keeper_token XXXXXXXXXXX
2
Config file create at location client-config.json
Copied!
This will generate the Keeper JSON configuration file in the current directory.
If you added the module directory to your PYTHONPATH, you can create a config with the following command.
1
$ python3 -m keeper_secrets_manager_ansible --keeper_token XXXXXX
2
Config file create at location client-config.json
Copied!
The default name for the JSON configuration file is client-config.json. The content of the file looks like the following:
1
{
2
"appKey" : "XXXXXXXX",
3
"clientId": "XXXXXXXX",
4
"clientKey": "XXXXXXXX",
5
"privateKey": "XXXXXXXX"
6
"serverPublicKeyId": "X"
7
}
8
Copied!
This config file allows your Ansible playbook to authenticate and retrieve designated secrets from the vault.

Ansible Variables

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.
1
---
2
keeper_config_file: /path/to/client-config.json
Copied!
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:
1
---
2
keeper_app_key: XXXXX
3
keeper_client_id: XXXXX
4
keeper_token: XXXXX
5
keeper_private_key: XXXXX
Copied!
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:
Ansible Variable
JSON Key
Description
keeper_config_file
--
An alternative path and name for the JSON configuration file, if not current directory or named differently than client-config.json.
keeper_token
clientKey
The one time access token, also known as the client key.
keeper_client_id
clientId
The client id provided from Secrets Manager after the one time access token is used.
keeper_app_key
appKey
The app key provided from the secret management service after the one time access token is used.
keeper_private_key
privateKey
The private key provided from the secret management service after the one time access token is used.
keeper_server_public_key_id
serverPublicKeyId
Selects which public key to use when connecting to the server. If the server wants a different public key the SDK will handle switching.
keeper_hostname
hostname
The Secrets Manager backend hostname. Defaults to US. Supports "US", "EU", "AU" and "US_GOV" values depending on your Keeper data center location.
keeper_log_level
Set the log level of the SDK. Acceptable levels are DEBUG, INFO, WARNING, ERROR, and CRITICAL. Defaults to ERROR.

Command Line Variables

As an optional method, values can be passed in through the ansible-playbook command. Example:
1
$ ansible-playbook my_playbook.yml \
2
-e "keeper_app_key=XXXXX" \
3
-e "keeper_client_id=XXXXX" \
4
-e "keeper_token=XXXXX" \
5
-e "keeper_private_key=XXXXX"
Copied!

Ansible Plugin Usage

There are three Keeper action plugins and one lookup plugin.
For all the plugins, the following arguments are used:
  • uid - The Record UID of the desired record (REQUIRED).
  • 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.
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_copy

The plugin keeper_copy is an extension of the built-in copy plugin. Example:
1
--
2
- name: Keeper Copy
3
hosts: my_hosts
4
5
tasks:
6
- name: Copy a password
7
keeper_copy:
8
uid: RECORD UID
9
field: password
10
dest: /tmp/my_password
11
mode: "0600"
12
13
- name: Copy a file
14
keeper_copy:
15
uid: RECORD UID
16
file: my_cert_file.crt
17
dest: /etc/special.crt
18
owner: root
19
group: root
20
mode: "0644"
21
backup: yes
22
Copied!
In the first task example from above, 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 built-in copy plugin's mode key/value to changed the permissions of the file.
The second 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.

Plugin: keeper_get

The plugin keeper_get will retrieve a field or file from a Keeper vault record. Example:
1
---
2
- name: Keeper Get
3
hosts: my_hosts
4
5
tasks:
6
- name: Get login name
7
keeper_get:
8
uid: RECORD UID
9
field: login
10
register: my_login
11
12
- name: Print login name
13
debug:
14
var: my_login.value
15
verbosity: 0
16
17
- name: Make a sudoer
18
copy:
19
dest: "/etc/sudoers.d/{{ my_login.value }}"
20
content: |
21
# Auto added by Ansible
22
{{ my_login.value }} ALL=(ALL:ALL) ALL
Copied!
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 return value is stored in memory so it can be accessed by other tasks.
In the example above, the first task gets the login field from the specified Vault record UID. It 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.

Plugin: keeper_set

The keeper_set plugin has the ability to write a value into an existing Keeper vault record. Example:
1
___
2
- name: Keeper Set
3
hosts: my_hosts
4
5
tasks:
6
- name: Get login name
7
keeper_get:
8
uid: RECORD UID
9
field: login
10
register: my_login
11
12
- name: Add new user
13
user:
14
name: "{{ my_login.value }}"
15
comment: "User {{ my_login.value }}"
16
register: new_user
17
18
- name: Update record
19
keeper_set:
20
uid: RECORD UID
21
custom_field: my_home_directory
22
value: "{{ new_user.home }}"
Copied!
In this example, the custom field "my_home_directory" in the specified Keeper vault record is updated with the given value.

Plugin: keeper_lookup

The keeper_lookup plugin retrieves a field from the Keeper vault record and inserts the value into a text string. Example:
1
---
2
- name: Keeper Lookup
3
hosts: my_hosts
4
5
tasks:
6
- name: Print my login
7
debug:
8
msg: "My login is {{ lookup('keeper', uid='RECORD UID', field='login') }}"
Copied!
When using the lookup ability of Ansible, the module is called keeper. The Record UID must be supplied. The field or custom_field can be used to retrieve an individual field or file. The lookup will then insert the content of the field or file into the text string.
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.

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:
1
#!/bin/sh
2
ksm secret notation keeper://XXXX/field/password
Copied!
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.
1
$ ANSIBLE_VAULT_PASSWORD_FILE=/path/to/script.sh ansible-playbook playbook_with_vault.yml
Copied!
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:
1
objc[6763]: +[__NSPlaceholderDate initialize] may have been in progress in
2
another thread when fork() was called. We cannot safely call it or ignore
3
it in the fork() child process. Crashing instead. Set a breakpoint on
4
objc_initializeAfterForkError to debug
Copied!
This is known problem with Ansible. This can be fixed with the following environmental variable.
1
OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES ansible-playbook ...
Copied!

Missing Configuration file

1
TASK [Copy file from Keeper into the file] ********************************************************************************************
2
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.
3
fatal: [localhost]: FAILED! => {"msg": "Unexpected failure during module execution.", "stdout": ""}
Copied!
Last modified 9d ago