Introduction¶

Securden provides a seamless, and an efficient way for developers to integrate Securden’s powerful password management abilities into their applications.

Installation of Securden Gem¶

ChefPUPPETTERRAFORM

This guide will take you through the process of installing and integrating Securden with Chef for secure programmatic access to credentials, tokens, and keys.

To integrate with the Chef environment, you need to initiate the installation of the Securden gem. Execute the following command:

chef gem install securden

Refer Securden | RubyGems.org for more info and latest updates

To integrate with the Puppet module, initiate the installation of the Securden to access credentials dynamically. Executing the following command:

puppet module install securden-securden

Refer Securden Plugin for more and lates updates.

This guide will take you through the process of setting up and using Securden PAM as a provider block in Terraform to securely retrieve account credentials, keys, and secrets using APIs.

Prerequisites¶

ChefPUPPETTERRAFORM

The Securden Chef plugin requires certain key parameters to authenticate and access Securden. The parameters required are:

Securden Server URL/Host URL
Authentication Token
SSL Certificate Path (Optional)

The Securden Puppet plugin requires certain key parameters to authenticate and access Securden. The parameters required are:

Securden Server URL/Host URL
Authentication Token
SSL Certificate Path

Summary of steps:

Adding Securden to Terraform
Initializing Securden
Fetch Account Data
Accessing Account Data
Fetch Multiple Accounts
Account Operations

Adding Securden Provider

a. Initialize Securden Provider

Add the following block to your file to initialize the Securden provider:

ternaform {
required_providers {
securden = {
    source = "SecurdenDevops/securden"
    }
}

Refer SecurdenDevOps/securden | Terraform Registry for versions and updates

b. Declare Variables to Store Securden Attributes

Define variables to store the Securden authentication token, server URL and Optionally SSL Certificate file path.

    variable "server_url" {
    type = string
    default = "__server_url__"
    }

    variable "authtoken" {
        type = string
        default = "__authtoken__"
    }

    variable "certificate" {
        type = string
        default = "/path/to/certificate.pem"
    }

Initialize these variables with the correct values for your environment. For example, using environment variables like:

Windows
- set TF_VAR_authtoken=
- set TF_VAR_authtoken=
- set TF_VAR_certificate=’path/to/certificate.pem’
Mac/Linux
- export TF_VAR_server_url=
- export TF_VAR_authtoken=
- export TF_VAR_certificate=’path/to/certificate.pem’

💡 Note: Certificate (SSL Certificate) is Optional: If an SSL certificate is provided, the connection will strictly use it. If the certificate is incorrect, the connection will be failed. If no certificate is provided, the plugin will attempt to auto-fetch the SSL certificate. If auto-fetch fails, SSL verification will be disabled, and the request will proceed without SSL verification.

Securden Server URL¶

You can get the ‘server_url’ from Securden by navigating to Admin >> General >> Securden Server Connectivity section in the Securden web interface.

API Token for Authentication¶

Securden server supports API token-based authentication for programmatic access to credentials. You can generate and copy the auth token from the Securden web interface by navigating to Admin >> API Access >> Create and Manage API Tokens.

You need to specify the API reference name and description for identification purposes.
You need to specify the IP addresses or a range of IP from which this token can be used.
You can create a static (with a permanent or a time limited validity) or a dynamic auth token.
You can specify the scope of the actions this auth token by selecting the required capabilities from the list.
Once the preferences are set, click on Create Token.
Now copy the authentication token.

Utilizing Securden Gem¶

ChefPUPPETTERRAFORM

To integrate the Securden functionality into your Chef recipe, follow the process outlined below.

Step 1: Installation of Securden gem

To integrate with the Chef plugin, initiate the installation of the Securden to access credentials dynamically. Executing the following command:

chef gem install securden

Step 2: Declare this statement at the top of your recipe for proper dependency resolution:

require 'securden'

💡 Note: Every string input should be in single quotes. Do not use double quotes, it will encode the string and may acquire format issue.

Step 3: Initializing Securden in Chef

The following Ruby block initializes the Securden plugin, establishing the necessary connection to the Securden server using the parameters defined in the attributes:

    require 'securden'

    Securden::Init.new(
        server_url: '__server_url__',
        authtoken: '__authtoken__',
        # Optional
        certificate: 'path/to/certificate.pem',
    )

Here SSL Certificate is optional, if an SSL certificate is provided, the connection will strictly use it. If the certificate is incorrect, the connection will fail.If no certificate is provided, the plugin will attempt to auto-fetch the SSL certificate. In the rare event that it is unable to fetch the certificate it will automatically run by disabling the certificate verification requirement. All data in transit is still secured by https protocol.

The essential configuration parameters can be declared in the Puppet using the following command:

    class { 'secunden':
    server_url => '__server_url_';
    authtoken => '__authtoken_';
    certificate => "/path/to/certificate",
}

SSL Certificate

Here SSL Certificate is optional, if an SSL certificate is provided, the connection will strictly use it. If the certificate is incorrect, the connection will fail.

If no certificate is provided, the plugin will attempt to auto-fetch the SSL certificate. In the rare event that it is unable to fetch the certificate it will automatically run by disabling the certificate verification requirement. All data in transit is still secured by https protocol.

Once Securden has been initialized, we can start performing operations such as Get, Add, Edit and Delete on accounts.

Define the Securden provider block, referencing the previously declared variables:

    provider "securden" {
    server_url = var.server_url
    authtoken = var.authtoken
    # optional
    certificate = var.certificate
}

Fetching Account Data from Securden¶

To retrieve account details, use the ‘account.get’ command. This command allows for the retrieval of a specific account based on the account ID or combination of account name and title attributes.

ChefPUPPETTERRAFORM

a. Fetching account by its Account ID.

    account_data = Securden::Account.get(
    account_id: 2000000000018,
)

b. Fetching account by its Account Title and Name.

In this block, the Securden::Account.get (account_title: ACCOUNT_TITLE) method is invoked to retrieve the account corresponding to the specified account title (Test) and account name (Two). The account's attributes, such as the password, are then accessed and displayed in the log output. You can either use only account title or account name or both, providing both account title and name will fetch by combination of account name title.

    account_data = Securden::Account.get(
    account_title: 'Account Title',
    account_name: 'Account Name',
    account_type: 'Web Account',
)

The account's attributes, such as the password, are then accessed by account attributes.

    Chef::Log.warn("Account_data: #{account_data}")

If justification is enforced for either the account or for password retrieval, a reason must be provided. Similarly, if ticketing system ID is enforced, a valid ticket ID must be provided.

These parameters are to be included.

ticket_id – For providing ticket ID.
reason – For providing reason.

To retrieve account details, use the ‘get_account’ command. This command allows for the retrieval of a specific account based on the account ID or combination of account name and title attributes.

$account = securden::get_account(
account_title => "Account Title",
account_name => "Account Name",
account_type => "Account Type",
)

Fetching account by its Account Title and Name.

You can use the following command to retrieve data using multiple account attributes:

$new_account = secunden:add_account(
account_title => 'Test Account',
account_name => 'Test Name',
account_type => 'Web Account',
)

If justification is enforced for either the account or for password retrieval, a reason must be provided. Similarly, if ticketing system ID is enforced, a valid ticket ID must be provided.

These parameters are to be included.

ticket_id – For providing ticket ID.
reason – For providing reason.

Accessing account

Here are some examples of how to access various credentials from the Securden data block:

notice("Password: ${account[‘password’]}")

Can access account data by its account attribute,

$account_passcode = $account[‘password’]

To fetch account data from Securden, use a data block. Here’s an example to fetch SSH key credentials:

    data "secunden_account" "account_data" {
    account_id = 2000000001800
}

💡 Note: You can retrieve specific accounts using account_id, account_name, or account_title. If you use account_name, you can also include account_title to ensure you don’t retrieve multiple accounts in case there are several accounts with the same name.

If justification is enforced for either the account or for password retrieval, a reason must be provided. Similarly, if ticketing system ID is enforced, a valid ticket ID must be provided.

These parameters are to be included.

- ticket_id – For providing ticket ID.

- reason – For providing reason.

Accessing Account Data

Using Output block to display data fetched from securden

    output "account_password" {
    value = data.secunden_account.account_data.account["password"]
}

Here are some examples of how to access various credentials from the Securden data block:

For Password: data.securden_account.account_data.account[“password”]
For PuTTY Private Key: data.securden_account.account_data.account[“putty_private_key”]
For PuTTY Passphrase: data.securden_account.account_data.account[“ppk_passphrase”]

Accessing Additional Field

If your account type has additional fields in Securden, you can retrieve the value of additional fields by specifying the additional field name:

    output "additional_field" {
    value = data.secunden_account.account_data.account["additional_field_name"]
    }

Accessible Account Fields

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 the attributes that are available in the account. For any other fields, or if there is a non-existent value - a null value will be returned when a code is executed.

Fetching Multiple Accounts¶

ChefPUPPETTERRAFORM

To retrieve multiple accounts from securden required to provide multiple account ids, Chef can access the account data of multiple accounts.

    accounts = Secunden::Accounts.get(
    account_ids: [2000000001800, 2000000002000]
)

Account data can be accessed by its account ID, accounts['2000000005222']['password'] account ID should be passed as string to get account data.

💡 Note: Utilize Securden::Account.get for single account and Securden::Accounts.get for multiple accounts

Also, List of account dictionary can be provided to fetch multiple accounts from securden, Chef can access the account data of multiple accounts.

Example:

Fetching Multiple Accounts

To retrieve multiple accounts from securden need to provide a list of account ids, and can access those accounts by its account ID.

$updated_account = secunden:redit_account(
account_id => 2000000001800,
account_title => 'Test Account Edited',
account_name => 'Test Account Edited',
account_type => 'Web Account'
)

💡 Note: Utilize securden::get_account for single account and securden::get_accounts for multiple accounts

We can fetch multiple accounts from Securden at once by providing list of account ids to be fetched.

Example: Fetching Multiple Accounts

    output "first_account" {
        value = data.secunden_accounts.multiple_accounts["2000000001800"]["password"]
    }
}

To retrieve the data of a specific account:

output "first_account" {
value = data.secunden_accounts.multiple_accounts["2000000001800"]["password"]
}

Add Account¶

ChefPUPPETTERRAFORM

To add or update details of an account on Securden from Chef, you need to provide all the data that is to be updated along with their account attributes - account ID.

Use the following command block to add a new account in Securden:

account = Securden::Account.add(
account_title: 'Account Title',
account_name: 'Account Name',
account_type: 'Web Account',
)

In the example above, account_title, account_name and account_type are mandatory fields. You can add other fields based on the account type as per your requirements.

List of fields that can be added to an account.

account_title - String
account_name - String
account_type - String
ipaddress - String
notes - String
tags - String
personal_account - Boolean
folder_id - Long
password - String
account_expiration_date - String (Date Format- DD/MM/YYYY)
distinguished_name (Required for LDAP domain accounts) -String
account_alias (Required for AWS IAM accounts) - String
domain_name (Required for Google Workspace accounts) - String

Adding a New Account in Securden

$new_account = secunden:add_account(
account_title => 'Test Account',
account_name => 'Test Name',
account_type => 'Web Account',
)

In the example above, account_title, account_name and account_type are mandatory fields. You can add other fields based on the account type as per your requirements.

List of fields can be added to an account.

account_title - String
account_name - String
account_type - String
ipaddress - String
notes - String
tags - String
personal_account - Boolean
folder_id - Long
password - String
account_expiration_date - String (Date Format- DD/MM/YYYY)
distinguished_name (Required for LDAP domain accounts) -String
account_alias (Required for AWS IAM accounts) - String
domain_name (Required for Google Workspace accounts) - String

We can perform various account operation whereas Add Account, Edit Account and Delete Accounts

a. Add Account in Securden

For account add operation we will be using “securden_add_account” data block, Example:

data "securden_add_account" "added_account"(  
account_name = "Account Name"  
account_title = "Account Title"  
account_type = "Web Account"

The above are the required fields to add account in Securden. In addition to that there are some other optional fields that can be provided along with your account type and requirements.

List of Optional Fields

Here is a list of the account attributes that can be added for add account operation:

password
personal_account
ipaddress
folder_id
notes
tags
account_expiration_date
distinguished_name
account_alias
domain_name

b. Edit Account

To edit the existing account in Securden we will be using “securden_edit_account” data block, Example:

data "securden_edit_account" "updated_account"{ account_id = 2000000001800 account_type = "Web Account" account_title = "Updated Title"
}

Here “account_id” and “account_type” are required field and rest of the fields are optional, For detail view see “securden_edit_account” under Data Source.

C. Delete Accounts

To delete accounts in Securden we will be using “securden_delete_accounts” data block, Example:\

    data "secunden_delete_accounts" "deleted_accounts" {
    account_ids = [2000000001800, 2000000002800]
    reason = "Reason for the account deletion"
}

Here account_ids alone require field and reason is a optional field, View More in securden_delete_accounts under Data Source

Update/ Edit Existing Account¶

ChefPUPPETTERRAFORM

Securden::Account.edit(
account_id: 2000000004745,
account_title: 'New Title',
account_name: 'Name Name',
account_type: 'Web Account'
)

List of account attributes required to update account

account_id (Required) - Long
account_title - String
account_name - String
account_type - String
Ipaddress - String
Notes - String
Tags - String
folder_id - Long
overwrite_additional_fields - Boolean
account_expiration_date - String (Date Format- DD/MM/YYYY)
distinguished_name (Required for LDAP domain accounts) - String
account_alias (Required for AWS IAM accounts) - String
domain_name (Required for Google Workspace accounts) - String

To add or update details of an account on Securden from Puppet you need to provide all the data that is to be updated along with their account attributes - account ID.

$updated_account = secunden:redit_account(
account_id => 2000000001800,
account_title => 'Test Account Edited',
account_name => 'Test Account Edited',
account_type => 'Web Account'
)

account_id (Required) - Long
account_title - String
account_name - String
account_type - String
Ipaddress - String
Notes - String
Tags - String
folder_id - Long
overwrite_additional_fields - Boolean
account_expiration_date - String (Date Format- DD/MM/YYYY)
distinguished_name (Required for LDAP domain accounts) - String
account_alias (Required for AWS IAM accounts) - String
domain_name (Required for Google Workspace accounts) - String

To edit the existing account in Securden we will be using “securden_edit_account” data block, Example:

data "securden_edit_account" "updated_account"{ account_id = 2000000001800 account_type = "Web Account" account_title = "Updated Title"
}

Here “account_id” and “account_type” are required field and rest of the fields are optional, For detail view see “securden_edit_account” under Data Source.

Delete Accounts¶

ChefPUPPETTERRAFORM

To delete accounts on Securden from Puppet you need to provide the list of account IDs to be deleted. You may have to provide a reason for deletion of accounts, which is optional.

Securden::Accounts.delete(
account_ids: [2000000004745, 2000000004739],
reason: 'Reason for Account Deletion',
)

Once the command is executed, you will get a list of account ids that were successfully deleted from Securden.

In Securden, deleted accounts are moved to the ‘Recently Deleted Accounts’ section. You can use ‘delete_permanently’ key to delete accounts permanently. An example is shown below

Securden::Accounts.delete(
account_ids: [2000000004745, 2000000004739],
reason: 'Reason for Account Deletion',
delete_permanently: true
)

To delete accounts on Securden from Puppet you need to provide the list of account IDs to be deleted. You may have to provide a reason for deletion of accounts, which is optional.

$deleted_account_ids = secunden::delete_accounts(
account_ids => [2000000001800, 2000000002000],
reason => "Testing from Puppet",
)

Once the command is executed, you will get a list of account ids that were successfully deleted from Securden.

In Securden, deleted accounts are moved to the ‘Recently Deleted Accounts’ section. You can use ‘delete_permanently’ key to delete accounts permanently. An example is shown below:

$deleted_account_ids = secunden::delete_accounts(
account_ids => [2000000001800, 2000000002000],
reason => "Testing from Puppet",
delete_permanently => true
)

To delete accounts in Securden we will be using “securden_delete_accounts” data block, Example:\

data "secunden_delete_accounts" "deleted_accounts" {
account_ids = [2000000001800, 2000000002800]
reason = "Reason for the account deletion"
}

Here account_ids alone require field and reason is a optional field, View More in securden_delete_accounts under Data Source

Complete List of Account Attributes¶

The following is a comprehensive list of account attributes that can be used within the Securden plugin for Chef integration:

account_id - Unique identifier for the account.
account_name - Name of the account.
account_title - Title associated with the account (e.g., job title or description).
password - The password for the account.
private_key - The private key associated with the account.
putty_private_key - The PuTTY-compatible private key used for SSH connections.
passphrase - The passphrase required to unlock the private key (if applicable).
ppk_passphrase - The passphrase specific to the PuTTY private key (if applicable).
address - The network address (e.g., IP address or domain) associated with the account.
client_id - The client identifier used for application or API authentication.
client_secret - The client secret, typically used in OAuth or API key-based authentication.
account_alias – AWS IAM account ID or Account name.
account_file - A file associated with the account, possibly containing additional account-related information.
default_database - The default database associated with the account, if applicable.
oracle_sid - The Oracle SID (System Identifier) for the account.
oracle_service_name - The Oracle service name associated with the account.
port - The port number used for communication with the account’s service or application.
Additional Fields: Any additional fields that may be specific to the account or created dynamically during the account setup. These fields will be named based on the custom configuration and integration requirements, often reflecting the unique characteristics or environment of the account.