Terraform Plugin

Keeper Secrets Manager Terraform plugin for accessing secrets in Terraform builds

Features

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

• Inject credentials directly into Terraform build scripts

• 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 addon 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

About

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.

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.0.0"
    }
  }
}

provider "secretsmanager" {
  # Configuration options
}

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"

Windows

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.0.0/terraform-provider-secretsmanager_1.0.0_windows_amd64.zip

Mac OS

mkdir -p ~/.terraform.d/plugins/github.com/keeper-security/secretsmanager && \
cd ~/.terraform.d/plugins/github.com/keeper-security/secretsmanager && \
curl -SfLOJ https://github.com/keeper-security/terraform-provider-secretsmanager/releases/download/v1.0.0/terraform-provider-secretsmanager_1.0.0_darwin_amd64.zip

Linux

mkdir -p ~/.terraform.d/plugins/github.com/keeper-security/secretsmanager && \
cd ~/.terraform.d/plugins/github.com/keeper-security/secretsmanager && \
curl -SfLOJ https://github.com/keeper-security/terraform-provider-secretsmanager/releases/download/v1.0.0/terraform-provider-secretsmanager_1.0.0_linux_amd64.zip

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.0.0"
    }
 }
}

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

Configuration File Contents

• app_key - (Required) Application key.

• client_id - (Required) Client ID.

• private_key - (Required) Private key.

• hostname - (Optional) By default plugin will connect 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_drivers_license"
Encrypted Notes	"secretsmanager_encrypted_notes"
Field	"secretsmanager_field"
File	"secretsmanager_file"
Health Insurance	"secretsmanager_health_insurance"
Login	"secretsmanager_login"
Membership	"secretsmanager_membership"
Passport	"secretsmanager_passport"
Photo	"secretsmanager_photo"
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

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>"

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"
    tile: "My Login Record"
    [...]
}

Folder UID

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

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

The given folder must by accessible by the Keeper Secrets Manager Application being used by your Terraform plugin. The folder must also have at least one record in it before being used by Keeper Secrets Manager.

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" {
    [...]
    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

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.

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.0.0"
    }
    local = {
      source = "hashicorp/local"
      version = "2.1.0"
    }
  }
}

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

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.1.0"
    }
    local = {
      source = "hashicorp/local"
      version = "2.1.0"
    }
  }
}

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

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"
	}
}

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
}

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