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

    Use Case Example File
    Retrieve a single secret examples/secrets/secret_get/main.tf
    Retrieve multiple secrets examples/secrets/secrets_get/main.tf
    Create or update a secret examples/secrets/secret_create/main.tf
    Retrieve ephemeral secret examples/secrets/ephemeral_secret_get/main.tf
    Retrieve multiple ephemeral secrets examples/secrets/ephemeral_secrets_get/main.tf
    Delete Secret by id examples/secrets/secret_delete/main.tf
    Delete multiple secrets by their id examples/secrets/secrets_delete/main.tf

    As of provider v5.0.0 each example is a standalone Terraform root module in its own directory, so it can be initialized and validated on its own. Copy the directory's main.tf into your working directory, or run the example in place:

    Copy 
    cd examples/secrets/secret_get
                            terraform init
                        terraform apply -var-file=../../../vars/secrets/secret_get.tfvars

  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 = "5.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.

    The Terraform Registry source stays DelineaXPM/tss. Only the pinned version changes. Before moving an existing configuration from 4.0.0 to 5.0.0, review Upgrading to Provider v5.0.0, because several v4 configurations are rejected at plan or apply time on v5.

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 a Windows account secret secret_windows_account.tfvars
Create an Oracle (Linux) account secret secret_oracle_account.tfvars
Create an SSH key secret secret_ssh.tfvars
Delete a secret by secret ID secret_delete.tfvars
Delete multiple secrets by their ID secrets_delete.tfvars

Static Credential Variables

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

Variable Description Note
tss_username Application account username.

If using token authentication, do not include this variable.

Use the example below to set up.
tss_password Application account password.

If using token authentication, do not include this variable.

Use the example below to set up.
tss_server_url Secret Server URL. Use the example below to set up.
tss_token An OAuth token to authenticate with Secret Server.

If using credentials authentication, do not include this variable.

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. fieldname is required on every fields block in provider v5.0.0 and must match exactly one field name or slug on the selected secret template.
  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.

Remove blocks that reference fields the template no longer defines, and do not list the same template field twice (including once by display name and once by slug). v5.0.0 rejects both cases before anything is written.
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. Set True to generate SSH keys when creating secret. Default value is False.

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

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

Token authentication

Copy 
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

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

Token authentication

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

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

  • Starting with provider v5.0.0, itemvalue is rejected on any field the secret template marks as a password field. The provider fails before writing anything, with an error that names the migration; an explicitly empty itemvalue on a password field is rejected as well. Move those fields to password_value together with password_wo_version (or set generate = true).

  • password_wo_version is required whenever password_value is configured, and password_value must be non-empty. Terraform cannot compare a write-only value, so without the version attribute a later change to password_value would be invisible to terraform plan. password_value is also rejected on a template field that is not a password field.

  • Rotation is gated strictly on password_wo_version: in v5.0.0 an unrelated change (for example a rename) no longer re-sends password_value and no longer regenerates a generate = true password. Bump password_wo_version when, and only when, you want the password to change.

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.

Copy 
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 v5.0.0, the following fields attributes are assigned by Secret Server or by the secret template and are read-only. Do not set them in your configuration:

  • itemid — Database ID of the field-value record.
  • fieldid — The template field ID.
  • fileattachmentid — The server-assigned attachment ID for a file-type field.
  • slug — The field's URL slug.
  • fielddescription — The field description from the template.
  • isfile, isnotes, ispassword, islist, and listtype — Field kinds and list metadata assigned by 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 became computed-only in v5.0.0: the provider never sent it when writing a secret, so accepting it silently ignored the requested attachment. Provide new file content through itemvalue and filename and let Secret Server return the attachment ID.

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
    TSS_ALLOW_INSECURE_HTTP allow_insecure_http

    For Linux/macOS:

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

    In provider v5.0.0 and later, a provider attribute whose value is not known at configure time (for example server_url = module.ss.url before that module has been applied) is an error instead of silently falling back to the environment variable, which could have pointed the plan at a different server or identity. Set the attribute to a static value, use the TSS_* environment variable exclusively and leave the attribute unset, or apply the value's source first with -target.

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

Server URL Requirements and Backend Probe (v5.0.0)

HTTPS is required for remote hosts. server_url must use https:// for any host that is not a loopback address. A plaintext http:// URL to a remote host is rejected when the provider is configured, so terraform plan and terraform apply fail immediately with an error naming the opt-in, because plaintext HTTP would expose the credential on the wire. http:// remains usable for loopback addresses such as localhost, 127.0.0.1, and ::1.

If Secret Server is behind upstream TLS termination and you accept the risk of plaintext HTTP between Terraform and that endpoint, opt in explicitly:

Copy 
provider "tss" {
                server_url          = "http://secretserver.internal/SecretServer"
                allow_insecure_http = true
            }

or export TSS_ALLOW_INSECURE_HTTP=true. The default is false.

Backend probe before credentials are sent. With username/password authentication, v5.0.0 first sends an unauthenticated GET to <server_url>/api/v1/healthcheck and then to <server_url>/health so it can tell Secret Server and Delinea Platform apart. The endpoint must return a direct 2xx response; redirects are deliberately not followed. If Secret Server sits behind a reverse proxy that routes only the legacy /healthcheck.aspx path, or that redirects these paths, permit the health path through the proxy before upgrading. Static Secret Server token authentication skips the probe.

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:

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.

Reading Multiple Secrets

In provider v5.0.0, the tss_secrets data source and the tss_secrets ephemeral resource fail the whole read if any requested ID is missing or inaccessible, and a missing or misspelled field is an error. Earlier versions warned and returned the remaining secrets, which shortened and re-indexed the result list and could feed the wrong value to a downstream resource.

If a read fails, remove IDs that no longer exist from the ids list, or split the read so that a deletable ID is not fatal to the whole batch. Results are returned in the same order as the requested IDs.

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.
  3. Changing sshkeyargs replaces the secret (v5.0.0): Because Secret Server generates SSH keys and passphrases only at creation, sshkeyargs is now replacement-only. Editing generatepassphrase or generatesshkeys produces a destroy-and-create plan instead of the in-place no-op earlier versions produced. generatepassphrase and generatesshkeys each default to false when omitted.

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.
  • v5.0.0: tss_secret_deletion is a one-shot operation. If the deleted secret is later restored, refresh reports a warning and keeps the completed operation in state; Terraform does not delete the restored secret again. Remove the resource from state and apply again only when another deletion is intended.
  • v5.0.0: Changing secret_id on an existing tss_secret_deletion resource replaces the resource so the newly selected secret is actually deleted.

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 v5.0.0

Terraform state from provider v4.0.x is compatible with v5.0.0, but configurations must be reviewed before upgrading. Use Terraform 1.11 or later, allow the direct Secret Server health endpoint through any reverse proxy, migrate password fields from itemvalue to password_value plus password_wo_version, remove configured computed field metadata, and add an unambiguous fieldname to every fields block. Changing sshkeyargs now replaces the secret. Managed-secret and multi-secret reads now fail closed instead of silently replacing or shortening results. Pin version = "~> 4.0" until these changes are complete.

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.