terraform-credentials-keychain

README

terraform-credentials-keychain

A Terraform credentials helper that stores your credentials in the system keychain

By default, terraform login writes your Terraform Cloud credentials (i.e. API token) as a plain text file in your home directory. Any program you run can read this file, potentially stealing your credentials.

With this credential helper installed, your credentials will instead be stored in the system keychain. This helper uses 99designs/keyring and can use any credential storage backend it supports. Currently, only macOS is actively tested.

Installing

Download an appropriate release binary for your operating system/architecture. Install it into the appropriate Terraform plugin directory. Credentials helpers are stored in the same directory as provider plugins.

For example, on macOS, you should install the binary as:

~/.terraform.d/plugins/darwin_amd64/terraform-credentials-keychain

Releases for macOS are signed and notarized so that the system will trust the application.

Usage

Run terraform logout for each Terraform host you connect to. For Terraform Cloud, you can run terraform logout directly. For Terraform Enterprise, supply the hostname of the Terraform Enterprise server. This will remove all plain text credentials stored in credentials.tfrc.json or print an error if credential blocks are defined in .terraformrc. These credentials will bypass the credential helper if they are not removed. You should also revoke these API tokens from your Terraform Cloud user settings.

Add the credential helper to ~/.terraformrc file:

credentials_helper "keychain" {}

Now when you use terraform login and terraform logout, they will use your system keychain rather than persisting credentials directly to disk!

Each time you run a terraform command that uses your credentials (e.g. init, plan, apply, etc.), the credential helper will read your credentials from the keychain, prompting for a password if needed.

Security

Any command that requires Terraform Cloud credentials, including most terraform commands, will prompt for the keychain password:

For maximum security, click Allow and enter your password every time it is required by Terraform or another program. If you run Terraform frequently, this may become tedious. If you click Always Allow, you will never be prompted for a password again. Your credentials will still be protected from a malicious program scanning your disk, but a program that calls terraform-credentials-keychain get <host> will still be able to obtain them.

If you choose this option, consider configuring your keychain to lock after a period of inactivity. When your keychain is locked, you will be prompted for the keychain password before an application can access its contents, even if that application is trusted by the item. You can also use a dedicated keychain, instead of the default login keychain:

credentials_helper "keychain" {
  args = ["--keychain=terraform"]
}

After adding your credentials, you can open Keychain Access to edit the keychain's auto-lock settings:

open ~/Library/Keychains/terraform.keychain-db