---
title: "Fortanix DSM with Ansible Lookup Plugin"
slug: "fortanix-dsm-with-ansible-lookup-plugin"
updated: 2026-07-24T17:52:08Z
published: 2026-07-24T17:52:08Z
canonical: "support.fortanix.com/fortanix-dsm-with-ansible-lookup-plugin"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.fortanix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fortanix DSM with Ansible Lookup Plugin

## 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 DSM, this plugin facilitates the secure retrieval 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 the Ansible Python module must be installed on the system.

```bash
sudo apt install python
sudo apt install python3-pip
sudo apt install ansible
```
- Fortanix DSM must be accessible. *For more information, refer to* [*Section 5.1: Signing Up*](/v1/docs/using-fortanix-data-security-manager-with-ansible-lookup-plugin#51-signing-up) *and* [*Section 5.2: Creating an Account*](/v1/docs/using-fortanix-data-security-manager-with-ansible-lookup-plugin#52-creating-an-account)*.*

## 3.0 Product Tested Version

The following product versions were tested:

- Fortanix DSM version 4.23+.
- Fortanix DSM version 5.6.
- Ansible Lookup Plugin version 2.9, 2.10, 2.16.3, and 2.19.9.
- Python version 3.12.3

## 4.0 Architecture Diagram

![Ansible_Architecture_Diagram](https://cdn.us.document360.io/c3bd85d2-4ad8-4d85-9f60-f1c168a3aad9/Images/Documentation/Ansible_Architecture_Diagram.png)

**Figure 1: Ansible architecture diagram**

Ansible Playbooks are a set of instructions for automating tasks. It interacts with the Fortanix DSM application over HTTPS (Hypertext Transfer Protocol Secure) on port 443 to retrieve secrets for subsequent Ansible deployments.

The Ansible Playbook initiates the request using a Lookup Plugin, facilitating secure communication with Fortanix DSM. Fortanix DSM then processes the request and returns 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 DSM cloud service, you must register an account at <Your_DSM_Service_URL>. For example, [https://amer.smartkey.io.](https://amer.smartkey.io.) On-premises customers use the KMS URL, and the SaaS customers can use the URLs as listed [*here*](https://support.fortanix.com/hc/en-us/articles/4406135346068-Fortanix-DSM-SaaS-Global-Availability-Map) based on the application region.

*For more information on how to set up the Fortanix DSM, refer to the* [*Sign Up for Fortanix Data Security Manager SaaS*](https://support.fortanix.com/docs/users-guide-sign-up-for-fortanix-data-security-manager-saas)*.*

### 5.2 Creating an Account

Access <Your_DSM_Service_URL> in a web browser and enter your credentials to log in to Fortanix DSM.

![](https://cdn.us.document360.io/c3bd85d2-4ad8-4d85-9f60-f1c168a3aad9/Images/Documentation/DSM_SaaS_Login_page(15).png)

**Figure 2: Logging in**

*For more information on how to set up an account in Fortanix DSM, refer to the* [*Getting Started with Fortanix Data Security Manager - UI*](https://support.fortanix.com/docs/users-guide-getting-started-with-fortanix-data-security-manager-ui)*.*

### 5.3 Creating a Group

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

1. In the DSM left navigation panel, click the **Groups** menu item, and then click **ADD GROUP** to create a new group.

![](https://cdn.us.document360.io/c3bd85d2-4ad8-4d85-9f60-f1c168a3aad9/Images/Documentation/Add-Group(65).png)

**Figure 3: Add groups**
2. On the **Adding new group** page:
  1. **Title**: Enter a name for your group.
  2. **Description** (optional): Enter a short description of the group.
3. Click **SAVE** to create the new group.

*For more information about groups, refer to* [*Definitions*](/v1/docs/dsm-definitions#40-groups)*.*

> [!NOTE]
> TIP
> 
> It is recommended to configure a **Key undo policy** for groups for the cryptographic keys used by the application before creating or using the keys. Without a configured **Key undo policy**, key deletion is permanent and the deleted key cannot be recovered. Deleting an encryption key may result in permanent loss of access to the protected data and service disruption for applications that depend on the deleted key. *For detailed steps, refer to* [*Key Undo Policy*](/v1/docs/fortanix-dsm-key-undo-policy)*.*

### 5.4 Creating an Application

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

1. In the DSM left navigation panel, click the **Apps** menu item, and then click **ADD APP** to create a new app.

![](https://cdn.us.document360.io/c3bd85d2-4ad8-4d85-9f60-f1c168a3aad9/Images/Documentation/Add-App(63).png)

**Figure 4: Add application**
2. On the **Adding new app** page:
  1. **App name**: Enter the name for your application.
  2. **ADD DESCRIPTION** (optional): Enter a short description of the application.
  3. **Authentication method**: Select the default **API Key** as the authentication method from the drop down menu. *For more information on these authentication methods, refer to the* [*User's Guide: Authentication*](https://support.fortanix.com/docs/users-guide-authentication)*.*
  4. **Assigning the new app to groups**: Select the group created in [*Section 5.3: Creating a Group*](/v1/docs/using-fortanix-data-security-manager-with-ansible-lookup-plugin#53-creating-a-group)[](/v1/docs/using-data-security-manager-with-idcentral-key-management#43-creating-a-group)from the list.
3. Click **SAVE** to add the new application.

*For more information about applications, refer to* [*Definitions*](https://support.fortanix.com/docs/dsm-definitions#50-applications)*.*

### 5.5 Copying the API Key

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

1. In the DSM left navigation panel, click the **Apps** menu item, and then click the app created in [*Section 5.4: Creating an Application*](/v1/docs/using-fortanix-data-security-manager-with-ansible-lookup-plugin#54-creating-an-application) to go to the detailed view of the app.
2. On the **INFO** tab, click **VIEW API KEY DETAILS**.

From the **API Key Details** dialog box, copy the **API Key** of the app to use in [*Section 7.0: Configuring Endpoints and API Key*](/v1/docs/using-fortanix-data-security-manager-with-ansible-lookup-plugin#70-configuring-endpoints-and-api-key).

## 6.0 Install 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 such as 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 on your system:

```bash
sudo pip install sdkms
```
2. Run the following command to create the `lookup_plugins` directory adjacent to your playbook:

```bash
mkdir lookup_plugins
```
3. Run the following command to navigate to `lookup_plugins` directory:

```bash
cd lookup_plugins
```
4. Run the following command to open a text editor and edit the `fortanix_kms.py` file:

```bash
nano fortanix_kms.py
```
5. Copy the following custom plugin details in `fortanix_kms.py` file:

```bash
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 Configure 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:

1. Run the following command to update the values for the environment variable:

```bash
export FORTANIX_API_ENDPOINT= <Your_DSM_Service_URL>
export FORTANIX_API_KEY= <API_KEY>
```

Where,
  - `FORTANIX_API_ENDPOINT` refers to the Fortanix DSM URL. On-premises customers use the KMS URL and the SaaS customers can use the URLs as listed [*here*](/v1/docs/fortanix-dsm-saas-global-availability-map) based on the application region.
  - `FORTANIX_API_KEY` refers to the API key of the Fortanix DSM app as created in [*Section 5.5: Copying the API Key*](/v1/docs/using-fortanix-data-security-manager-with-ansible-lookup-plugin#55-copying-an-api-key).
2. Create a sample YAML file, `dm_env.yml`, and add the following lookup tag in it:

```bash
- 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:

```bash
ansible-playbook dm_env.yml
```

The following is the output of the command:

```bash

[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 the Fortanix endpoint and API key in the Ansible Playbook.

Perform the following steps:

1. Create a sample YAML file, `dm_with_endpoint.yml`, and add the following lookup tag in it:

```bash
- 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 the KMS URL and the SaaS customers can use the URLs as listed [*here*](/v1/docs/fortanix-dsm-saas-global-availability-map) based on the application region.
  - `apikey` refers to the API key of the Fortanix DSM app as created in [*Section 5.5: Copying the API Key*](/v1/docs/using-fortanix-data-security-manager-with-ansible-lookup-plugin#55-copying-an-api-key).
2. Run the following command to execute the Ansible Playbook:

```bash
ansible-playbook dm_with_endpoint.yml
```

The following is the output of the command:

```bash
    [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
```

Fortanix Data Security Manager (DSM) is the world’s first cloud service secured with Intel® SGX. With Fortanix DSM, you can securely generate, store, and use cryptographic keys and certificates, as well as other secrets such as passwords, API keys, tokens, or any blob of data. Your business-critical applications and containers can integrate with Fortanix DSM using legacy cryptographic interfaces (PKCS#11, CNG, and JCE) or using the native Fortanix DSM RESTful interface.

## Related

- [Exporting Fortanix DSM Keys to Cloud Providers for BYOK - Alibaba](/exporting-dsm-keys-to-cloud-providers-for-byok-alibaba.md)
- [Azure Key Vault Group Setup](/fortanix-dsm-azure-key-vault-cdc-group-setup.md)
- [Fortanix DSM with EDB Postgres for TDE](/fortanix-dsm-with-edb-postgres-for-tde.md)
- [Azure Key Vault Bring Your Own Key](/fortanix-dsm-azure-key-vault-byok-bring-your-own-key.md)
- [Port Requirements](/fortanix-data-security-manager-port-requirements.md)