You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A credential helper for Terraform Cloud/Enterprise that allows secure storage of your API token within the operating system's vault instead of in a plain text configuration file
6
+
A credential helper for Terraform Cloud/Enterprise, or to store other secrets, securely in the operating system's credential vault or through a third party vault. No longer keep secrets in a plain text configuration file!
7
7
8
8
We all know storing secrets in plain text can pose major security threats, and Terraform doesn't come pre-packaged with a credential helper, so we decided to create one and to share it with the greater Terraform/DevOps community to help enable stronger security practices
9
9
@@ -12,10 +12,16 @@ We all know storing secrets in plain text can pose major security threats, and T
12
12
-[x] MacOS (Keychain)
13
13
-[x] Linux (gnome-keyring) *Tested on Ubuntu 20.04*
14
14
15
+
#### Currently supported Vault providers:
16
+
-[x] AWS Secrets Manager
17
+
-[x] Azure Key Vault
18
+
-[ ] Google Secret Manager
19
+
-[x] HashiCorp Vault
20
+
15
21
## Windows Install via Chocolatey
16
22
The fastest way to install `terracreds` on Windows is via our Chocolatey package:
17
23
```powershell
18
-
choco install terracreds -y
24
+
choco install terracreds --version "2.0.0" -y
19
25
```
20
26
21
27
Once installed run the following command to verify `terracreds` was installed properly:
@@ -25,7 +31,7 @@ terracreds -v
25
31
26
32
To upgrade `terracreds` to the latest version with Chocolatey run the the following command:
27
33
```powershell
28
-
choco upgrade terracreds -y
34
+
choco upgrade terracreds --version "2.0.0" -y
29
35
```
30
36
31
37
## macOS Install
@@ -36,10 +42,10 @@ extract the package, and then place it in a directory available on `$HOME`
36
42
You'll need to download the latest binary from our release page and place it anywhere on `$PATH` of your system. You can also copy and run the following commands:
The `terracreds` Linux implementation uses `gnome-keyring` in conjunction with `gnome-keyring-daemon`
@@ -179,8 +185,84 @@ Success! Terraform has removed the stored API token for app.terraform.io.
179
185
180
186
Additionally, you can check the `terracreds.log` if logging is enabled for more information
181
187
188
+
## Setting Up a Vault Provider
189
+
> You can reference example configs in our [repo](https://github.com/tonedefdev/terracreds/blob/main/config.yaml) plus we have example [terraform](https://github.com/tonedefdev/terracreds/tree/main/terraform) code you can reference in order to setup your `AWS` or `Azure` VMs to use `terracreds` for a CI/CD piepline agent or a development workstation
190
+
191
+
### AWS Secrets Manager
192
+
> Currently, we only support using an `EC2 Instance Role` for authentication. This ensures the highest level of security by alleviating the `secret zero` dilemma
193
+
194
+
In order to leverage `terracreds` to manage secrets in `AWS Secrets Manager` the following block needs to be provided in the configuration file:
195
+
```yaml
196
+
aws:
197
+
description: my_terraform_api_token
198
+
region: us-west-2
199
+
secretName: my-secret-name
200
+
```
201
+
202
+
| Value | Description | Required |
203
+
| ----- | ----------- | -------- |
204
+
| `description` | A brief description to provide for the secret object viewable in `Secrets Manager` | `yes` |
205
+
| `region` | The `Secrets Manager` instance's region where the secret will be stored | `yes` |
206
+
| `secretName` | A name for the secret. If omitted and using `terraform login` the hostname of the TFC\TFE server will be used for the name instead | `no` |
207
+
208
+
The following role permissions are required in order for the `EC2 Instance Role` to levearge `terracreds` with `AWS Secrets Manager`:
209
+
```hcl
210
+
Action = [
211
+
"secretsmanager:CreateSecret",
212
+
"secretsmanager:DeleteSecret",
213
+
"secretsmanager:GetSecretValue",
214
+
"secretsmanager:PutSecretValue"
215
+
]
216
+
```
217
+
### Azure Key Vault
218
+
> Currently, we only support using a `Managed Service Identity` for authentication. This ensures the highest level of security by alleviating the `secret zero` dilemma
219
+
220
+
In order to leverage `terracreds` to manage secrets in `Azure Key Vault` the following block needs to be provided in the configuration file:
221
+
```yaml
222
+
azure:
223
+
secretName: my-secret-name
224
+
useMSI: true
225
+
vaultUri: https://keyvault.azure.net
226
+
```
227
+
228
+
| Value | Description | Required |
229
+
| ----- | ----------- | -------- |
230
+
| `secretName` | A name for the secret. If omitted and using `terraform login` the hostname of the TFC\TFE server will be used for the name instead | `no` |
231
+
| `useMSI` | A flag to choose whether or not to use `Manged Service Identity`. Currently, `true` is required | `yes` |
232
+
| `vaultUri` | The URI for the `Azure Key Vault` where you want to store or retrieve your credentials | `yes` |
233
+
234
+
The following `Azure Key Vault Access Policies` are required to be given to the `Managed Service Identity` for it to leverage `terracreds`:
235
+
```hcl
236
+
secret_permissions = [
237
+
"Get",
238
+
"List",
239
+
"Set",
240
+
"Delete"
241
+
]
242
+
```
243
+
> Since `Azure Key Vault` doesn't support the period character in a secret name a helper function will replace any periods with dashes so they can be successfully stored. This means a `terraform` API token name that would usually be `app.terraform.io` will become `app-terraform-io`
244
+
245
+
### HashiCorp Vault
246
+
In order to leverage `terracreds` to manage secrets in `HashiCorp Vault` the following block needs to be provided in the configuration file:
247
+
```yaml
248
+
hcvault:
249
+
environmentTokenName: HASHI_TOKEN
250
+
keyVaultPath: kv
251
+
secretName: my-secret-name
252
+
secretPath: tfe
253
+
vaultUri: http://localhost:8200
254
+
```
255
+
256
+
| Value | Description | Required |
257
+
| ----- | ----------- | -------- |
258
+
| `environmentTokenName` | The name of the environment variable that contains the token value to authenticate with `HashiCorp Vault` | `yes` |
259
+
| `keyVaultPath` | The path to the `Key Vault` object within the vault | `yes` |
260
+
| `secretName` | A name for the secret. If omitted and using `terraform login` the hostname of the TFC\TFE server will be used for the name instead | `no` |
261
+
| `secretPath` | The path of the secret within `HashiCorp Vault` | `yes` |
262
+
| `vaultUri` | The URI for the `HashiCorp Vault` instance | `yes` |
263
+
182
264
## Protection
183
-
In order to add some protection `terracreds` adds a username to the credential object, and checks to ensure that the user requesting access to the token is the same user as the token's creator. This means that only the user account used to create the token can view the token from `terracreds` which ensures that the token can only be read by the account used to create it. Any attempt to access or modify this token from `terracreds` outside of the user that created the credentail will lead to denial messages. Additionally, if the credential name is not found, the same access denied message will be provided in lieu of a generic not found message to help prevent brute force attempts
265
+
In order to add some protection `terracreds` adds a username to the credential object to secrets stored in the local operating system, and checks to ensure that the user requesting access to the token is the same user as the token's creator. This means that only the user account used to create the token can view the token from `terracreds` which ensures that the token can only be read by the account used to create it. Any attempt to access or modify this token from `terracreds` outside of the user that created the credentail will lead to denial messages. Additionally, if the credential name is not found, the same access denied message will be provided in lieu of a generic not found message to help prevent brute force attempts
184
266
185
267
## Logging
186
268
Wherever either binary is stored `terracreds` or `terraform-credential-terracreds` a `config.yaml` file is generated on first launch of the binary. Currently, this configuration file only enables/disables logging and sets the log path. If logging is enabled you'll find the log named `terracreds.log` at the provided path
0 commit comments