Securden – Ansible Integration

This guide will take you through the process of setting up and using the Ansible lookup plugin through Securden PAM for securely retrieving account credentials, keys, and secrets.

Summary of steps:

• Setup the Securden Ansible Lookup Plugin

• Ansible Configuration

• Accessing Account Information

• Accessing Additional Fields

• Accessible Data Fields in the Lookup Plugin

1. Securden Ansible Lookup Plugin Setup

First, set up the Securden lookup plugin by obtaining the securden.py file. This is available for download as a .zip file under the Ansible configurations page in the Securden Admin tab. Place this file in a folder named lookup_plugins within your Ansible project directory. Alternatively, you can also set the ' lookup_plugins’ path in your ansible.cfg.

2. Ansible Configuration

To use the Securden Ansible lookup plugin, you must configure the following environment variables. The variables will differ based on your operating system (Windows, Mac, or Linux).

These variables facilitate secure communication with the Securden API and can be set directly in the environment or passed as parameters in your playbook.

Required Environment Variables

• SECURDEN_URL: The URL of the Securden server.

• SECURDEN_AUTHTOKEN: The authentication token for secure API access.

• SECURDEN_VERIFY_CERT: Requires Boolean value to automatically verify the server certificate.

• SECURDEN_CERT: The SSL certificate for secure communication (can be a certificate string or a file path).

• SECURDEN_ORG: If you are using the MSP edition, provide the organization's domain.

Setting Environment Variables

For Mac/Linux:

Run the following commands in your terminal to export the environment variables:

• export SECURDEN_URL=https://<SECURDEN_SERVER_URL>

• export SECURDEN_AUTHTOKEN=<SECURDEN_AUTHTOKEN>

• export SECURDEN_VERIFY_CERT=True

If need to provide certificate manually just provide the certificate by,

• export SECURDEN_CERT=<SECURDEN_CERT>

If you are using the MSP edition, provide the organization's domain.

• export SECURDEN_ORG=<ORG_DOMAIN>

For Windows:

Run the following commands in Command Prompt (CMD) to set the environment variables:

• set SECURDEN_URL=https://<SECURDEN_SERVER_URL>

• set SECURDEN_AUTHTOKEN=<SECURDEN_AUTHTOKEN>

If need to provide certificate manually just provide the certificate by,

• set SECURDEN_CERT=<SECURDEN_CERT>

If you are using the MSP edition, provide the organization's domain.

• set SECURDEN_ORG=<ORG_DOMAIN>

Notes:

• The SECURDEN_URL must include either http or https based on your product URL.

• The SECURDEN_CERT can either be a value string of the certificate or a file path pointing to the SSL certificate file. For example:

export SECURDEN_CERT=/path/to/your/certificate.pem

This configuration ensures that Ansible can securely communicate with the Securden API and retrieve account details.

Accessing Account Information

You can use the following Ansible code snippet to fetch account information:

- name: Test custom lookup plugin returning an object 

hosts: localhost 

tasks: 

- name: Fetch account information using the custom lookup plugin 

    set_fact: 

    account: "{{ lookup('securden', account_id='2000000003455') }}" 



- name: Set Password 

    set_fact: 

    password: "{{ account.password }}" 



- name: View Password 

    debug: 

    msg: "Account Password: {{password}}" 

In the example above:

• lookup('securden') invokes the lookup plugin.

• account_id represents the Securden account ID. You can also specify account_name and account_title as needed.

To access various fields, use the following:

• For Password: account.password

• For Account Name: account.account_name

• For Port: account.port

3. Accessing Additional Fields

If an account type has additional fields associated with it, you need to specify a ‘key_field’ in your lookup code:

tasks: 

    - name: Fetch account information using the custom lookup plugin 

      set_fact: 

        account: "{{ lookup('securden', account_id='2000000003455', key_field='field_name') }}" 

    - name: Set Password 

      set_fact: 

        additional_field: "{{ account.key_value }}" 

By providing the name of the additional field in key_field, you can retrieve its value using account.key_value parameter.

4. Accessible Data Fields in the Lookup Plugin

Here is a list of the account attributes that can be retrieved for use in Terraform using the Securden plugin:

• account_id

• account_name

• account_title

• password

• key_value

• private_key

• putty_private_key

• passphrase

• ppk_passphrase

• address

• client_id

• client_secret

• account_alias

• account_file

• default_database

• sql_server_port

• mysql_port

• oracle_sid

• oracle_service_name

• oracle_port

Note

Data can only be retrieved for fields that exist in the account. If a field is unavailable, the system will return a message indicating that the account does not contain the requested field.

Bulk Password Retrieval

You have the option to fetch account passwords in bulk from Securden at once using a 'get_passwords' action

Here’s an example to fetch multiple account passwords:

- name: Test custom lookup plugin returning an object 

  hosts: localhost 

  vars: 

    - account_ids: 

      - 2000000002788 

      - 2000000002800 



  vars_files: 

    - vars.yml 



  tasks: 



   - name: Fetch account information using the custom lookup plugin 

    set_fact: 

      data: "{{ lookup('securden', action='get_passwords', account_ids=account_ids) }}" 



  - name: Debug fetched data 

    debug: 

      var: data 



  - name: Set Password 

    debug: 

      msg: "{{ data.passwords['2000000002788'] }}" 

Accounts whose passwords need to be retrieved can be called by their respective account IDs.

Execute PAM Functions in Ansible

You can utilize features available in Securden by passing code snippets in Ansible

For example,

To update account password, action argument provided with the name of action you needs to perform, Let take ‘update_password’ to update password of an account.

tasks:
- name: Update Account Password
  set_fact:
    data: "{{ lookup('secunden', action='update_password', account_id='2000000004489', password='Pearalagu404')}}"
- name: View Message
  debug:
    msg: "{{data.message}}"

From the above image of code snippet, action is name of PAM function to be performed. In this case, update_password is passed with the details of account_id and the password.

List of product functions that can be executed

You can execute commands using certain parameters and supply the required account fields to get the necessary results (such as an account password). All the possible functions are listed below.

1) Update the password of an account

• Parameter name: update_password

• Required Account Fields:

  • account_id

  • password

  • reason (in string)

• Values obtained in return:

  • status_code – Contains the status code of the process.

  • message – Contains success message if password was updated successfully or a failure message with specific cause of failure.

2) Generate a complex password

• Parameter name: generate_password

• Required fields

  • policy_name (If the password needs to be generated according to a specific password policy – the default password policy will be used otherwise)

• Values obtained in return:

  • password – Contains a newly generated password

Example

 - name: Generate Password with policy name or id 

      set_fact: 

        data: "{{ lookup('securden', action='generate_password', policy_name='Securden policy') }}" 



    - name: View Password 

      debug: 

        msg: "New Password with policy: {{data.password}}" 

From the above example return data stored in data in set_fact module and accessed by data.password as in debug module

3) Add a new account

• Parameter name: add_account

• Required fields

  • account_title
  • account_name
  • account_type
  • ipaddress
  • notes
  • tags
  • personal_account
  • folder_id
  • password
  • account_expiration_date
  • distinguished_name
  • account_alias
  • domain_name

• Values obtained in return:

  • Message – Contains success message if a new account was created successfully or a failure message with specific cause of failure.
  • ID – Account ID of the newly created account.

4) List all the accounts in a folder

• Parameter name: list_accounts

• Required fields

• folder_id

• search_text

• Page (page number)

• page_limit (account count per page)

• get_full_account_details

• get_record_count_details (The number of accounts to be listed can be specified using this attribute.)

• Values obtained in return:

• record_details

  • account_address

• account_category

  • account_name

  • account_type

  • reset_due_on

  • permissions

    • open_connection

    • view

    • modify

    • manage

  • last_modified_date

Elaborate Account Details

You have the option to obtain the following data by setting the get_full_account_details attribute to True:

• owner_name

• password_policy

• folder_id

• folder_name

• owner_id

• expiry_date

• tags

• notes

• additional_fields

  • Text

  • Passcode

  • Select

  • Date

  • URL

• template_additional_fields

  • RDP Port

Get Record Count Details

You can obtain the following data by adding get_record_count_details attribute as True:

• record_count_details

  • total_pages – Total pages returned

  • total_records – Total number of accounts listed

5) Get a file stored in an account

• Parameter name: get_file

• Required fields:

  • account_id

• Values obtained in return:

  • It returns the content that a file contains on script

For Example

- name: Fetch account additional file 

      set_fact: 

        file_data: "{{ lookup('securden', action='get_file', account_id='2000000011710') }}" 



- name: View File 

      debug: 

6) Get an additional file stored in an account

• Parameter name: get_additional_file

• Required fields:

  • account_id

  • field_name

• Values obtained in return:

  • It returns the file content

For Example

- name: Fetch account additional file 

    set_fact: 

    file_data: "{{ lookup('securden', action='get_additional_file', account_id='2000000011710', field_name='File Field Name') }}" 

From the above example file content stored in file_data

7) Create a folder

• Feature name: add_folder

• Required field:

  • folder_name

  • description

  • notes

  • parent_folder_id

  • inherit_parentshare

• Values obtained in return:

  • folder_id - Contains the id of the newly created folder.

  • Message – Success/Failure message

8) Move an account or multiple accounts from a folder to another

• Parameter name: move_accounts

• Required field:

  • account_ids

  • source_folder_id

  • destination_folder_id

• Values obtained in return:

  • status_code

  • message - Success/Failure message

9) Delete one or more accounts

• Parameter name: delete_accounts

• Required field:

  • account_ids

  • reason

  • delete_permanently

• Values obtained in return:

  • message - Success/failure message

  • IDs deleted successfully - Contains list of deleted account IDs

10) Delete folder

• Parameter name: delete_folders

• Required field:

  • folder_ids

  • reason

• Values obtained in return:

  • message - Success/failure message

  • IDs deleted successfully – Contains the list of deleted folder IDs