| --- |
| page_title: Credentials Helpers |
| description: >- |
| Credentials helpers are external programs that know how to store and retrieve |
| API tokens for remote Terraform services. |
| --- |
| |
| # Credentials Helpers |
| |
| For Terraform-specific features that interact with remote network services, |
| such as [module registries](/registry) and |
| [remote operations](/cloud-docs/run/cli), Terraform by default looks for |
| API credentials to use in these calls in |
| [the CLI configuration](/cli/config/config-file). |
| |
| Credentials helpers offer an alternative approach that allows you to customize |
| how Terraform obtains credentials using an external program, which can then |
| directly access an existing secrets management system in your organization. |
| |
| This page is about how to write and install a credentials helper. To learn |
| how to configure a credentials helper that was already installed, see |
| [the CLI config Credentials Helpers section](/cli/config/config-file#credentials-helpers). |
| |
| ## How Terraform finds Credentials Helpers |
| |
| A credentials helper is a normal executable program that is installed in a |
| particular location and whose name follows a specific naming convention. |
| |
| A credentials helper called "credstore", for example, would be implemented as |
| an executable program named `terraform-credentials-credstore` (with an `.exe` |
| extension on Windows only), and installed in one of the |
| [default plugin search locations](/plugin/how-terraform-works#plugin-locations). |
| |
| ## How Terraform runs Credentials Helpers |
| |
| Once Terraform has located the configured credentials helper, it will execute |
| it once for each credentials request that cannot be satisfied by a `credentials` |
| block in the CLI configuration. |
| |
| For the following examples, we'll assume a "credstore" credentials helper |
| configured as follows: |
| |
| ``` |
| credentials_helper "credstore" { |
| args = ["--host=credstore.example.com"] |
| } |
| ``` |
| |
| Terraform runs the helper program with each of the arguments given in `args`, |
| followed by an _verb_ and then the hostname that the verb will apply to. |
| The current set of verbs are: |
| |
| * `get`: retrieve the credentials for the given hostname |
| * `store`: store new credentials for the given hostname |
| * `forget`: delete any stored credentials for the given hostname |
| |
| To represent credentials, the credentials helper protocol uses a JSON object |
| whose contents correspond with the contents of |
| [`credentials` blocks in the CLI configuration](/cli/config/config-file#credentials). |
| To represent an API token, the object contains a property called "token" whose |
| value is the token string: |
| |
| ```json |
| { |
| "token": "example-token-value" |
| } |
| ``` |
| |
| The following sections describe the specific expected behaviors for each of the |
| three verbs. |
| |
| ## `get`: retrieve the credentials for the given hostname |
| |
| To retrieve credentials for `app.terraform.io`, Terraform would run the |
| "credstore" helper as follows: |
| |
| ``` |
| terraform-credentials-credstore --host=credstore.example.com get app.terraform.io |
| ``` |
| |
| If the credentials helper is able to provide credentials for the given host |
| then it must print a JSON credentials object to its stdout stream and then |
| exit with status code zero to indicate success. |
| |
| If the credentials helper definitively has no credentials for the given host, |
| then it must print an empty JSON object to stdout and exit with status zero. |
| |
| If the credentials helper is unable to provide the requested credentials for |
| any other reason, it must print an end-user-oriented plain text error message |
| to its stderr stream and then exit with a _non-zero_ status code. |
| |
| ## `store`: store new credentials for the given hostname |
| |
| To store new credentials for `app.terraform.io`, Terraform would run the |
| "credstore" helper as follows: |
| |
| ``` |
| terraform-credentials-credstore --host=credstore.example.com store app.terraform.io |
| ``` |
| |
| Terraform then writes a JSON credentials object to the helper program's stdin |
| stream. If the helper is able to store the given credentials then it must do |
| so and then exit with status code zero and no output on stdout or stderr to |
| indicate success. |
| |
| If it is unable to store the given credentials for any reason, it _must_ still |
| fully read its stdin until EOF and then print an end-user-oriented plain text |
| error message to its stderr stream before exiting with a non-zero status |
| code. |
| |
| The new credentials must fully replace any existing credentials stored for the |
| given hostname. |
| |
| ## `forget`: delete any stored credentials for the given hostname |
| |
| To forget any existing credentials for `app.terraform.io`, Terraform would run |
| the "credstore" helper as follows: |
| |
| ``` |
| terraform-credentials-credstore --host=credstore.example.com forget app.terraform.io |
| ``` |
| |
| No JSON credentials objects are used for the `forget` verb. |
| |
| If the helper program is able to delete its stored credentials for the given |
| hostname or if there are no such credentials stored already then it must |
| exist with status code zero and produce no output on stdout or stderr. |
| |
| If it is unable to forget the stored credentials for any reason, particularly |
| if the helper cannot be sure that the credentials are no longer available for |
| retrieval, the helper program must print an end-user-oriented plain text error |
| message to its stderr stream and then exit with a non-zero status code. |
| |
| ## Handling Other Commands |
| |
| The credentials helper protocol may be extended with additional verbs in future, |
| so for forward-compatibility a credentials helper must react to any unsupported |
| verb by printing an end-user-oriented plain text error message to its stderr |
| stream and then exiting with a non-zero status code. |
| |
| ## Handling Unsupported Credentials Object Properties |
| |
| Currently Terraform defines only the `token` property within JSON credentials |
| objects, but this format might be extended in future. |
| |
| If a credentials helper is asked to store an object that has any properties |
| other than `token` and if it is not able to faithfully retain them then it |
| must behave as if the object is unstorable, returning an error. It must _not_ |
| store the `token` value in isolation and silently drop other properties, as |
| that might change the meaning of the credentials object. |
| |
| If technically possible within the constraints of the target system, a |
| credentials helper should prefer to store the whole JSON object as-is for |
| later retrieval. For systems that are more constrained, it's acceptable to |
| store only the `token` string so long as the program rejects objects containing |
| other properties as described above. |
| |
| ## Installing a Credentials Helper |
| |
| Terraform does not have any automatic installation mechanism for credentials |
| helpers. Instead, the user must extract the helper program executable into |
| one of the [default plugin search locations](/plugin/how-terraform-works#plugin-locations). |
| |
| If you are packaging a credentials helper for distribution, place it in an |
| named with the expected naming scheme (`terraform-credentials-example`) and, |
| if the containing archive format supports it and it's meaningful for the |
| target operating system, mark the file as executable to increase the chances |
| that it will work immediately after extraction. |
| |
| Terraform does _not_ honor the `-plugin-dir` argument to `terraform init` when |
| searching for credentials helpers, because credentials are also used by other |
| commands that can be run prior to `terraform init`. Only the default search |
| locations are supported. |