Terraform Provider for KSM

Keeper Secrets Manager Terraform provider for interacting with vault secrets in Terraform builds

Features

The Keeper Terraform Plugin utilizes Keeper Secrets Manager to provide access to secret credentials saved in the Keeper Vault. The Keeper Terraform plugin allows for injecting secrets directly into Terraform builds securely using Keeper's zero-knowledge infrastructure.

• Retrieve secrets from the Keeper Vault to use in Terraform builds

• Inject credentials directly into Terraform build scripts

• Create new secrets and store them in the vault

• Get Files from the Keeper Vault

For a complete list of Keeper Secrets Manager features see the Overview

Prerequisites

This page documents the Secrets Manager Terraform integration. In order to utilize this integration, you will need:

• Keeper Secrets Manager access (See the Quick Start Guide for more details)

  • Secrets Manager add-on enabled for your Keeper account

  • Membership in a Role with the Secrets Manager enforcement policy enabled

• A Keeper Secrets Manager Application with secrets shared to it

  • See the Quick Start Guide for instructions on creating an Application

• An initialized Keeper Secrets Manager Configuration

  • The Terraform integration accepts JSON and Base 64 format configurations

Installation

Registry install

The Keeper Secrets Manager provider page is located here

To install this provider, add the following code to your Terraform configuration and run terraform init:

terraform {
  required_providers {
    secretsmanager = {
      source = "keeper-security/secretsmanager"
      version = ">= 1.2.0"
    }
  }
}

provider "secretsmanager" {
  # Configuration options
}

Find the source code in the GitHub repository

Manual Installation

Download the latest version of the Terraform Provider for your platform from our GitHub release page and copy the archive to the corresponding Terraform plugin folder (creating any missing folders in the path). Initialize source with full provider URL: source = "github.com/keeper-security/secretsmanager"

Use the archive matching your OS and CPU architecture (amd64 or arm64). The Mac OS and Linux commands below detect architecture automatically. Windows command shown is for amd64.

Windows (amd64)

SETLOCAL EnableExtensions && ^
mkdir %APPDATA%\.terraform.d\plugins\github.com\keeper-security\secretsmanager && ^
cd %APPDATA%\.terraform.d\plugins\github.com\keeper-security\secretsmanager && ^
curl -SfLOJ https://github.com/keeper-security/terraform-provider-secretsmanager/releases/download/v1.2.0/terraform-provider-secretsmanager_1.2.0_windows_amd64.zip

Mac OS

Linux

For help on manually installing Terraform Providers, please refer to the official Terraform documentation.

Usage

Configure the Provider

The Keeper Secrets Manager provider is used to interact with the resources supported by Keeper Secrets Manager. The provider needs to be configured with Keeper credentials before it can be used.

terraform {
  required_providers {
    secretsmanager = {
      source  = "keeper-security/secretsmanager"
      version = ">= 1.2.0"
    }
  }
}

provider "secretsmanager" {
  # Specify config contents as a string or load from file
  # credential = "<CONFIG FILE CONTENTS BASE64>"
  credential = file("/path/to/config.json")
}

For CI/CD environments, you can omit the credential attribute entirely and set the KEEPER_CREDENTIAL environment variable instead:

export KEEPER_CREDENTIAL=$(cat ~/.keeper/credential)

Configuration File Contents

• appKey - (Required) Application key.

• clientId - (Required) Client ID.

• privateKey - (Required) Private key.

• hostname - (Optional) By default the plugin connects to keepersecurity.com

For more information on creating a Secrets Manager configuration, see the Configuration Documentation

Get Secrets Using Data Sources

A data source is provided for each standard Keeper record type, which facilitates easy fetching of secret credentials.

Data sources are accessed using the following format:

data "<data_source_name>" "<record_type_reference>" {
    path = "<record_uid>"
}

For example, using a Login type record:

data "secretsmanager_login" "my_login_record" {
    path = "<RECORD_UID>"
}

To access any additional custom fields or standard fields for user defined record types use secretsmanager_field data source

List of supported record types

Record Type	Data Source Name
Address	"secretsmanager_address"
Bank Account	"secretsmanager_bank_account"
Bank Card	"secretsmanager_bank_card"
Birth Certificate	"secretsmanager_birth_certificate"
Contact	"secretsmanager_contact"
Database Credentials	"secretsmanager_database_credentials"
Drivers License	"secretsmanager_driver_license"
Encrypted Notes	"secretsmanager_encrypted_notes"
Field	"secretsmanager_field"
File	"secretsmanager_file"
Folder	"secretsmanager_folder"
Folders	"secretsmanager_folders"
Health Insurance	"secretsmanager_health_insurance"
Login	"secretsmanager_login"
Membership	"secretsmanager_membership"
Passport	"secretsmanager_passport"
PAM Database	"secretsmanager_pam_database"
PAM Directory	"secretsmanager_pam_directory"
PAM Machine	"secretsmanager_pam_machine"
PAM User	"secretsmanager_pam_user"
Photo	"secretsmanager_photo"
Record	"secretsmanager_record"
Records (for large volume requests)	"secretsmanager_records"
Server Credentials	"secretsmanager_server_credentials"
Software License	"secretsmanager_software_license"
SSH Keys	"secretsmanager_ssh_keys"
SSN Card	"secretsmanager_ssn_card"

To see the fields available to each data source see Record Types Data Source Reference

For more information on record types see Record Types documentation and Commander usage.

Accessing Record Fields

To access a secret credential saved to a field in a record, access the field as part of the data source.

Access the field of a typed record data source

Use this format to access fields of a typed data resource

${ data.<data_source_name>.<record_type_reference>.<field> }

Example: access the password of a login type data source

${ data.secretsmanager_login.my_login_secret.password }

Use the field data source to query any field in a record with Keeper Notation

Create a data source using the "secretsmanager_field" data source type, and specify a field query in the path property.

data "secretsmanager_field" "my_field" {
  path = "<record UID>/field/login"
}

The field query uses the format: "<UID>/field/<field type>"

If you don't know the record UID, you can look up by title using a wildcard * in place of the UID and the optional title attribute:

data "secretsmanager_field" "db_password" {
  path  = "*/field/password"
  title = "Production Database"
}

Returns an error if more than one accessible record matches the title.

Creating Records With Resources

Keeper provides Terraform resources for the major Keeper record types shown above. Using these resources, Keeper records can be created using the Keeper Secrets Manager Terraform plugin.

To create a record, use the resource corresponding to the record type that you would like to use.

Each record resource requires at least a folder_uid and title as well as values for each record field.

Example login resource

resource "secretsmanager_login" "login" {
    folder_uid = "4PbDLf8UF4od87wJt-fdyQ"
    title = "My Login Record"
    # Additional fields...
}

Folder UID

To create records, Keeper Secrets Manager requires a folder UID so it knows where to create new records.

A folder UID can be found in the Keeper Vault or by using Keeper Commander.

The target folder (or its parent shared folder) must be accessible by the Keeper Secrets Manager Application with Can Edit permissions.

Title

The record title.

Record Fields

The value and settings for each record field can be set in the resource. For information on the available fields per record type, see the resource definitions.

Each field is represented as an object in the resource.

Example login field

resource "secretsmanager_login" "login" {
    folder_uid = "<FOLDER_UID>"
    title = "My Login Record"

    login {
        value = "MyUsername"
        label = "Username"
        required = true
    }
}

Setting Field Values

Use the value field to set the intended value for each field. The format of fields can differ, for example the login field type takes a string, while the name field takes an object with "first", "middle" and "last" fields.

For reference of each field's value format see the resource documentation.

Setting Field Settings

Each field can be configured with various settings:

Field	Accepted Value	Description
label	string	The field label
required	boolean	if True, the field will be considered required by the Keeper Vault
privacy_screen	boolean	if True, the field will be hidden in the Keeper Vault

Password Field

The password field has some special features.

Password Generation

Records created using the Terraform plugin can have a password generated automatically. To have the plugin generate a password, do not provide a value field to the password, and instead use generate = "true"

The password generation can be configured to generate a password of a specified length using the complexity field

password {
    generate = "true"
    complexity {
        length = 16
    }
}

Additionally, password fields have an extra configuration setting: enforce_generation which when true will make the Keeper Vault enforce that the password can only be generated and not set by a user.

To have Terraform regenerate a password, it needs to notice a difference in the generate field. To allow for triggering a difference, the generate field accepts both "true" and "yes" values. Change from one to the other to trigger a regeneration.

SSH Key Generation

The secretsmanager_ssh_keys resource can automatically generate an SSH key pair. To trigger generation, omit the key pair value and set generate = "true" on the key_pair field:

resource "secretsmanager_ssh_keys" "example" {
  folder_uid = "<FOLDER_UID>"
  title      = "My SSH Key"

  key_pair {
    generate = "true"
    key_type = "ssh-ed25519"    # default; also supports ssh-rsa, ecdsa-sha2-nistp256/384/521
    # key_bits = 4096           # only used for ssh-rsa; valid values: 2048, 3072, 4096
  }

  # Optional: generate and store a passphrase to encrypt the private key
  passphrase {
    generate = "true"
    complexity {
      length = 32
    }
  }
}

PAM Machine and PAM User resources also support generating a private PEM key via the private_pem_key field using the same generate / key_type / key_bits pattern.

Like passwords, SSH key generation uses "true" or "yes" as valid values. Changing between the two triggers Terraform to detect a diff and regenerate the key pair on the next apply.

resource "secretsmanager_pam_user" "pam_user_with_generated_key" {
  folder_uid = "<FOLDER_UID>"
  title      = "PAM User With Generated Key"

  login {
    value = "svc-deploy"
  }

  private_key_passphrase {
    generate = "yes"
    complexity {
      length = 32
    }
  }

  private_pem_key {
    generate = "yes"
    key_type = "ssh-rsa"
    key_bits = 4096
  }
}

Examples

Read Credentials

This example provisions Keeper Secrets Manager, reads a login type data source, and accesses each field of the data source.

terraform {
  required_providers {
    secretsmanager = {
      source  = "keeper-security/secretsmanager"
      version = ">= 1.2.0"
    }
    local = {
      source  = "hashicorp/local"
      version = "2.1.0"
    }
  }
}

provider "local" {}
provider "secretsmanager" {
  # Option 1: Use file containing base64-encoded credential
  credential = file("~/.keeper/credential")

  # Option 2: Use environment variable (recommended for CI/CD)
  # Leave credential empty to read from KEEPER_CREDENTIAL env var
}

data "secretsmanager_login" "db_server" {
  path = "<record UID>"
}

resource "local_file" "out" {
  filename        = "${path.module}/out.txt"
  file_permission = "0644"
  content         = <<EOT
UID:    ${data.secretsmanager_login.db_server.path}
Type:   ${data.secretsmanager_login.db_server.type}
Title:  ${data.secretsmanager_login.db_server.title}
Notes:  ${data.secretsmanager_login.db_server.notes}
======
Login:    ${data.secretsmanager_login.db_server.login}
Password: ${data.secretsmanager_login.db_server.password}
URL:      ${data.secretsmanager_login.db_server.url}
TOTP:
-----
%{for t in data.secretsmanager_login.db_server.totp~}
URL:    ${t.url}
Token:  ${t.token}
TTL:    ${t.ttl}
%{endfor~}
FileRefs:
---------
%{for fr in data.secretsmanager_login.db_server.file_ref~}
UID:      ${fr.uid}
Title:    ${fr.title}
Name:     ${fr.name}
Type:     ${fr.type}
Size:     ${fr.size}
Last Modified:  ${fr.last_modified}
Content/Base64: ${fr.content_base64}
%{endfor~}
EOT
}

output "db_secret_login" {
  value = data.secretsmanager_login.db_server.login
}

Create a Keeper Record

terraform {
  required_version = ">= 1.0.0"
  required_providers {
    secretsmanager = {
      source  = "keeper-security/secretsmanager"
      version = ">= 1.2.0"
    }
    local = {
      source  = "hashicorp/local"
      version = "2.1.0"
    }
  }
}

provider "local" {}
provider "secretsmanager" {
  # Option 1: Use file containing base64-encoded credential
  credential = file("~/.keeper/credential")

  # Option 2: Use environment variable (recommended for CI/CD)
  # Leave credential empty to read from KEEPER_CREDENTIAL env var
}

resource "secretsmanager_membership" "membership" {
  folder_uid = "<FOLDER UID>"
  title      = "test_membership_resource"
  notes      = "test_membership_resource"

  account_number {
    label          = "MyAccountNumber"
    required       = true
    privacy_screen = true
    value          = "AccountNumber#1234"
  }

  name {
    label          = "Jane"
    required       = true
    privacy_screen = true
    value {
      first  = "Jane"
      middle = "D"
      last   = "Doe"
    }
  }

  password {
    label              = "MyPass"
    required           = true
    privacy_screen     = true
    enforce_generation = true
    generate           = "true"
    complexity {
      length = 16
    }
    # value = "to_be_generated"  # Commented because generate=true
  }
}

resource "local_file" "out" {
  filename        = "${path.module}/out.txt"
  file_permission = "0644"
  content         = <<EOT
FUID:   ${secretsmanager_membership.membership.folder_uid}
UID:    ${secretsmanager_membership.membership.uid}
Type:   ${secretsmanager_membership.membership.type}
Title:  ${secretsmanager_membership.membership.title}
Notes:  ${secretsmanager_membership.membership.notes}
======

Account Number:
---------------
%{for n in secretsmanager_membership.membership.account_number~}
Type:           ${n.type}
Label:          ${n.label}
Required:       ${n.required}
Privacy Screen: ${n.privacy_screen}
Value:          ${n.value}
%{endfor}

Name:
-----
%{for n in secretsmanager_membership.membership.name~}
Type:           ${n.type}
Label:          ${n.label}
Required:       ${n.required}
Privacy Screen: ${n.privacy_screen}
First Name:     ${n.value.0.first}
Middle Name:    ${n.value.0.middle}
Last Name:      ${n.value.0.last}
%{endfor}

Password:
---------
%{for n in secretsmanager_membership.membership.password~}
Type:               ${n.type}
Label:              ${n.label}
Required:           ${n.required}
Privacy Screen:     ${n.privacy_screen}
Enforce Generation: ${n.enforce_generation}
Generate:           %{if n.generate != null}${n.generate}%{endif}
Complexity:         Length = ${n.complexity.0.length}
Value:              ${n.value}
%{endfor}
EOT
}

output "record_uid" {
  value = secretsmanager_membership.membership.uid
}

output "record_title" {
  value = secretsmanager_membership.membership.title
}

Create PAM Records

These snippets assume the terraform and provider "secretsmanager" blocks are already configured as shown above.

resource "secretsmanager_pam_database" "postgres_prod" {
  folder_uid = "<FOLDER_UID>"
  title      = "Production PostgreSQL"

  pam_hostname {
    value {
      hostname = "postgres.prod.example.com"
      port     = "5432"
    }
  }

  pam_settings = jsonencode([{
    connection = [{
      protocol = "postgresql"
      port     = "5432"
      database = "production"
    }]
  }])

  database_type = "postgresql"

  use_ssl {
    value = true
  }
}

resource "secretsmanager_pam_directory" "corp_ad" {
  folder_uid = "<FOLDER_UID>"
  title      = "Corporate AD"

  pam_hostname {
    value {
      hostname = "ad.corp.example.com"
      port     = "636"
    }
  }

  pam_settings = jsonencode([{
    connection = [{
      protocol = "ldaps"
      port     = "636"
    }]
  }])

  directory_type = "Active Directory"

  distinguished_name {
    value = "DC=corp,DC=example,DC=com"
  }

  use_ssl {
    value = true
  }
}

Read PAM Data Source Outputs

These snippets assume the terraform and provider "secretsmanager" blocks are already configured as shown above.

data "secretsmanager_pam_machine" "host" {
  path = "<PAM_MACHINE_UID>"
}

output "pam_machine_folder_uid" {
  value = data.secretsmanager_pam_machine.host.folder_uid
}

output "pam_machine_totp_uri" {
  value = try(data.secretsmanager_pam_machine.host.totp[0].value, null)
}

output "pam_machine_private_key_passphrase" {
  value     = try(data.secretsmanager_pam_machine.host.private_key_passphrase[0].value, null)
  sensitive = true
}

For more examples, check out the examples folder in the source code.

Optimization

The secretsmanager_records data source allows you to fetch multiple Keeper Secrets Manager records in a single API call, significantly reducing API requests and improving performance when dealing with many secrets.

Fetch by UIDs (most efficient):

data "secretsmanager_records" "infrastructure" {
  uids = ["uid1", "uid2", "uid3"]
}

Fetch by exact titles:

data "secretsmanager_records" "by_name" {
  titles = ["Production DB", "Staging DB", "API Keys"]
}

Fetch by regex pattern:

data "secretsmanager_records" "prod_secrets" {
  title_patterns = ["^prod-.*"]  # Records starting with "prod-"
}

titles and title_patterns both fetch all accessible vault records and filter client-side. Use uids whenever possible for better performance. Patterns use Go regex syntax and are limited to 500 characters to prevent ReDoS.

For detailed documentation including all available output attributes, see the secretsmanager_records reference.

Accessing results by UID:

Records are available as a list via records, or as a UID-indexed map via records_by_uid:

# Access by list position
output "first_title" {
  value = data.secretsmanager_records.infrastructure.records[0].title
}

# Access by UID (returns JSON-encoded record)
output "specific_record" {
  value = data.secretsmanager_records.infrastructure.records_by_uid["uid1"]
}