Terraform

Terraform is an Infrastructure as Code (IaC) tool, used primarily to automate various infrastructure tasks. The Password Safe Terraform Provider enables the use of Password Safe's credential management solution with Terraform, providing a streamlined way for users to secure their Terraform associated secrets.

ℹ️

Note

The Password Safe Terraform Provider is available in the Terraform Registry.

Overview

The Password Safe Terraform provider is named terraform-provider-passwordsafe. It has been built for the following Operating systems: Windows, Linux and MacOS. Built to support amd64 architecture.

The provider enables using Password Safe secrets management capabilities with Terraform. The provider is invoked by using HashiCorp Configuration Language (HCL) which tells the provider to reach out (using APIs) to the Password Safe service and utilize its secrets management capabilities.

1. The end user writes a Terraform configuration that sets Password Safe variables for the Password Safe provider and retrieves the API secret for authentication to a third-party provider. All configuration is run on Terraform plan/apply.
2. Terraform plan/apply invokes the Password Safe provider to retrieve the secret.
3. Terraform plan/apply also invokes the third-party provider, using the Password Safe secret for authentication to the third-party service.

ℹ️

Note

This integration requires Password Safeversion 23.1 or higher for Secrets Safe secrets.

This integration uses Transport Layer Security (TLS) 1.2 protocol.

ℹ️

Note

For more information, see The Core Terraform Workflow.

Configure Password Safe to allow Terraform files to retrieve secrets

The following sections outline how to set up the required authorization in Password Safe to allow Terraform HCL files to retrieve secrets.

ℹ️

Note

The following instructions are meant to be a quick start guide to help with Password Safe setup.

Password Safe Authentication Methods

The provider must be configured with one of next authentication methods:

1. API key and a user account to access target secrets in Password Safe.
2. Client_id/client_secret using OAuth method to access target secrets in Password Safe.

ℹ️

Note

For Authentication: Use api_key or client_id/client_secret, when api_key is empty so client_id and client_secret will be used to authenticate using API OAuth method.

This is accomplished by the following steps:

Set up API key and user account

1. Create an API registration with API key or OAuth method in BeyondInsight.
2. Create or use an existing Secrets Safe group.
3. Create or use an existing BeyondInsight user.
4. Add the API registration to the group.
5. Add the user to the group.
6. Add the Secrets Safe feature to the group.

Managed accounts setup

1. Create or use an existing access policy that has the View Password Auto Approve option set.
2. Add the All Managed Accounts Smart Group to the BeyondInsight group.
3. Add the access policy to the All Managed Accounts Smart Group role, and ensure that both requestor and approver are set.
4. Create or use an existing managed system.
5. Create or use an existing managed account associated with the managed system.
6. Configure the managed account with the API Enabled and Max Concurrent Requests Unlimited options selected.

Configure Terraform

The provider must be configured with an API key and a user account to access target secrets in Password Safe.

⚠️

Important

Terraform state files and plan files contain sensitive information. Ensure best practices are followed for securing files.

Plugin directory setup

The provider will need to be placed in the terraform plugin directory. The plugin directory can be customized by the end user.

The default unpacked layout, implied local mirror directory is:

• Windows: %APPDATA%/terraform.d/plugins/providers/beyondtrust/passwordsafe/1.x.x/windows_amd64
• Mac OS X: $HOME/.terraform.d/plugins/providers/beyondtrust/passwordsafe/1.x.x/darwin_amd64
• Linux systems: $HOME/.terraform.d/plugins/providers/beyondtrust/passwordsafe/1.x.x/linux_amd64

❗️

Warning

Remember to set the executable bit on the provider chmod +x

📘

Note

For more information, see CLI Configuration | Terraform | HashiCorp Developer.

Configure provider

Configure the provider in your HCL files.

✅

Example

Provider Configuration Example:

terraform {
  required_providers {
    passwordsafe = {
      source = "providers/beyondtrust/passwordsafe"
      version = "1.0.0"
    }
  }
}
# configure the Password Safe provider
provider "passwordsafe" {
  # Note about Authentication: (Use api_key or client_id/client_secret, 
  # when api_key is empty so client_id and client_secret will be used 
  # to authenticate using API OAuth method).
  api_key = "${var.api_key}"
  client_id = "${var.client_id}"
  client_secret = "${var.client_secret}"
  url = "${var.url}"
  api_version = "${var.api_version}"
  api_account_name = "${var.api_account_name}"
  verify_ca = true
  client_certificates_folder_path = "${var.client_certificates_folder_path}"
  client_certificate_name = "${var.client_certificate_name}"
  client_certificate_password = "${var.client_certificate_password}"
}

Provider Arguments

• url - The URL for the Password Safe instance from which to request a secret.
• api_version - The recommended version is 3.1. If no version is specified, the default API version 3.0 will be use.
• api_account_name - The user name for the api request to the Password Safe instance. For use when authenticating with an api key.
• api_key - The api key for making requests to the Password Safe instance. For use when authenticating to Password Safe.
• client_id - API OAuth Client ID.
• client_secret - API OAuth Client Secret.
• client_certificates_folder_path – (optional) The path to the Client Certificate associated with the Password Safe instance for use when authenticating with an API key using a Client Certificate.
• client_certificate_password – (optional) The password associated with the Client Certificate. For use when authenticating with an API key using a Client Certificate.
• client_certificate_name – (optional) The name of the Client Certificate for use when authenticating with an API key using a Client Certificate.
• verify_ca – (optional) Indicates whether to verify the certificate authority on the Password Safe instance. For use when authenticating to Password Safe.

Configure secrets retrieval

Configure data sources to retrieve secrets from Password Safe. The first data block in the example below is passwordsafe_managed_account, used to retrieve managed account secrets. The second type of data source is passwordsafe_secret, which is used to retrieve credentials, text, and file secrets.

✅

Example

# retrieve a managed account secret
data "passwordsafe_managed_account" "manage_account" {
  system_name = "ServerStandard"
  account_name = "serveruser1"
}
output "manage_account" {
  value = "${data.passwordsafe_managed_account.manage_account.value}"
}
# retrieve a secrets safe credential
data "passwordsafe_secret" "secret_credential" {
  path = "folder1*folder2*folder3/folder4"
  title = "credLevel6"
  # separator is optional, and its default value is '/'.
  separator = "*"
}
output "secret_credential" {
  value = "${data.passwordsafe_secret.secret_credential.value}"
}
# retrieve a secrets safe file
data "passwordsafe_secret" "secret_file" {
  path = "folder1"
  title = "RootFile"
}
 output "secret_file" {
  value = "${data.passwordsafe_secret.secret_file.value}"
}

Create Secrets, folder and safes

You can create three types of secrets: credential, text, and file. You need to define the parent folder name. If the parent folder does not exist, you must create it before creating the secret.

Create Credential Secret

✅

Example

# create credential secret
resource "passwordsafe_credential_secret" "my_credenial_secret" {
  folder_name = "folder1"
  title = "Credential_Secret_from_Terraform"
  username = "my_user_name"
  password = "password_content"
  owner_type = "User"
  # optional attributes from here on
  description = "my credential secret description"
  owner_id = 1
  notes = "My Notes"
  password_rule_id = 1
  # the API user will be added as the owner by default
  owners {
    owner_id = 1
    owner = "owner"
    email = "[email protected]"
  }
  urls {
    id = 1
    credential_id = 1
    url = "https://www.beyondtrust.com/"
  }
}

Parameters Description

• The folder name indicates where the secret is created.
• Max string length for description and password is 256.
• Max string length for notes is 4000.
• Max string length for URL is 2048.
• Required: Title, username, password.
• A password or a PasswordRuleID is required.
  • If a PasswordRuleID is passed in, then a password is generated (based on the Password Policy defined by the PasswordPolicyID).
  • If a password is passed in instead, the same behavior is followed (using that as the password).

Create Text Secret

✅

Example

# create text secret
resource "passwordsafe_text_secret" "my_text_secret" {
  folder_name = "folder1"
  title = "Text_Secret_from_Terraform"
  text = "password_text"
  owner_type = "User"
  # optional attributes from here on
  description = "my text secret description"
  owner_id = 1
  notes = "My notes"
  # the API user will be added as the owner by default
  owners {
    owner_id = 1
    owner = "owner"
    email = "[email protected]"
  }
  urls {
    id = 1
    credential_id = 1
    url = "https://www.beyondtrust.com/"
  }
}

Parameters Description

• The folder name indicates where the secret will be created.
• Max string length for Title and Description is 256.
• Max string length for text is 4096.
• Max string length for notes is 4000.
• Max string length for URL is 2048.
• Required: Title, FolderId.

Create File Secret

✅

Example

# create file secret
resource "passwordsafe_file_secret" "my_file_secret" {
  folder_name = "folder1"
  title = "File_Secret_from_Terraform"
  file_content = file("test_secret.txt")
  file_name = "my_secret.txt"
  owner_type = "User"
  # optional attributes from here on
  description = "my file secret description"
  owner_id = 1
  notes= "My notes"
  # the API user will be added as the owner by default
  owners {
    owner_id = 1
    owner = "owner"
    email = "[email protected]"
  }
  urls {
    id = 1
    credential_id = 1
    url = "https://www.beyondtrust.com/"
  }

Parameters Description

• The folder name indicates where the secret will be created.
• Max string length for Title, Description, and FileName is 256.
• Max string length for notes is 4000.
• Max string length for URL is 2048.
• Max file size is 5 MB. Size must be greater than 0 MB.
• Required: Title, FolderId, Filename.

Create Folder

✅

Example

# create folder
resource "passwordsafe_folder" "my_folder" {
  parent_folder_name = "folder1"
  name = "my_new_folder_mame"
  # optional attributes from here on
  description = "New Folder Description"
  user_group_id = 1
}

Parameters Description

• parent_folder_name: (required) Parent folder where new folder will be created.
• name: (required) New folder name.
• description: A description of the folder.
• user_group_id: User group id.

Create Safe

✅

Example

# create safe
resource "passwordsafe_safe" "my_safe" {
  name = "my_new_safe_mame"
  description="my_safe_description" #optional
}

Parameters Description

• name: (required) New safe name.
• description: A description of the safe.

Create Managed Account

✅

Example

# create managed account
resource "passwordsafe_managed_account" "my_managed_account" {
  system_name = "system_integration_test"
  account_name = "managed_account_Test"
  password = "MyTest101*!"
  # optional attributes from here on
  domain_name                       = "example.com"
  user_principal_name               = "[email protected]"
  sam_account_name                  = "USER123"
  distinguished_name                = "CN=User123,OU=Users,DC=example,DC=com"
  private_key                       = "/path/to/private/key.pem"
  passphrase                        = "mysecretpassphrase"
  password_fallback_flag            = true
  login_account_flag                = false
  description                       = "This is a test user account"
  password_rule_id                  = 1
  api_enabled                       = true
  release_notification_email        = "[email protected]"
  change_services_flag              = true
  restart_services_flag             = false
  change_tasks_flag                 = true
  release_duration                  = 30
  max_release_duration              = 90
  isa_release_duration              = 60
  max_concurrent_requests           = 10
  auto_management_flag              = true
  dss_auto_management_flag          = false
  check_password_flag               = true
  change_password_after_any_release_flag = false
  reset_password_on_mismatch_flag   = true
  change_frequency_type             = "first"
  change_frequency_days             = 30
  change_time                       = "03:00"
  next_change_date                  = "2025-01-01"
  use_own_credentials               = false
  workgroup_id                      = 2
  change_windows_auto_logon_flag    = true
  change_com_plus_flag              = false
  change_dcom_flag                  = true
  change_scom_flag                  = false
  object_id                         = "12345-abcde-67890"
}

Parameters Description

• system_name (required): The name of the system, Max string length is 245.
• account_name (required): The name of the account. Must be unique on the system. Max string length is 245.
• password (required if auto_management_flag is false): The account password.
• domain_name (optional): This can be given but it must be exactly the same as the directory. If empty or null, it is automatically populated from the parent managed system/directory. Max string length is 50.
• user_principal_name (required for Active Directory and Entra ID managed systems only): The Active Directory user principal name. Max string length is 500.
• sam_account_name (required for Active Directory managed systems, optional for Entra ID managed systems): The Active Directory SAM account name (Maximum 20 characters). Max string length is 20.
• distinguished_name (required for LDAP Directory managed systems only): The LDAP distinguished name. Max string length is 1000.
• private_key: DSS private key. Can be set if platform.dss_flag is true.
• passphrase (required when private_key is an encrypted DSS key): DSS passphrase. Can be set if platform.dss_flag is true.
• password_fallback_flag (default: false): True if failed DSS authentication can fall back to password authentication, otherwise false. Can be set if platform.dss_flag is true.
• login_account_flag: True if the account should use the managed system login account for SSH sessions, otherwise false. Can be set when the managed_system.login_account_id is set.
• description: A description of the account. Max string length is 1024.
• password_rule_id (default: 0): ID of the password rule assigned to this managed account.
• api_enabled (default: false): True if the account can be requested through the API, otherwise false.
• release_notification_email: Email address used for notification emails related to this managed account. Max string length is 255.
• change_services_flag (default: false): True if services run as this user should be updated with the new password after a password change, otherwise false.
• restart_services_flag (default: false): True if services should be restarted after the run as password is changed (change_services_flag), otherwise false.
• change_tasks_flag (default: false): True if scheduled tasks run as this user should be updated with the new password after a password change, otherwise false.
• release_duration (minutes: 1-525600, default: 120): Default release duration.
• max_release_duration (minutes: 1-525600, default: 525600): Default maximum release duration.
• isa_release_duration (minutes: 1-525600, default: 120): Default Information Systems Administrator (ISA) release duration.
• max_concurrent_requests (0-999, 0 is unlimited, default: 1): Maximum number of concurrent password requests for this account.
• auto_management_flag (default: false): True if password auto-management is enabled, otherwise false.
• dss_auto_management_flag (default: false): True if DSS key auto-management is enabled, otherwise false. If set to true, and no private_key is provided, immediately attempts to generate and set a new public key on the server. Can be set if platform.dss_auto_management_flag is true.
• check_password_flag (default: false): True to enable password testing, otherwise false.
• change_password_after_any_release_flag (default: false): True to change passwords on release of a request, otherwise false.
• reset_password_on_mismatch_flag (default: false): True to queue a password change when scheduled password test fails, otherwise false.
• change_frequency_type (default: first): The change frequency for scheduled password changes:
  • first: Changes scheduled for the first day of the month.
  • last: Changes scheduled for the last day of the month.
  • xdays: Changes scheduled every x days (change_frequency_days).
• change_frequency_days (days: 1-999): When change_frequency_type is xdays, password changes take place this configured number of days.
• change_time (24hr format: 00:00-23:59, default: 23:30): UTC time of day scheduled password changes take place.
• next_change_date (date format: YYYY-MM-DD): UTC date when next scheduled password change occurs. If the next_change_date + change_time is in the past, password change occurs at the nearest future change_time.
• use_own_credentials (version 3.1+): True if the current account credentials should be used during change operations, otherwise false.
• change_iis_app_pool_flag (version 3.2 only): True if IIS application pools run as this user should be updated with the new password after a password change, otherwise false.
• restart_iis_app_pool_flag (version 3.2 only): True if IIS application pools should be restarted after the run as password is changed (change_iis_app_pool_flag), otherwise false.
• workgroup_id: ID of the assigned Workgroup.
• change_windows_auto_logon_flag (default: false): True if Windows Auto Logon should be updated with the new password after a password change, otherwise false.
• change_com_plus_flag (default: false): True if COM+ Apps should be updated with the new password after a password change, otherwise false.
• change_dcom_flag (default: false): True if DCOM Apps should be updated with the new password after a password change, otherwise false.
• change_scom_flag (default: false): True if SCOM Identities should be updated with the new password after a password change, otherwise false.
• object_id (required when platform.requires_object_id is true): ObjectID of the account (if applicable). Max string length is 36.