1.0 Introduction
This article describes how to integrate Fortanix-Data-Security-Manager (DSM) with Ansible Lookup Plugin to access the secrets securely from Fortanix DSM within Ansible Playbooks.
The Ansible Lookup Plugin facilitates real-time data retrieval from external sources within Ansible Playbooks. When integrated with Fortanix Data Security Manager, this plugin facilitates secure fetch of sensitive information stored within the DSM, such as secrets, credentials, certificates, and other securely managed data, during playbook execution. This integration also enhances automation workflows by ensuring secure and centralized management of sensitive data.
2.0 Prerequisites
Ensure the following:
Python latest version and Ansible Python module must be installed on the system.
sudo apt install python sudo apt install python3-pip sudo apt install ansibleFortanix DSM is accessible. For more information, refer to Section 5.1: Signing Up and Section 5.2: Creating an Account.
3.0 Product Tested Version
Fortanix DSM version 4.23 and above.
Ansible Lookup Plugin version 2.9 and 2.10.
Python version 3.x
4.0 Architecture Diagram
Figure 1: Ansible_Architecture_Diagram
The Ansible Playbooks are a set of instructions for automating tasks. It interacts with the Fortanix Data Security Manager application over HTTPS (Hypertext Transfer Protocol Secure) with 443 port to retrieve the secrets for further Ansible deployments.
The Ansible Playbook initiates the request using a Lookup Plugin, facilitating secure communication with Fortanix DSM. Then Fortanix DSM processes the request and sends back a response containing the requested secrets.
The hosts represent the systems where Ansible Playbooks are executed in the workflow, ensuring that automation tasks are performed securely while maintaining the integrity of sensitive data. This setup enhances the security of the system by ensuring that sensitive data is accessed and managed securely during automation tasks.
5.0 Configure Fortanix DSM
A Fortanix DSM service must be configured, and the URL must be accessible. To create a Fortanix DSM account and group, refer to the following sections:
5.1 Signing Up
To get started with the Fortanix Data Security Manager (DSM) cloud service, you must register an account at <Your_DSM_Service_URL>. For example, https://eu.smartkey.io.
For detailed steps on how to set up the Fortanix DSM, refer to the User's Guide: Sign Up for Fortanix Data Security Manager SaaS documentation.
5.2 Creating an Account
Access the <Your_DSM_Service_URL> on the web browser and enter your credentials to log in to the Fortanix DSM.
Figure 2: Logging In
5.3 Creating a Group
Perform the following steps to create a group in the Fortanix DSM:
Click the Groups menu item in the DSM left navigation bar and click the + button on the Groups page to add a new group.
Figure 3: Add Groups
On the Adding new group page, enter the following details:
Title: Enter a title for your group.
Description (optional): Enter a short description for the group.
Click the SAVE button to create the new group.
The new group has been added to the Fortanix DSM successfully.
5.4 Creating an Application
Perform the following steps to create an application (app) in the Fortanix DSM:
Click the Apps menu item in the DSM left navigation bar and click the + button on the Apps page to add a new app.
Figure 4: Add Application
On the Adding new app page, enter the following details:
App name: Enter the name of your application (app).
ADD DESCRIPTION (optional): Enter a short description for the application.
Authentication method: Select the default API Key as the method of authentication from the drop down menu. For more information on these authentication methods, refer to User's Guide: Authentication documentation.
Assigning the new app to groups: Select the group created in Section 5.3: Creating a Group from the list.
Click the SAVE button to add the new application.
The new application has been added to the Fortanix DSM successfully.
5.5 Copying the API Key
Perform the following steps to copy the API key from the Fortanix DSM:
Click the Apps menu item in the DSM left navigation bar and click the app created in Section 5.4: Creating an Application to go to the detailed view of the app.
On the INFO tab, click the VIEW API KEY DETAILS button.
From the API Key Details dialog box, copy the API Key of the app to use it later.
Figure 5: Copy API Key
6.0 Installing Custom Plugin
The custom plugin, fortanix_kms.py, is designed to help you retrieve the secrets from the Fortanix DSM. It relies on the Fortanix Python library to communicate with the DSM effectively. You can configure the plugin by specifying details like the secret name, API endpoint, and API key. It is important to note that the plugin operates securely, requiring API key-based authentication for accessing secrets stored within the Fortanix DSM.
Perform the following steps:
Run the following commands to install the Fortanix Python library,
sdkms-python-sdk-.zip, on your system:sudo pip install sdkmsRun the following command to create the
lookup_pluginsdirectory adjacent to your playbook:mkdir lookup_pluginsRun the following command to navigate to
lookup_pluginsdirectory:cd lookup_pluginsRun the following command to open a text editor and edit the
fortanix_kms.pyfile:nano fortanix_kms.pyCopy the following custom plugin details in
fortanix_kms.pyfile:from ansible.errors import AnsibleError from ansible.module_utils.parsing.convert_bool import boolean from ansible.plugins.lookup import LookupBase import sdkms import sdkms.v1 import base64 import os FORTANIX_API_ENDPOINT=None FORTANIX_API_KEY=None if "FORTANIX_API_ENDPOINT" in os.environ: FORTANIX_API_ENDPOINT = os.environ['FORTANIX_API_ENDPOINT'] if "FORTANIX_API_KEY" in os.environ: FORTANIX_API_KEY = os.environ['FORTANIX_API_KEY'] class FortanixKMS: def __init__(self, **kwargs): self.endpoint = kwargs.get('endpoint', FORTANIX_API_ENDPOINT) self.apikey = kwargs.get('apikey', FORTANIX_API_KEY) self.secret = kwargs.get('secret', None) try: api_key = base64.b64decode(self.apikey).decode('ascii') parts = api_key.split(':') config = sdkms.v1.configuration.Configuration() config.username = parts[0] config.password = parts[1] config.host = self.endpoint client = sdkms.v1.ApiClient(configuration=config) auth_instance = sdkms.v1.AuthenticationApi(api_client=client) auth = auth_instance.authorize() config.api_key['Authorization'] = auth.access_token config.api_key_prefix['Authorization'] = 'Bearer' self.api_instance = sdkms.v1.SecurityObjectsApi(api_client=client) except: raise AnsibleError("Authentication failed, Please check the Fortanix Endpoint and API key") def get(self): kid = self.api_instance.get_security_objects(name=self.secret) key = self.api_instance.get_security_object_value(key_id=kid[0].kid) return bytes(key.value).decode("utf-8") class LookupModule(LookupBase): def run(self, terms, variables=None, **kwargs): vault_dict = {} res = [] for param in terms: try: key, value = param.split('=') except ValueError: raise AnsibleError("fortanix_kms lookup plugin needs key=value pairs, but received %s" % terms) vault_dict[key] = value vault_conn = FortanixKMS(**vault_dict) s = vault_conn.get() res.append(s) return res
7.0 Configuring Endpoints and API Key
You can configure the endpoint and API key in either of the following ways:
Method 1: Using the environment variables.
Method 2: Using plugin parameters.
7.1 Method 1: Using the Environment Variables
This method describes the steps to set the environment variables by configuring the Fortanix endpoint and API key in the Ansible Playbook.
Perform the following steps:
Run the following command to update the values for the environment variable:
export FORTANIX_API_ENDPOINT= <Your_DSM_Service_URL> export FORTANIX_API_KEY= <API_KEY>Where,
FORTANIX_API_ENDPOINTrefers to the Fortanix DSM URL. On-premises customers use KMS URL and the SaaS customers can use the URLs as listed here based on the application region.FORTANIX_API_KEYrefers to the API key of the Fortanix DSM app as created in Section 5.5: Copying the API Key.
Create a sample YAML file,
dm_env.yml, and add the following lookup tag in it:- name: TEST ansible secret management with Fortanix KMS hosts: localhost tasks: - name: if this file does not exist, FAIL (this is the default) debug: msg="{{ lookup('fortanix_kms', 'secret=ansible') }}"Where,
lookuprefers to the Fortanix plugin name.secretrefers to the secret stored in Fortanix DSM.
Run the following command to execute the Ansible Playbook:
ansible-playbook dm_env.ymlThe following is the output of the command:
[WARNING]: No inventory was parsed, only implicit localhost is available [WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all' PLAY [setup Mysql with medium_db db and remote login] ***************************************************************************************************************************************** TASK [Gathering Facts] ************************************************************************************************************************************************************************ ok: [localhost] TASK [if this file does not exist, FAIL (this is the default)] ******************************************************************************************************************************** ok: [localhost] => { "msg": "Password" } PLAY RECAP ************************************************************************************************************************************************************************************ localhost : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
7.2 Method 2: Using Plugin Parameters
This method describes the steps to fetch the secret by configuring Fortanix endpoint and API key in Ansible Playbook.
Perform the following steps:
Create a sample YAML file,
dm_with_endpoint.yml, and add the following lookup tag in it:- name: setup Mysql with medium_db db and remote login hosts: localhost tasks: - name: if this file does not exist, FAIL (this is the default) debug: msg="{{ lookup('fortanix_kms', 'secret=ansible', 'endpoint=https://eu.smartkey.io/', 'apikey=<>') }}"Where,
lookuprefers to the Fortanix plugin name.secretrefers to the secret stored in Fortanix DSM.endpointrefers to the Fortanix DSM URL. On-premises customers use KMS URL and the SaaS customers can use the URLs as listed here based on the application region.apikeyrefers to the API key of the Fortanix DSM app as created in Section 5.5: Copying the API Key.
Run the following command to execute the Ansible Playbook:
ansible-playbook dm_with_endpoint.ymlThe following is the output of the command:
Nithya[WARNING]: No inventory was parsed, only implicit localhost is available [WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all' PLAY [setup Mysql with medium_db db and remote login] ***************************************************************************************************************************************** TASK [Gathering Facts] ************************************************************************************************************************************************************************ ok: [localhost] TASK [if this file does not exist, FAIL (this is the default)] ******************************************************************************************************************************** ok: [localhost] => { "msg": "Password" } PLAY RECAP ************************************************************************************************************************************************************************************ localhost : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0