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:

• terraform-provider-tss/examples/secrets

• terraform-provider-tss/vars/secrets

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

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

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

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

Copy

terraform {
                required_version = "> 1.11.0"
                required_providers {
                tss = {
                source  = "DelineaXPM/tss"
                version = "4.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:

Static Credential Variables

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

Example: secret_get.tfvars

Use only tss_username and tss_password or tss_token in secret_get.tfvars depending on whether you use credentials or token-based authentication.

Credentials authentication

                tss_username   = "username"
                tss_password   = "password"
                tss_server_url = "https://yourtenantName.secretservercloud.com"
                tss_secret_id  = 1

Token authentication

                tss_token      = "token"
                tss_server_url = "https://yourtenantName.secretservercloud.com"
                tss_secret_id  = 1

Example: secrets_get.tfvars

Use only tss_username and tss_password or tss_token in secrets_get.tfvars depending on whether you use credentials or token-based authentication.

Credentials authentication

                tss_username   = "username"
                tss_password   = "password"
                tss_server_url = "https://yourtenantname.secretservercloud.com"
                tss_secret_id  = ["1", "2", "3"]

Token authentication

                tss_token      = "token"
                tss_server_url = "https://yourtenantname.secretservercloud.com"
                tss_secret_id  = ["1", "2", "3"]

Password Fields (Terraform 1.11+)

Starting with provider v4.0.0, password fields use a write-only attribute so the password value is never written to the Terraform state file. For any field whose template marks it as a password field, use password_value instead of itemvalue, and pair it with password_wo_version as a rotation trigger.

                fields {
                fieldname = "Username"
                itemvalue = "myuser"
                }
                fields {
                fieldname           = "Password"
                password_value      = var.db_password
                password_wo_version = 1
            }

• password_value is write-only: it is sent to Secret Server on create/update but never stored in terraform.tfstate or emitted by terraform show -json.

• To rotate a password, change password_value and bump password_wo_version to any new integer in the same apply.

• Legacy configurations that set a password via itemvalue still work but produce a perpetual plan diff in v4.0.0, because the value is nulled in state on read. Migrate password fields to password_value + password_wo_version.

Server-Side Password Generation

If you do not want to supply a password value yourself, set generate = true on a password field. The provider asks Secret Server to generate a password matching the template's password-requirement policy and uses that value.

                fields {
                fieldname           = "Password"
                generate            = true
                password_wo_version = 1
            }

• generate is only honored on fields the template marks as password fields.

• generate is mutually exclusive with password_value and itemvalue; setting more than one on a password field is rejected.

• The generated password reaches Secret Server through the normal create/update flow and is never written to Terraform state.

• To rotate to a newly generated password, bump password_wo_version. Re-applying with the same password_wo_version is a no-op.

Server Assigned (Computed) Fields

In provider v4.0.0, the following fields attributes are assigned by Secret Server and are read-only. Do not set them in your configuration:

• itemid — Database ID of the field-value record.
• fieldid — The template field ID.
• slug — The field's URL slug.
• fielddescription — The field description from the template.

Setting any of these produces a plan-time error such as: Can't configure a value for "itemid": its value will be decided automatically based on the result of applying this configuration. Remove these attributes from your fields blocks.

fileattachmentid remains user-settable for file-type fields.

Using Environment Credential Variables

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

You can use environment variables to securely authenticate to Secret Server. You can choose between authentication with credentials and authentication with an OAuth token.

Credentials authentication

Environment Variable Authentication Methods

There are two independent ways to supply credentials via environment variables:

1. Direct Provider Fallback (provider v4.0.0+). The provider reads the following environment variables directly, in the order explicit provider attribute > environment variable > unset. With these exported, you can leave the provider block empty (provider "tss" {}):

   Environment Variable	Provider Attribute
   TSS_SERVER_URL	server_url
   TSS_USERNAME	username
   TSS_PASSWORD	password
   TSS_TOKEN	token
   TSS_DOMAIN	domain

   For Linux/macOS:

   export TSS_SERVER_URL="https://yourtenantName.secretservercloud.com"
   export TSS_USERNAME="my_app_user"
   export TSS_PASSWORD="Password."
   terraform plan

   After the fallback runs, the provider enforces that server_url is set and that exactly one of (username and password) or token is set.

2. Terraform Input Variables (TF_VAR_ prefix). Alternatively, expose credentials via variable "x" blocks referenced by the provider configuration; each is populated from the corresponding TF_VAR_x environment variable (for example, TF_VAR_tss_username). This is Terraform's general variable mechanism and is independent of the TSS_* fallback described above.

Set the environment variables as follows:

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://yourtenantName.secretservercloud.com"

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://yourtenantName.secretservercloud.com"

Token-based authentication

You can pass Terraform the Secret Server URL and the token to use via the tss_server_url and tss_token environment variables. You must add the prefix TF_VAR_ before the variable names so that Terraform will automatically fetch the values from these environment variables.

Set the environment variables as follows:

For Linux(secret_oracle_account.tfvars)

$ export TF_VAR_token="token"

$ export TF_VAR_tss_server_url="https://yourtenantName.secretservercloud.com"

For Windows (secret_windows_account.tfvars)

> set TF_VAR_tss_token="token"

> set TF_VAR_tss_server_url="https://yourtenantName.secretservercloud.com"

After setting the 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:

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:

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)

Upgrading to Provider v4.0.0

• From v3.x: v4.0.0 ships a state upgrader that runs automatically on the first terraform plan against existing v3.x state. No user action is required. If a password was previously supplied via itemvalue, the first plan after upgrade shows the value being nulled in state (your password in Secret Server is unchanged); migrate to password_value and password_wo_version to avoid a perpetual diff.

• From v2.x: v2.x and v4.0.0 are not directly compatible at the state level, and there is no automatic upgrade path. Options are to stay on v2.x, drop and recreate state, or perform manual state surgery. Back up your state before attempting any migration.