Ansible Plugin
A collection of Ansible plugins that interact with your Keeper account and can be used in your automations.
- 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
This page documents the Secrets Manager Ansible integration. In order to utilize this integration, you will need:
- Secrets Manager add-on enabled for your Keeper account
- Membership in a Role with the Secrets Manager enforcement policy enabled
- The Ansible integration accepts JSON format configurations
Due to the flexibility of Ansible, where you install the plugins depends on your Ansible installation and playbook locations.
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
...
Installing via Ansible Galaxy assumes you already have Ansible installed. Ansible Galaxy cannot install dependencies. The following dependencies will need to be installed manually, via pip, into your the python library or virtualenv used by Ansible.
- importlib_metadata
- keeper-secrets-manager-core>=16.2.2
- keeper-secrets-manager-helper>=1.0.4
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
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
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:
My Vault> secrets-manager client add --app MyApplication
------------------------------------------------------------------
One Time Access Token: XX:XXXXXX
------------------------------------------------------------------
Using the Keeper Ansible module, generate a Configuration file using the provided One Time Access Token. For example:
$ 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 looks 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.
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:
Ansible Variable | JSON Key | Description |
keeper_config | -- | A Base64 encoded configuration string. |
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. Only used to initialize the configuration. |
keeper_client_id | clientId | The client id provided from Secrets Manager after the one time access token is used. Required. |
keeper_app_key | appKey | The app key provided from the secret management service after the one time access token is used. Required. |
keeper_private_key | privateKey | The private key provided from the secret management service after the one time access token is used. Required. |
keeper_app_owner_public_key | appOwnerPublicKey | The public key used for creating records. Required if using the keeper_create plugin. |
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. Not required, but will reduce number of web service calls. |
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. Required. |
keeper_log_level | -- | Set the log level of the SDK. Acceptable levels are DEBUG, INFO, WARNING, ERROR, and CRITICAL. Defaults to ERROR. |
keeper_use_cache | -- | Use a cache of the vault. Defaults to False. Cache file are used as backup for network problems. |
keeper_cache_dir | -- | The directory to write and read the cache file. |
keeper_record_types | -- | An list of Keeper Commander record type definitions. |
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"
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.The plugin example are shown with the short plugin names. If you installed the collection via Ansible Galaxy, you will need to use the longer plugin name or add the collection name to the list of collections used in your playbook.
--
- 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 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.
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
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 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.
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
keeper_get:
uid: RECORD UID
field: login
register: my_login
- name: Add new user
user:
name: "{{ my_login.value }}"
comment: "User {{ my_login.value }}"
register: new_user
- name: Update record
keeper_set:
uid: RECORD UID
custom_field: my_home_directory
value: "{{ new_user.home }}"
In this example, the custom field "my_home_directory" in the specified Keeper vault record is updated with the given value.
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.The Ansible variable
keeper_app_owner_public_key is required to create a record. In the client-config.json, the JSON key is appOwnerPublicKey. If your configuration does not contain this key, create a new One-Time Access Token and initialize it.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: [email protected]
- 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 thekeeper_record_typesis 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.
Password generation will use the following symbols: "[email protected]#$%()+;<>=?[]{}^.,
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_fieldstype- Field typelabel- Label to display with the value.value- Field value. Can be a string or dictionary based on field type.
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: [email protected]
- type: password
label: Password
value: "ABC123"
register: my_new_record
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.
Password generation will use the following symbols: "[email protected]#$%()+;<>=?[]{}^.,
Based of record types, certain fields maybe required. Custom fields are optional. Both fields and custom_field are an array of values.
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
copy:
content: "My login is {{ lookup('keeper', uid='RECORD UID', field='login') }}"
dest: "/tmp/my_login.txt"
no_log: True
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 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.
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 isFalse. 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'
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.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.
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. 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 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:
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.See How do I keep secrets data in my playbook? Using
no_log can hide all logging from a task. This plugin is for when you just want secrets returned by the Keeper Secrets Manager plugins to be hidden/redacted.The
keeper_redact plugin will not work with Ansible Tower since it had its own stdout callback plugin to stream the log as the job runs. Highly recommend using the no_log option when you do not wish show information in the log.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
}
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.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.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 ...
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": ""}
Last modified 7mo ago