Using Fortanix Data Security Manager with Ansible Lookup Plugin

1.0 Introduction

This article describes how to integrate Fortanix Data Security Manager (DSM) with the 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:

3.0 Architecture Diagram

1.png

Figure 1: 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.

4.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:

4.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 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.

4.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.

Screenshot 2024-05-16 163815.png

Figure 2: Logging In

4.3 Creating a Group

Perform the following steps to create a group in the Fortanix DSM:

  1. Click the Groups menu item in the DSM left navigation bar and click the + button to add a new group.
    Screenshot 2024-05-16 163755.png
    Figure 3: Add Groups
  2. 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.
    • Add Group Quorum Policy: Specify the quorum policy for the group. This setting determines the number of approvals required for security-sensitive operations within the group. Adjust this policy based on your security requirements. For detailed information, refer to User's Guide: Group Quorum Policy documentation.
  3. Click the SAVE button to create the new group.

The new group has been added to the Fortanix DSM successfully.

4.4 Creating an App

Perform the following steps to create an application in the Fortanix DSM:

  1. Click the Apps menu item in the DSM left navigation bar and click the + button to add a new app.
    Screenshot 2024-05-16 163738.png
    Figure 4: Add Application
  2. On the Adding new app page, enter the following details:
    • App name: Enter the name of your application.
    • Interface (optional): Select the required interface type from the drop down menu, such as REST API, PKCS#11, JCE, CNG, or KMIP.
    • 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.
      • Set app secret key size: Select the required size of the application secret key in bytes from the drop down menu.
    • Assigning the new app to groups: Select one or more group names from the drop down menu to associate this application with that group(s).
  3. Click the Save button to add the new application.

The new application has been added to the Fortanix DSM successfully.

4.5 Copying an API Key

Perform the following steps to copy the API key from the Fortanix DSM:

  1. Click the Apps menu item in the DSM left navigation bar and click the required app from the list of apps.
  2. On the INFO tab, click the VIEW API KEY DETAILS button.
  3. From the API Key Details dialog box, copy the API Key of the app to use it later while configuring the Fortanix DSM.
    Screenshot 2024-05-16 163835.png
    Figure 5: Copy API Key

5.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, sdkms-python-sdk-<dsm_version>.zip, 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:

  1. Run the following commands to install the Fortanix Python library, sdkms-python-sdk-<dsm_version>.zip, on your system:
    pip install sdkms
  2. Run the following command to create the lookup_plugins directory adjacent to your playbook:
    mkdir lookup_plugins
  3. Run the following command to navigate to lookup_plugins directory:
    cd lookup_plugins
  4. Run the following command to open a text editor and edit the fortanix_kms.py file:
    nano fortanix_kms.py
  5. Copy the following custom plugin details in fortanix_kms.py file:
    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
    DOCUMENTATION = """ name: fortanix_kms author: Support <support@fortanix.com> version_added: "0.1" description: retrive the secrets from Fortanix DSM description: - This lookup connects the fortanix endpoint and fetch required secrets . requirement: - sdkms (fortanix python module) options: secret: description: secret name on fortanix DSM required: True api_endpoint: description: - Fortanix DSM endpoint eg https://amer.smartkey.io required: False api_apikey: description: - Fortanix DSM Application key to authenticate and retrive secret. required: False notes: - Fortanix endpoint and API key can be fetched from environment variable also export FORTANIX_API_ENDPOINT= export FORTANIX_API_KEY= - This is plugin only support API key based authentication EXAMPLE: tasks: - name: Fetch secret from fortanix DSM debug: msg="{{ lookup('fortanix_kms', 'secret=db-password', 'endpoint=','apikey=')}}" tasks: - name: Fetch secret from fortanix DSM if the environment variable is set debug: msg="{{ lookup('fortanix_kms', 'secret=db-password')}}" """ 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 </support@fortanix.com>

Where,

  • lookup refers to the Fortanix plugin name.
  • secret refers to the secret stored in Fortanix DSM.
  • endpoint refers 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.
  • apikey refers to the API key of the Fortanix DSM app as created in Section 4.5: Copying an API Key.

6.0 Verification

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.

6.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:

  1. Run the following command to update the values for the environment variable:
    export FORTANIX_API_ENDPOINT=https://eu.smartkey.io/
    export FORTANIX_API_KEY=<>
    Where,
    • FORTANIX_API_ENDPOINT refers 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_KEY refers to the API key of the Fortanix DSM app as created in Section 4.5: Copying an API Key.
  2. Create a sample YAML file 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,
    • lookup refers to the Fortanix plugin name.
    • secret refers to the secret stored in Fortanix DSM.
  3. Run the following command to execute the Ansible Playbook:
    ansible-playbook dm_env.yml
    The 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

6.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:

  1. Create a sample YAML file 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,
    • lookup refers to the Fortanix plugin name.
    • secret refers to the secret stored in Fortanix DSM.
    • endpoint refers 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.
    • apikey refers to the API key of the Fortanix DSM app as created in Section 4.5: Copying an API Key.
  2. Run the following command to execute the Ansible Playbook:
    #ansible-playbook dm_with_endpoint.yml
    The 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

Comments

Please sign in to leave a comment.

Was this article helpful?
0 out of 0 found this helpful