github.com/muratcelep/terraform@v1.1.0-beta2-not-internal-4/website/docs/internals/credentials-helpers.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Credentials Helpers"
     4  sidebar_current: "docs-internals-credentials-helpers"
     5  description: |-
     6    Credentials helpers are external programs that know how to store and retrieve API tokens for remote Terraform services.
     7  ---
     8  
     9  # Credentials Helpers
    10  
    11  For Terraform-specific features that interact with remote network services,
    12  such as [module registries](/docs/registry/) and
    13  [remote operations](/docs/cloud/run/cli.html), Terraform by default looks for
    14  API credentials to use in these calls in
    15  [the CLI configuration](/docs/cli/config/config-file.html).
    16  
    17  Credentials helpers offer an alternative approach that allows you to customize
    18  how Terraform obtains credentials using an external program, which can then
    19  directly access an existing secrets management system in your organization.
    20  
    21  This page is about how to write and install a credentials helper. To learn
    22  how to configure a credentials helper that was already installed, see
    23  [the CLI config Credentials Helpers section](/docs/cli/config/config-file.html#credentials-helpers).
    24  
    25  ## How Terraform finds Credentials Helpers
    26  
    27  A credentials helper is a normal executable program that is installed in a
    28  particular location and whose name follows a specific naming convention.
    29  
    30  A credentials helper called "credstore", for example, would be implemented as
    31  an executable program named `terraform-credentials-credstore` (with an `.exe`
    32  extension on Windows only), and installed in one of the
    33  [default plugin search locations](/docs/extend/how-terraform-works.html#plugin-locations).
    34  
    35  ## How Terraform runs Credentials Helpers
    36  
    37  Once Terraform has located the configured credentials helper, it will execute
    38  it once for each credentials request that cannot be satisfied by a `credentials`
    39  block in the CLI configuration.
    40  
    41  For the following examples, we'll assume a "credstore" credentials helper
    42  configured as follows:
    43  
    44  ```
    45  credentials_helper "credstore" {
    46    args = ["--host=credstore.example.com"]
    47  }
    48  ```
    49  
    50  Terraform runs the helper program with each of the arguments given in `args`,
    51  followed by an _verb_ and then the hostname that the verb will apply to.
    52  The current set of verbs are:
    53  
    54  * `get`: retrieve the credentials for the given hostname
    55  * `store`: store new credentials for the given hostname
    56  * `forget`: delete any stored credentials for the given hostname
    57  
    58  To represent credentials, the credentials helper protocol uses a JSON object
    59  whose contents correspond with the contents of
    60  [`credentials` blocks in the CLI configuration](/docs/cli/config/config-file.html#credentials).
    61  To represent an API token, the object contains a property called "token" whose
    62  value is the token string:
    63  
    64  ```json
    65  {
    66    "token": "example-token-value"
    67  }
    68  ```
    69  
    70  The following sections describe the specific expected behaviors for each of the
    71  three verbs.
    72  
    73  ## `get`: retrieve the credentials for the given hostname
    74  
    75  To retrieve credentials for `app.terraform.io`, Terraform would run the
    76  "credstore" helper as follows:
    77  
    78  ```
    79  terraform-credentials-credstore --host=credstore.example.com get app.terraform.io
    80  ```
    81  
    82  If the credentials helper is able to provide credentials for the given host
    83  then it must print a JSON credentials object to its stdout stream and then
    84  exit with status code zero to indicate success.
    85  
    86  If the credentials helper definitively has no credentials for the given host,
    87  then it must print an empty JSON object to stdout and exit with status zero.
    88  
    89  If the credentials helper is unable to provide the requested credentials for
    90  any other reason, it must print an end-user-oriented plain text error message
    91  to its stderr stream and then exit with a _non-zero_ status code.
    92  
    93  ## `store`: store new credentials for the given hostname
    94  
    95  To store new credentials for `app.terraform.io`, Terraform would run the
    96  "credstore" helper as follows:
    97  
    98  ```
    99  terraform-credentials-credstore --host=credstore.example.com store app.terraform.io
   100  ```
   101  
   102  Terraform then writes a JSON credentials object to the helper program's stdin
   103  stream. If the helper is able to store the given credentials then it must do
   104  so and then exit with status code zero and no output on stdout or stderr to
   105  indicate success.
   106  
   107  If it is unable to store the given credentials for any reason, it _must_ still
   108  fully read its stdin until EOF and then print an end-user-oriented plain text
   109  error message to its stderr stream before exiting with a non-zero status
   110  code.
   111  
   112  The new credentials must fully replace any existing credentials stored for the
   113  given hostname.
   114  
   115  ## `forget`: delete any stored credentials for the given hostname
   116  
   117  To forget any existing credentials for `app.terraform.io`, Terraform would run
   118  the "credstore" helper as follows:
   119  
   120  ```
   121  terraform-credentials-credstore --host=credstore.example.com forget app.terraform.io
   122  ```
   123  
   124  No JSON credentials objects are used for the `forget` verb.
   125  
   126  If the helper program is able to delete its stored credentials for the given
   127  hostname or if there are no such credentials stored already then it must
   128  exist with status code zero and produce no output on stdout or stderr.
   129  
   130  If it is unable to forget the stored credentials for any reason, particularly
   131  if the helper cannot be sure that the credentials are no longer available for
   132  retrieval, the helper program must print an end-user-oriented plain text error
   133  message to its stderr stream and then exit with a non-zero status code.
   134  
   135  ## Handling Other Commands
   136  
   137  The credentials helper protocol may be extended with additional verbs in future,
   138  so for forward-compatibility a credentials helper must react to any unsupported
   139  verb by printing an end-user-oriented plain text error message to its stderr
   140  stream and then exiting with a non-zero status code.
   141  
   142  ## Handling Unsupported Credentials Object Properties
   143  
   144  Currently Terraform defines only the `token` property within JSON credentials
   145  objects, but this format might be extended in future.
   146  
   147  If a credentials helper is asked to store an object that has any properties
   148  other than `token` and if it is not able to faithfully retain them then it
   149  must behave as if the object is unstorable, returning an error. It must _not_
   150  store the `token` value in isolation and silently drop other properties, as
   151  that might change the meaning of the credentials object.
   152  
   153  If technically possible within the constraints of the target system, a
   154  credentials helper should prefer to store the whole JSON object as-is for
   155  later retrieval. For systems that are more constrained, it's acceptable to
   156  store only the `token` string so long as the program rejects objects containing
   157  other properties as described above.
   158  
   159  ## Installing a Credentials Helper
   160  
   161  Terraform does not have any automatic installation mechanism for credentials
   162  helpers. Instead, the user must extract the helper program executable into
   163  one of the [default plugin search locations](/docs/extend/how-terraform-works.html#plugin-locations).
   164  
   165  If you are packaging a credentials helper for distribution, place it in an
   166  named with the expected naming scheme (`terraform-credentials-example`) and,
   167  if the containing archive format supports it and it's meaningful for the
   168  target operating system, mark the file as executable to increase the chances
   169  that it will work immediately after extraction.
   170  
   171  Terraform does _not_ honor the `-plugin-dir` argument to `terraform init` when
   172  searching for credentials helpers, because credentials are also used by other
   173  commands that can be run prior to `terraform init`. Only the default search
   174  locations are supported.