Configuring Terraform Files for Secret Server Integration

To integrate Terraform with Delinea Secret Server, you must copy and update required files from the Terraform provider GitHub repository:

  • Terraform configuration files (.tf)
  • Terraform variable files (.tfvars)

These files must be placed in the directory where your Terraform executable is located. Do not create them from scratch. Instead, use the examples provided in the official Delinea Terraform provider repository:

Step 1: Copy and Update the Terraform Configuration Files (.tf)

  1. Go to the Delinea Terraform provider GitHub repository terraform-provider-tss/examples/secrets.

  2. Copy the relevant example .tf file into your Terraform working directory. Rename them if needed (e.g., main.tf).

  3. Use Case Example File
    Retrieve a single secret secret_get.tf
    Retrieve multiple secrets secrets_get.tf
    Create or update a secret secret_create.tf
    Retrieve ephemeral secret ephemeral_secret_get.tf
    Retrieve multiple ephemeral secrets ephemeral_secrets_get.tf
    Delete Secret by id secret_delete.tf
    Delete multiple secrets by their id secrets_delete.tf
  4. Update each file with the required configuration definition.

    • The required Terraform version

    • The Delinea provider version (terraform-provider-tss)

    • References to variables

    • The type of secret-management operation to perform

  5. Inside your copied .tf file, update the required provider block. This ensures Terraform uses the correct provider and version to communicate with Delinea Secret Server:

  6. Copy
    terraform {
                    required_version = "> 1.10.5"
                    required_providers {
                    tss = {
                    source  = "DelineaXPM/tss"
                    version = "3.0.0"
                    }
                    }
            }

    This configuration defines how Terraform will interact with Delinea Secret Server using the tss provider. Once updated, it becomes the foundation for managing secrets securely during infrastructure provisioning.

Step 2: Copy and Update the Terraform Variable Files (.tfvars)

To ensure security when using Terraform with Delinea Secret Server, avoid storing user credentials in the .tfvars file or the .tfstate file in plain text. Use one of the supported secure methods below to protect sensitive information during infrastructure provisioning. Ephemeral resources are temporary and short-lived. They are not persisted in the Terraform state file, making them ideal for managing sensitive secrets such as usernames, passwords, or tokens.

The variable files define the values required by your configuration file.

Navigate to terraform-provider-tss/vars/secrets and choose .tfvars file that fits your use case:

Use Case Example File
Retrieve one secret secret_get.tfvars
Retrieve multiple secrets secrets_get.tfvars
Create Windows account secret secret_windows_account.tfvars
Create Oracle (Linux) account secret secret_oracle_account.tfvars
Create SSH key secret secret_ssh.tfvars
Delete secret by secret ID secret_delete.tfvars
Delete multiple secrets by their ID secrets_delete.tfvars

Static Credential Variable

The following variables must be updated in the files (secret_get.tfvars and secrets_get.tfvars):

Variable Description Note
tss_username Application account username Use the example below to set up.
tss_password Application account password Use the example below to set up.
tss_server_url Secret Server URL Use the example below to set up.
tss_secret_name Secret name Use the example below to set up.
tss_secret_templateid Template ID
  1. In Secret Server, go to Settings > All Settings > Secret Templates
  2. Select the template you want to use.
  3. In the browser URL, locate the template ID.
fields[] Field name and value pairs
  1. In Secret Server, go to Settings > All Settings > Secret Templates
  2. Select the template you want to use.
  3. On the Fields tab, make note of the field names.
generate_passphrase Flag to generate passphrase Set True to generate passphrase when creating secret. Default value is False.
generate_ssh_keys Flag to generate ssh keys 1. Set True to generate SSH keys when creating secret. Default value is False.

Example: secret_get.tfvars

Copy
tss_username   = "username"
                tss_password   = "password"
                tss_server_url = "https://example/SecretServer"
        tss_secret_id  = 1

Example: secrets_get.tfvars

Copy
tss_username   = "username"
                tss_password   = "password"
                tss_server_url = "https://example/SecretServer"
        tss_secret_id  = ["1", "2", "3"]

Using Environment Credential Variables

Storing credentials in .tfvars files can expose sensitive information. Using environment variables is a more secure option.

You can pass user credentials to Terraform via the tss_server_url, tss_username, and tss_password environment variables. You must add the prefix TF_VAR_ before these variable names so that Terraform will automatically fetch the values from these environment variables.

Set the environment variables as the following:

For Linux(secret_oracle_account.tfvars)

$ export TF_VAR_tss_username="my_app_user"

$ export TF_VAR_tss_password="Password."

$ export TF_VAR_tss_server_url="https://localhost/SecretServer"

For Windows (secret_windows_account.tfvars)

> set TF_VAR_tss_username="my_app_user"

> set TF_VAR_tss_password="Password."

> set TF_VAR_tss_server_url="https://localhost/SecretServer"

After setting these environment variables, you no longer need to store credentials in the .tfvars file. You can also execute terraform apply or terraform plan commands.

Ephemeral Resource Support (Preferred Method)

The Terraform provider now supports ephemeral resources using the latest Terraform Plugin Framework. Ephemeral resources are temporary, short-lived entities created during the execution of the terraform application operation. They are not persisted in the Terraform state file or any other Terraform-managed storage, offering enhanced security for managing sensitive data such as username, passwords, and API tokens.

Usage Example

In your .tf file, use the ephemeral block:

Usage Example

In your .tf file, use the ephemeral block:

Copy
ephemeral "tss_secret" "my_username" {
id    = var.tss_secret_id
field = "username"
}
ephemeral "tss_secret" "my_password" {
id    = var.tss_secret_id
field = "password"
}

These values can be dynamically injected into other Terraform resources:

Copy
resource "print_resource" "print_username" {
secret = ephemeral.tss_secret.my_username.secret_value
}
resource "print_resource" "print_usernames" {
secret = ephemeral.tss_secrets.my_usernames.secrets
}

Sample Terraform files demonstrating the use of ephemeral resources are available in the terraform-provider-tss/examples/secrets directory for reference. For more details and examples on using ephemeral resources, see Ephemeral Resource Support for Improved Security.

SSH Keys and Passphrase Generation in Terraform Provider for TSS

To generate SSH keys and a passphrase when creating a secret using templates that include SSH key and passphrase fields, you need to set the generate_passphrase and generate_ssh_keys flags to true. By default, these flags are set to false.

To Pass SSH Key and Passphrase Generation Arguments from Terraform Variable File:

fields = [
					{
					fieldname = "Public Key"
					itemvalue = null
					},
					{
					fieldname = "Private Key"
					itemvalue = null
					},
					{
					fieldname = "Private Key Passphrase"
					itemvalue = null
					}
					]

					# SSH Key Generation Settings
					generate_passphrase = true
					generate_ssh_keys   = true
		

Important Notes

  1. Set itemvalue to null for SSH key fields.
  2. Set the appropriate boolean values for generate_passphrase and generate_ssh_keys.

Limitations and Considerations

  1. Creation Only: SSH key generation is only supported during secret creation, not during updates.
  2. Field Values: When updating a secret with previously generated SSH keys, the provider will automatically preserve the generated values.

Delete Secret

This functionality deactivates the secret in Delinea Secret Server. It does not permanently delete the secret, but renders it inaccessible.

Delete Secret by ID

The tss_secret_deletion resource allows you to delete a secret by its ID, even if it is not managed by Terraform state. Use the following block in your .tf file:

resource "tss_secret_deletion" "delete_secret" {
				secret_id = var.tss_secret_id
				}
		

Apply this configuration to delete the secret with the ID provided in your Terraform variable file. After deletion, run terraform destroy to remove the resource from state before deleting another secret.

Delete Multiple Secrets

The tss_secret_deletion resource also supports deleting multiple secrets by their IDs, even if they are not managed by Terraform state. Use the following block in your .tf file:

resource "tss_secret_deletion" "delete_secrets" {
				for_each  = toset(var.tss_secret_ids)
				secret_id = tonumber(each.key)
				}
		

This configuration deletes all secrets listed in the set provided from the Terraform variable file. Each deletion is tracked separately in state.

Important Notes

  • After deleting, run terraform destroy to clean up the state before deleting new secrets.
  • Deletion is performed during the terraform apply phase.
  • The resource is tracked in state to prevent repeated deletion attempts.
  • Creating... in logs indicates the deletion is being performed.

Step 3: Complete Configuration

After completing the configuration, your Terraform executable directory should include:

  • The .tf configuration file

  • The .tfvars variable file

  • Terraform executable (terraform)