Ansible Integration

Before proceeding with this section, please ensure that you have access to the secretssafe Python package, installable from a BeyondTrust-provided .whl file. To run any Secrets Safe plugin or module, you must use a python interpreter version 3.6 or greater.

Install the DevOps Secrets Safe package

The DevOps Secrets Safe lookup plugin and modules import the secretssafe package and create an instance of the client that communicates with the DevOps Secrets Safe API.

Install the secretssafe package to your Python environment using pip.

$ pip install secretssafe-<version_details>.whl

Configure Ansible to Discover the DevOps Secrets Safe Lookup Plugin and Modules

You can load any of the DevOps Secrets Safe Ansible integrations automatically.

For the DevOps Secrets Safe lookup plugin, do any of the following:

  • Store it in the subdirectory named ~/.ansible/plugins/lookup.
  • Store it in the subdirectory named /usr/share/ansible/plugins/lookup.
  • Place the path to the plugin in your ansible.cfg file.

For any of the DevOps Secrets Safe Ansible modules, do any of the following:

  • Store it in the subdirectory named ~/.ansible/plugins/modules.
  • Store it in the subdirectory named /usr/share/ansible/plugins/modules.
  • Place the path to the plugin in your ansible.cfg file.

To use the Ansible components in certain playbooks:

  • For the lookup plugin, store it in the subdirectory named lookup_plugins, located in the directory that contains the playbook.
  • For the modules, store them in the subdirectory named library, located in the directory that contains the playbook.

To use the environment to configure the plugin location for the DevOps Secrets Safe lookup plugin, export the following:

$ export ANSIBLE_LOOKUP_PLUGINS=<path/to/secretssafe/lookup/plugin/directory/>

To use the environment to configure the plugin location for the DevOps Secrets Safe modules, export the following:

$ export ANSIBLE_LIBRARY=<path/to/secretssafe/module/directory/>

Once properly configured, validate the discovery of the plugin:

$ ansible-doc -t lookup secretssafelookup
$ ansible-doc -t module secretssafe_dynamic_accout_create
$ ansible-doc -t module secretssafe_create	

Execute the Plugin with Environment Variables

DevOps Secrets Safe Ansible components share some common options that can be set via environment variables. The following variables must be set either on the control machine (shell where ansible is called), or within the playbook that uses the plugin:

SECRETSSAFE_HOST=<IP address or hostname of Secrets Safe instance>
SECRETSSAFE_PORT=<port of Secrets Safe instance>SECRETSSAFE_API_KEY=<pregenerated API key>
SECRETSSAFE_APP_NAME=<application name associated with API key>
SECRETSSAFE_VERIFY_CA=<true/false/path to CA certificate>

This allows you to invoke the plugin without the credential/configuration keyword arguments.

The DevOps Secrets Safe client verifies the SSL certificate presented by the DSS instance. The SECRETSSAFE_VERIFY_CA environment variable specifies the path to the CA certificate that the Secrets Safe certificate is checked against.

If no SECRETSSAFE_VERIFY_CA is specified, the default certificate bundles provided by the Python requests library are used.

Certificate verification can be disabled by setting SECRETSSAFE_VERIFY_CA=false. We strongly discourag doing this in a production environment.

Common Options

All Secrets Safe Ansible components share some common options:

Component Description Settings
name The name of the application used to create the secret. required: true
api_key API key that corresponds to the application provided in the name option.

required: true

host DNS or IP address of the DSS instance this secret will be saved to.

required: true

verify_ca SSL certificate verification flag; looks to publicly available CA if set to true.

required: false

default: true

choices:

  • true
  • false
  • path to CA certificate
port DSS instance port.

required: false

default: 443

DevOps Secrets Safe Lookup Plugin

This module supports retrieving secrets with Secrets Safe.

In addition to the common options listed above, the secretssafelookup plugin also has the following:

Component Description Settings
uri The DSS URI where the secret is retrieved. required: true
Retrieve and display multiple secrets from DSS using string arguments.
- name: Retrieving and displaying a series of plaintext secrets from Secrets Safe using string arguments.
  hosts: controlnode
  vars:
	secretssafe:
		credentials:
			api_key: "{{ secretssafe_api_key }}"
			app_name: "{{ secretssafe_app_name }}"
		configuration:
			host: "{{ secretssafe_host }}"
			port: "{{ secretssafe_port }}"
			verify_ca: "{{ secretssafe_verify_ca }}"
		uris:
			uri1: some/uri:1
			uri2: some/uri:2

tasks:
- name: Call Secrets Safe using jinja2 with_<lookup_plugin_name> syntax
  debug:
	msg: "{{ item }}"
  with_secretssafelookup:
	- 'uri={{ uris.uri1 }} | credentials={{ secretssafe.credentials }} | configuration={{ secretssafe.configuration }}'
	- 'uri={{ uris.uri2 }} | credentials={{ secretssafe.credentials }} | configuration={{ secretssafe.configuration }}'

Retrieve and display multiple secrets from DSS, reading the configuration from the environment.

- name: Retrieving and displaying a series of plaintext secrets from Secrets Safe, reading the configuration/credentials from the environment.
  hosts: controlnode
  vars:
	uris:
		- some/uri:1
		- some/uri:2

  tasks:
	- name: Call Secrets Safe using jinja2 with_<lookup_plugin_name> syntax and pre-exported environment variables
	  debug:
		msg: "{{ item }}"
	with_secretssafelookup: "{{ uris }}"			

Retrieve and display a single secret from DSS, reading the configuration from defined variables as keyword arguments.

- name: Retrieve and display a single secret from DSS, reading the configuration from defined variables as keyword arguments.
  hosts: controlnode
  vars:
	secretssafe:
		credentials:
			api_key: "{{ secretssafe_api_key }}"
			app_name: "{{ secretssafe_app_name }}"
		configuration:
			host: "{{ secretssafe_host }}"
			port: "{{ secretssafe_port }}"
			verify_ca: "{{ secretssafe_verify_ca }}"
	uri: some/uri:1

  tasks:
	- set_fact:
		decrypted_secret: "{{ lookup('secretssafelookup', uri, credentials=secretssafe.credentials, configuration=secretssafe.configuration) }}"
	- debug:
		msg: "{{ decrypted_secret }}"

Retrieve and display multiple secrets from DSS, reading the configuration from defined variables as keyword arguments.

- name: Retrieve and display multiple secrets from DSS, reading the configuration from defined variables as keyword arguments.
  hosts: controlnode
  vars:
	secretssafe:
		credentials:
			api_key: "{{ secretssafe_api_key }}"
			app_name: "{{ secretssafe_app_name }}"
		configuration:
			host: "{{ secretssafe_host }}"
			port: "{{ secretssafe_port }}"
			verify_ca: "{{ secretssafe_verify_ca }}"
	uris:
		- some/uri:1
		- some/uri:2

tasks:
  - name: Call Secrets Safe lookup in a with_items loop
	debug:
		msg: "{{ lookup('secretssafelookup', item, credentials=secretssafe.credentials, configuration=secretssafe.configuration) }}"
	with_items: "{{ uris }}"

Create Secret Module

This module supports creating secrets with Secrets Safe. Secrets can be read from a file on disk or an Ansible fact. Secret creation by providing a generator name is also supported. You must provide credentials for a Secrets Safe application.

In addition to the common options listed above, the create secret module also has the following options:

Component Description Settings
secret_uri The DSS URI where the secret is saved. required: true
generator Name of generator used to create secret value. Mutually exclusive with secret_file_path and secret_value options.

required: true

secret_file_path Path to file that is saved as a secret. Mutually exclusive with generator and secret_value options.
  • required: false
  • secret_value Value, in the form of a string, that is saved as a secret path to file that is saved as a secret. Mutually exclusive with generator and secret_file_path options.

    required: false

    Create Secret From File.
    - name: Create Secret From File
      hosts: managed_1
      tasks:
    	- name: Create With File Path
    	secretssafe_create:
    	  api_key: <api_key>
    	  name: myapp
    	  host: <secretssafe_host>
    	  port: 443
    	  verify_ca: false
    	  secret_uri: this/is:secret2500
    	  secret_file_path: /home/lockboxadmin/examples.desktop
    

    Create Secret From Fact.

    - name: Create Secret From Fact
      hosts: managed_1
      tasks:
    	- name: Set Fact Value
    	set_fact:
    		test_value: This is my secret
    	- name: Create From Fact
    		secretssafe_create:
    			api_key: <api_key>
    				name: myapp
    				host: <secretssafe_host%gt;
    				port: 443
    				verify_ca: false
    				secret_value: "{{ test_value }}"
    				secret_uri: this/is:secret3  			
    

    Create Secret From Generator

    												
    - name: Create Secrets Using Generator
      hosts: managed_1
      tasks:
    	- name: Create With Generator
    	secretssafe_create:
    		api_key: <api_key%gt;
    		name: myapp
    		host: <secretssafe_host>
    		port: 443
    		verify_ca: true
    		generator: my-number-generator
    		secret_uri: this/is:secret111    
    

    DevOps Secrets Safe secretssafe_dynamic_accout_create Module

    This module supports creating Dynamic Accounts with Secrets Safe.

    In addition to the common options listed above, the secretssafe_dynamic_accout_create module also has the following options:

    Component Description Options
    provider Provider used to create the Dynamic Account.

    required: true

    account_definition Account Definition used to create the Dynamic Account.

    required: true

    input_file Input file with data for Dynamic Account creation. Mutually exclusive with the input_json option.

    required: false

    input_json JSON file that contains data for Dynamic Account creation. Mutually exclusive with the input_file option.

    required: false

    Create Dynamic Account and Copy Output to File
    - name: Create Dynamic Account and Copy Output to File
      hosts: managed_host_1
      tasks:
      - name: create dynamic account
    	secretssafe_dynamic_account_create:
    		api_key: 04ab4f29-21c7-4348-98d7
    		name: myapp
    		host: mydss.myorg.com
    		port: 443
    		verify_ca: 'false'
    		provider: my_gcp_provider
    		account_definition: my_gcp_definition
    		input_file: path/to/myfile.json
    	register: create_output
      - name: copy account info to file
    	copy:
    		dest: ~/dss_dynamic_account.json
    		content: '{{ create_output.msg }}'