Terraform Plugin
Keeper Secrets Manager Terraform plugin for accessing secrets in Terraform builds
- Retrieve secrets from the Keeper Vault to use in Terraform builds
- Inject credentials directly into Terraform build scripts
- Get Files from the Keeper Vault
This page documents the Secrets Manager Terraform integration. In order to utilize this integration, you will need:
- Secrets Manager addon enabled for your Keeper account
- Membership in a Role with the Secrets Manager enforcement policy enabled
- The Terraform integration accepts JSON and Base 64 format configurations
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.
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
}
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
Mac OS
Linux
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
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
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.
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")
}
app_key- (Required) Application key.client_id- (Required) Client ID.private_key- (Required) Private key.hostname- (Optional) By default plugin will connect tokeepersecurity.com
For more information on creating a Secrets Manager configuration, see the Configuration Documentation
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 sourceRecord Type | Data Source Name |
|---|---|
"secretsmanager_address" | |
"secretsmanager_bank_account" | |
"secretsmanager_bank_card" | |
"secretsmanager_birth_certificate" | |
"secretsmanager_contact" | |
"secretsmanager_database_credentials" | |
"secretsmanager_drivers_license" | |
"secretsmanager_encrypted_notes" | |
"secretsmanager_field" | |
"secretsmanager_file" | |
"secretsmanager_health_insurance" | |
"secretsmanager_login" | |
"secretsmanager_membership" | |
"secretsmanager_passport" | |
"secretsmanager_photo" | |
"secretsmanager_server_credentials" | |
"secretsmanager_software_license" | |
"secretsmanager_ssh_keys" | |
"secretsmanager_ssn_card" |
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>"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"
[...]
}
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.
The record title.
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
}
}
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.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 |
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.
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
}
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
}
Last modified 1yr ago