terraform your HCP Terraform runs Important If you are self hosting HCP Terraform agents terraform cloud docs agents ensure your agents use v1 7 0 terraform cloud docs agents changelog 1 7 0 03 02 2023 or above To use the latest dynamic credentials features upgrade your agents to the latest version terraform cloud docs agents changelog Dynamic Credentials with the GCP Provider page title Dynamic Credentials with the GCP Provider Workspaces HCP Terraform Use OpenID Connect to get short term credentials for the GCP Terraform provider in

Answer:
---
page_title: Dynamic Credentials with the GCP Provider - Workspaces - HCP Terraform
description: >-
  Use OpenID Connect to get short-term credentials for the GCP Terraform provider in
  your HCP Terraform runs.
---

# Dynamic Credentials with the GCP Provider

~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.7.0](/terraform/cloud-docs/agents/changelog#1-7-0-03-02-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog).

You can use HCP Terraform’s native OpenID Connect integration with GCP to get [dynamic credentials](/terraform/cloud-docs/workspaces/dynamic-provider-credentials) for the GCP provider in your HCP Terraform runs. Configuring the integration requires the following steps:

1. **[Configure GCP](#configure-gcp):** Set up a trust configuration between GCP and HCP Terraform. Then, you must create GCP roles and policies for your HCP Terraform workspaces.
2. **[Configure HCP Terraform](#configure-hcp-terraform):** Add environment variables to the HCP Terraform workspaces where you want to use Dynamic Credentials.

Once you complete the setup, HCP Terraform automatically authenticates to GCP during each run. The GCP provider authentication is valid for the length of the plan or apply.

!> **Warning:** Dynamic credentials with the GCP provider do not work if your Terraform Enterprise instance uses a custom or self-signed certificate. This limitation is due to restrictions in GCP.

## Configure GCP
You must enable and configure a workload identity pool and provider on GCP. These instructions use the GCP console, but you can also use Terraform to configure GCP. Refer to our [example Terraform configuration](https://github.com/hashicorp/terraform-dynamic-credentials-setup-examples/tree/main/gcp).
### Add a Workload Identity Pool and Provider
Google documentation for setting this up can be found here: [Configuring workload identity federation with other identity providers](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers).

Before starting to create the resources, you must enable the APIs mentioned at the start of the [Configure workload Identity federation](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#configure).
#### Add a Workload Identity Pool
The following information should be specified:
* **Name**: Name for the pool, such as `my-tfc-pool`. The name is also used as the pool ID. You can't change the pool ID later.

The following is optional, but may be desired:
* **Pool ID**: The ID for the pool. This defaults to the name as mentioned above, but can be set to another value.
* **Description**: Text that describes the purpose of the pool.

You will also want to ensure that the `Enabled Pool` option is set to be enabled before clicking next.

#### Add a Workload Identity Provider
You must add a workload identity provider to the pool. The following information should be specified:
* **Provider type**: Must be `OpenID Connect (OIDC)`.
* **Provider name**: Name for the identity provider, such as `my-tfc-provider`. The name is also used as the provider ID. You can’t change the provider ID later.
* **Issuer (URL)**: The address of the TFC/E instance, such as https://app.terraform.io
    * **Important**: make sure this value starts with **https://** and does _not_ have a trailing slash.
* **Audiences**: This can be left as `Default audience` if you are planning on using the default audience HCP Terraform provides.
    * **Important**: you must select the `Allowed audiences` toggle and set this to the value of `TFC_GCP_WORKLOAD_IDENTITY_AUDIENCE`, if configured.
* **Provider attributes mapping**: At the minimum this must include `assertion.sub` for the `google.subject` entry. Other mappings can be added for other claims in the identity token to attributes by adding `attribute.[claim name]` on the Google side and `assertion.[claim name]` on the OIDC side of a new mapping.
* **Attribute Conditions**: Conditions to restrict which identity tokens can authenticate using the workload identity pool, such as `assertion.sub.startsWith("organization:my-org:project:my-project:workspace:my-workspace")` to restrict access to identity tokens from a specific workspace. See this page in Google documentation for more information on the expression language: [Attribute conditions](https://cloud.google.com/iam/docs/workload-identity-federation#conditions).

!> **Warning**: you should always check, at minimum, the audience and the name of the organization in order to prevent unauthorized access from other HCP Terraform organizations!

The following is optional, but may be desired:
* **Provider ID**: The ID for the provider. This defaults to the name as mentioned above, but can be set to another value.
### Add a Service Account and Permissions
You must next add a service account and properly configure the permissions.
#### Create a Service Account
Google documentation for setting this up can be found here: [Creating a service account for the external workload](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#create_a_service_account_for_the_external_workload).

The following information should be specified:
* **Service account name**: Name for the service account, such as `tfc-service-account`. The name is also used as the pool ID. You can't change the pool ID later.

The following is optional, but may be desired:
* **Service account ID**: The ID for the service account. This defaults to the name as mentioned above, but can be set to another value.
* **Description**: Text that describes the purpose of the service account.
#### Grant IAM Permissions
The next step in the setup wizard will allow for granting IAM permissions for the service account. The role that is given to the service account will vary depending on your specific needs and project setup. This should in general be the most minimal set of permissions needed for the service account to properly function.
#### Grant External Permissions
Once the service account has been created and granted IAM permissions, you will need to grant access to the service account for the identity pool created above. Google documentation for setting this up can be found here: [Allow the external workload to impersonate the service account](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#allow_the_external_workload_to_impersonate_the_service_account).
## Configure HCP Terraform
You’ll need to set some environment variables in your HCP Terraform workspace in order to configure HCP Terraform to authenticate with GCP using dynamic credentials. You can set these as workspace variables, or if you’d like to share one GCP service account across multiple workspaces, you can use a variable set. When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details.
### Required Environment Variables
| Variable                                                                                | Value                                                                        | Notes                                                                                |
|-------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `TFC_GCP_PROVIDER_AUTH`
`TFC_GCP_PROVIDER_AUTH[_TAG]`
_(Default variable not supported)_                                  | `true`                                                                       | Requires **v1.7.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to use dynamic credentials to authenticate to GCP.                                                                                |
| `TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL`
`TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL[_TAG]`
`TFC_DEFAULT_GCP_RUN_SERVICE_ACCOUNT_EMAIL` | The service account email HCP Terraform will use when authenticating to GCP. | Requires **v1.7.0** or later if self-managing agents. Optional if `TFC_GCP_PLAN_SERVICE_ACCOUNT_EMAIL` and `TFC_GCP_APPLY_SERVICE_ACCOUNT_EMAIL` are both provided. These variables are described [below](/terraform/cloud-docs/workspaces/dynamic-provider-credentials/gcp-configuration#optional-environment-variables) |

You must also include information about the GCP Workload Identity Provider that HCP Terraform will use when authenticating to GCP. You can supply this information in two different ways:

1. By providing one unified variable containing the canonical name of the workload identity provider.
2. By providing the project number, pool ID, and provider ID as separate variables.

You should avoid setting both types of variables, but if you do, the unified version will take precedence.

#### Unified Variable

| Variable                                                                                | Value                                                                                | Notes                                                                                |
|----------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `TFC_GCP_WORKLOAD_PROVIDER_NAME`
`TFC_GCP_WORKLOAD_PROVIDER_NAME[_TAG]`
`TFC_DEFAULT_GCP_WORKLOAD_PROVIDER_NAME` | The canonical name of the workload identity provider. This must be in the form mentioned for the `name` attribute [here](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/iam_workload_identity_pool_provider#attributes-reference) | Requires **v1.7.0** or later if self-managing agents. This will take precedence over `TFC_GCP_PROJECT_NUMBER`, `TFC_GCP_WORKLOAD_POOL_ID`, and `TFC_GCP_WORKLOAD_PROVIDER_ID` if set. |

#### Separate Variables

| Variable                                                                                | Value                                                       | Notes                                                                                |
|----------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
| `TFC_GCP_PROJECT_NUMBER`
`TFC_GCP_PROJECT_NUMBER[_TAG]`
`TFC_DEFAULT_GCP_PROJECT_NUMBER`                   | The project number where the pool and other resources live. | Requires **v1.7.0** or later if self-managing agents. This is _not_ the project ID and is a separate number. |
| `TFC_GCP_WORKLOAD_POOL_ID`
`TFC_GCP_WORKLOAD_POOL_ID[_TAG]`
`TFC_DEFAULT_GCP_WORKLOAD_POOL_ID`             | The workload pool ID.                                       | Requires **v1.7.0** or later if self-managing agents.                                                        |
| `TFC_GCP_WORKLOAD_PROVIDER_ID`
`TFC_GCP_WORKLOAD_PROVIDER_ID[_TAG]`
`TFC_DEFAULT_GCP_WORKLOAD_PROVIDER_ID` | The workload identity provider ID.                          | Requires **v1.7.0** or later if self-managing agents.                                                        |

### Optional Environment Variables
You may need to set these variables, depending on your use case.

| Variable                                                                                | Value                                                                                | Notes                                                                                |
|-------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
| `TFC_GCP_WORKLOAD_IDENTITY_AUDIENCE`
`TFC_GCP_WORKLOAD_IDENTITY_AUDIENCE[_TAG]`
`TFC_DEFAULT_GCP_WORKLOAD_IDENTITY_AUDIENCE`    | Will be used as the `aud` claim for the identity token. Defaults to a string of the form mentioned [here](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#oidc_1) in the GCP docs with the leading **https:** stripped. | Requires **v1.7.0** or later if self-managing agents. This is one of the default `aud` formats that GCP accepts.                          |
| `TFC_GCP_PLAN_SERVICE_ACCOUNT_EMAIL`
`TFC_GCP_PLAN_SERVICE_ACCOUNT_EMAIL[_TAG]`
`TFC_DEFAULT_GCP_PLAN_SERVICE_ACCOUNT_EMAIL`    | The service account email to use for the plan phase of a run.                                                                                | Requires **v1.7.0** or later if self-managing agents. Will fall back to the value of `TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL` if not provided. |
| `TFC_GCP_APPLY_SERVICE_ACCOUNT_EMAIL`
`TFC_GCP_APPLY_SERVICE_ACCOUNT_EMAIL[_TAG]`
`TFC_DEFAULT_GCP_APPLY_SERVICE_ACCOUNT_EMAIL` | The service account email to use for the apply phase of a run.                                                                                | Requires **v1.7.0** or later if self-managing agents. Will fall back to the value of `TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL` if not provided. |

## Configure the GCP Provider
Make sure that you’re passing values for the `project` and `region` arguments into the provider configuration block.

Make sure that you’re not setting values for the `GOOGLE_CREDENTIALS` or `GOOGLE_APPLICATION_CREDENTIALS` environment variables as these will conflict with the dynamic credentials authentication process.

### Specifying Multiple Configurations

~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog).

You can add additional variables to handle multiple distinct GCP setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`.

For more details, see [Specifying Multiple Configurations](/terraform/cloud-docs/workspaces/dynamic-provider-credentials/specifying-multiple-configurations).

#### Required Terraform Variable

To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks.

```hcl
variable "tfc_gcp_dynamic_credentials" {
  description = "Object containing GCP dynamic credentials configuration"
  type = object({
    default = object({
      credentials = string
    })
    aliases = map(object({
      credentials = string
    }))
  })
}
```

#### Example Usage

```hcl
provider "google" {
  credentials = var.tfc_gcp_dynamic_credentials.default.credentials
}

provider "google" {
  alias = "ALIAS1"
  credentials = var.tfc_gcp_dynamic_credentials.aliases["ALIAS1"].credentials
}
```

page title  Dynamic Credentials with the GCP Provider   Workspaces   HCP Terraform description       Use OpenID Connect to get short term credentials for the GCP Terraform provider in   your HCP Terraform runs         Dynamic Credentials with the GCP Provider       Important    If you are self hosting  HCP Terraform agents   terraform cloud docs agents   ensure your agents use  v1 7 0   terraform cloud docs agents changelog 1 7 0 03 02 2023  or above  To use the latest dynamic credentials features   upgrade your agents to the latest version   terraform cloud docs agents changelog     You can use HCP Terraform s native OpenID Connect integration with GCP to get  dynamic credentials   terraform cloud docs workspaces dynamic provider credentials  for the GCP provider in your HCP Terraform runs  Configuring the integration requires the following steps   1     Configure GCP   configure gcp     Set up a trust configuration between GCP and HCP Terraform  Then  you must create GCP roles and policies for your HCP Terraform workspaces  2     Configure HCP Terraform   configure hcp terraform     Add environment variables to the HCP Terraform workspaces where you want to use Dynamic Credentials   Once you complete the setup  HCP Terraform automatically authenticates to GCP during each run  The GCP provider authentication is valid for the length of the plan or apply        Warning    Dynamic credentials with the GCP provider do not work if your Terraform Enterprise instance uses a custom or self signed certificate  This limitation is due to restrictions in GCP      Configure GCP You must enable and configure a workload identity pool and provider on GCP  These instructions use the GCP console  but you can also use Terraform to configure GCP  Refer to our  example Terraform configuration  https   github com hashicorp terraform dynamic credentials setup examples tree main gcp       Add a Workload Identity Pool and Provider Google documentation for setting this up can be found here   Configuring workload identity federation with other identity providers  https   cloud google com iam docs workload identity federation with other providers    Before starting to create the resources  you must enable the APIs mentioned at the start of the  Configure workload Identity federation  https   cloud google com iam docs workload identity federation with other providers configure        Add a Workload Identity Pool The following information should be specified      Name    Name for the pool  such as  my tfc pool   The name is also used as the pool ID  You can t change the pool ID later   The following is optional  but may be desired      Pool ID    The ID for the pool  This defaults to the name as mentioned above  but can be set to another value      Description    Text that describes the purpose of the pool   You will also want to ensure that the  Enabled Pool  option is set to be enabled before clicking next        Add a Workload Identity Provider You must add a workload identity provider to the pool  The following information should be specified      Provider type    Must be  OpenID Connect  OIDC        Provider name    Name for the identity provider  such as  my tfc provider   The name is also used as the provider ID  You can t change the provider ID later      Issuer  URL     The address of the TFC E instance  such as https   app terraform io         Important    make sure this value starts with   https      and does  not  have a trailing slash      Audiences    This can be left as  Default audience  if you are planning on using the default audience HCP Terraform provides          Important    you must select the  Allowed audiences  toggle and set this to the value of  TFC GCP WORKLOAD IDENTITY AUDIENCE   if configured      Provider attributes mapping    At the minimum this must include  assertion sub  for the  google subject  entry  Other mappings can be added for other claims in the identity token to attributes by adding  attribute  claim name   on the Google side and  assertion  claim name   on the OIDC side of a new mapping      Attribute Conditions    Conditions to restrict which identity tokens can authenticate using the workload identity pool  such as  assertion sub startsWith  organization my org project my project workspace my workspace    to restrict access to identity tokens from a specific workspace  See this page in Google documentation for more information on the expression language   Attribute conditions  https   cloud google com iam docs workload identity federation conditions         Warning    you should always check  at minimum  the audience and the name of the organization in order to prevent unauthorized access from other HCP Terraform organizations   The following is optional  but may be desired      Provider ID    The ID for the provider  This defaults to the name as mentioned above  but can be set to another value      Add a Service Account and Permissions You must next add a service account and properly configure the permissions       Create a Service Account Google documentation for setting this up can be found here   Creating a service account for the external workload  https   cloud google com iam docs workload identity federation with other providers create a service account for the external workload    The following information should be specified      Service account name    Name for the service account  such as  tfc service account   The name is also used as the pool ID  You can t change the pool ID later   The following is optional  but may be desired      Service account ID    The ID for the service account  This defaults to the name as mentioned above  but can be set to another value      Description    Text that describes the purpose of the service account       Grant IAM Permissions The next step in the setup wizard will allow for granting IAM permissions for the service account  The role that is given to the service account will vary depending on your specific needs and project setup  This should in general be the most minimal set of permissions needed for the service account to properly function       Grant External Permissions Once the service account has been created and granted IAM permissions  you will need to grant access to the service account for the identity pool created above  Google documentation for setting this up can be found here   Allow the external workload to impersonate the service account  https   cloud google com iam docs workload identity federation with other providers allow the external workload to impersonate the service account      Configure HCP Terraform You ll need to set some environment variables in your HCP Terraform workspace in order to configure HCP Terraform to authenticate with GCP using dynamic credentials  You can set these as workspace variables  or if you d like to share one GCP service account across multiple workspaces  you can use a variable set  When you configure dynamic provider credentials with multiple provider configurations of the same type  use either a default variable or a tagged alias variable name for each provider configuration  Refer to  Specifying Multiple Configurations   specifying multiple configurations  for more details      Required Environment Variables   Variable                                                                                Value                                                                          Notes                                                                                TFC GCP PROVIDER AUTH  br    TFC GCP PROVIDER AUTH  TAG   br     Default variable not supported                                       true                                                                          Requires   v1 7 0   or later if self managing agents  Must be present and set to  true   or HCP Terraform will not attempt to use dynamic credentials to authenticate to GCP                                                                                TFC GCP RUN SERVICE ACCOUNT EMAIL  br    TFC GCP RUN SERVICE ACCOUNT EMAIL  TAG   br    TFC DEFAULT GCP RUN SERVICE ACCOUNT EMAIL    The service account email HCP Terraform will use when authenticating to GCP    Requires   v1 7 0   or later if self managing agents  Optional if  TFC GCP PLAN SERVICE ACCOUNT EMAIL  and  TFC GCP APPLY SERVICE ACCOUNT EMAIL  are both provided  These variables are described  below   terraform cloud docs workspaces dynamic provider credentials gcp configuration optional environment variables     You must also include information about the GCP Workload Identity Provider that HCP Terraform will use when authenticating to GCP  You can supply this information in two different ways   1  By providing one unified variable containing the canonical name of the workload identity provider  2  By providing the project number  pool ID  and provider ID as separate variables   You should avoid setting both types of variables  but if you do  the unified version will take precedence        Unified Variable    Variable                                                                                Value                                                                                Notes                                                                                TFC GCP WORKLOAD PROVIDER NAME  br    TFC GCP WORKLOAD PROVIDER NAME  TAG   br    TFC DEFAULT GCP WORKLOAD PROVIDER NAME    The canonical name of the workload identity provider  This must be in the form mentioned for the  name  attribute  here  https   registry terraform io providers hashicorp google latest docs resources iam workload identity pool provider attributes reference    Requires   v1 7 0   or later if self managing agents  This will take precedence over  TFC GCP PROJECT NUMBER    TFC GCP WORKLOAD POOL ID   and  TFC GCP WORKLOAD PROVIDER ID  if set          Separate Variables    Variable                                                                                Value                                                         Notes                                                                                TFC GCP PROJECT NUMBER  br    TFC GCP PROJECT NUMBER  TAG   br    TFC DEFAULT GCP PROJECT NUMBER                      The project number where the pool and other resources live    Requires   v1 7 0   or later if self managing agents  This is  not  the project ID and is a separate number       TFC GCP WORKLOAD POOL ID  br    TFC GCP WORKLOAD POOL ID  TAG   br    TFC DEFAULT GCP WORKLOAD POOL ID                The workload pool ID                                          Requires   v1 7 0   or later if self managing agents                                                              TFC GCP WORKLOAD PROVIDER ID  br    TFC GCP WORKLOAD PROVIDER ID  TAG   br    TFC DEFAULT GCP WORKLOAD PROVIDER ID    The workload identity provider ID                             Requires   v1 7 0   or later if self managing agents                                                                 Optional Environment Variables You may need to set these variables  depending on your use case     Variable                                                                                Value                                                                                Notes                                                                                TFC GCP WORKLOAD IDENTITY AUDIENCE  br    TFC GCP WORKLOAD IDENTITY AUDIENCE  TAG   br    TFC DEFAULT GCP WORKLOAD IDENTITY AUDIENCE       Will be used as the  aud  claim for the identity token  Defaults to a string of the form mentioned  here  https   cloud google com iam docs workload identity federation with other providers oidc 1  in the GCP docs with the leading   https    stripped    Requires   v1 7 0   or later if self managing agents  This is one of the default  aud  formats that GCP accepts                                TFC GCP PLAN SERVICE ACCOUNT EMAIL  br    TFC GCP PLAN SERVICE ACCOUNT EMAIL  TAG   br    TFC DEFAULT GCP PLAN SERVICE ACCOUNT EMAIL       The service account email to use for the plan phase of a run                                                                                Requires   v1 7 0   or later if self managing agents  Will fall back to the value of  TFC GCP RUN SERVICE ACCOUNT EMAIL  if not provided       TFC GCP APPLY SERVICE ACCOUNT EMAIL  br    TFC GCP APPLY SERVICE ACCOUNT EMAIL  TAG   br    TFC DEFAULT GCP APPLY SERVICE ACCOUNT EMAIL    The service account email to use for the apply phase of a run                                                                                Requires   v1 7 0   or later if self managing agents  Will fall back to the value of  TFC GCP RUN SERVICE ACCOUNT EMAIL  if not provided        Configure the GCP Provider Make sure that you re passing values for the  project  and  region  arguments into the provider configuration block   Make sure that you re not setting values for the  GOOGLE CREDENTIALS  or  GOOGLE APPLICATION CREDENTIALS  environment variables as these will conflict with the dynamic credentials authentication process       Specifying Multiple Configurations       Important    If you are self hosting  HCP Terraform agents   terraform cloud docs agents   ensure your agents use  v1 12 0   terraform cloud docs agents changelog 1 12 0 07 26 2023  or above  To use the latest dynamic credentials features   upgrade your agents to the latest version   terraform cloud docs agents changelog    You can add additional variables to handle multiple distinct GCP setups  enabling you to use multiple  provider aliases   terraform language providers configuration alias multiple provider configurations  within the same workspace  You can configure each set of credentials independently  or use default values by configuring the variables prefixed with  TFC DEFAULT     For more details  see  Specifying Multiple Configurations   terraform cloud docs workspaces dynamic provider credentials specifying multiple configurations         Required Terraform Variable  To use additional configurations  add the following code to your Terraform configuration  This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks      hcl variable  tfc gcp dynamic credentials      description    Object containing GCP dynamic credentials configuration    type   object       default   object         credentials   string            aliases   map object         credentials   string                          Example Usage     hcl provider  google      credentials   var tfc gcp dynamic credentials default credentials    provider  google      alias    ALIAS1    credentials   var tfc gcp dynamic credentials aliases  ALIAS1   credentials


terraform HCP Vault Secrets Backed Dynamic Credentials with the GCP Provider your HCP Terraform runs page title HCP Vault Secrets Backed Dynamic Credentials with the GCP Provider Workspaces HCP Terraform Important If you are self hosting HCP Terraform agents terraform cloud docs agents ensure your agents use v1 16 0 terraform cloud docs agents changelog 1 16 0 10 02 2024 or above To use the latest dynamic credentials features upgrade your agents to the latest version terraform cloud docs agents changelog Use OpenID Connect and HCP Vault Secrets to get short term credentials for the GCP Terraform provider in

Answer:
---
page_title: HCP Vault Secrets-Backed Dynamic Credentials with the GCP Provider - Workspaces - HCP Terraform
description: >-
  Use OpenID Connect and HCP Vault Secrets to get short-term credentials for the GCP Terraform provider in
  your HCP Terraform runs.
---

# HCP Vault Secrets-Backed Dynamic Credentials with the GCP Provider

~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.16.0](/terraform/cloud-docs/agents/changelog#1-16-0-10-02-2024) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog).

You can use HCP Terraform’s native OpenID Connect integration with HCP to use [HCP Vault Secrets-backed dynamic credentials](/terraform/cloud-docs/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed) with the GCP provider in your HCP Terraform runs. Configuring the integration requires the following steps:

1. **[Configure HCP Provider Credentials](#configure-hcp-provider-credentials)**: Set up a trust configuration between HCP Vault Secrets and HCP Terraform, create HCP Vault Secrets roles and policies for your HCP Terraform workspaces, and add environment variables to those workspaces.
2. **[Configure HCP Vault Secrets](#configure-hcp-vault-secrets-gcp-secrets-engine)**: Set up your HCP project's GCP integration and dynamic secret.
3. **[Configure HCP Terraform](#configure-hcp-terraform)**: Add additional environment variables to the HCP Terraform workspaces where you want to use HCP Vault Secrets-backed dynamic credentials.
4. **[Configure Terraform Providers](#configure-terraform-providers)**: Configure your Terraform providers to work with HCP Vault Secrets-backed dynamic credentials.

Once you complete this setup, HCP Terraform automatically authenticates with GCP via HCP Vault Secrets-generated credentials during the plan and apply phase of each run. The GCP provider's authentication is only valid for the length of the plan or apply phase.

## Configure HCP Provider Credentials
You must first set up HCP dynamic provider credentials before you can use HCP Vault Secrets-backed dynamic credentials. This includes creating a service principal, configuring trust between HCP and HCP Terraform, and populating the required environment variables in your HCP Terraform workspace.

[See the setup instructions for HCP dynamic provider credentials](/terraform/cloud-docs/workspaces/dynamic-provider-credentials/hcp-configuration).

## Configure HCP Vault Secrets GCP Secrets Engine
Follow the instructions in the HCP Vault Secrets documentation for [setting up the GCP integration in your HCP project](/hcp/docs/vault-secrets/dynamic-secrets/gcp).

## Configure HCP Terraform
Next, you need to set certain environment variables in your HCP Terraform workspace to authenticate HCP Terraform with GCP using HCP Vault Secrets-backed dynamic credentials. These variables are in addition to those you previously set while configuring [HCP provider credentials](#configure-hcp-provider-credentials). You can add these as workspace variables or as a [variable set](/terraform/cloud-docs/workspaces/variables/managing-variables#variable-sets).

### Required Common Environment Variables
| Variable                                                                                | Value                                                                        | Notes                                                                                |
|---------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| `TFC_HVS_BACKED_GCP_AUTH`
`TFC_HVS_BACKED_GCP_AUTH[_TAG]`
_(Default variable not supported)_  | `true`                                                                       | Requires **v1.16.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate with GCP.   |
| `TFC_HVS_BACKED_GCP_RUN_SECRET_RESOURCE_NAME`                                                           | The name of the HCP Vault Secrets dynamic secret resource to read.           | Requires **v1.16.0** or later if self-managing agents. Must be present.                                                                                |

### Optional Common Environment Variables
You may need to set these variables, depending on your use case.

| Variable                                                                                | Value                                                                                | Notes                                                                                |
|-----------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| `TFC_HVS_BACKED_GCP_HCP_CONFIG`
`TFC_HVS_BACKED_GCP_HCP_CONFIG[_TAG]`
`TFC_DEFAULT_HVS_BACKED_GCP_HCP_CONFIG`     | The name of the non-default HCP configuration for workspaces using [multiple HCP configurations](/terraform/cloud-docs/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). | Requires **v1.16.0** or later if self-managing agents. Will fall back to using the default HCP Vault Secrets configuration if not provided. |
| `TFC_HVS_BACKED_GCP_PLAN_SECRET_RESOURCE_NAME`                                                                              | The name of the HCP Vault Secrets dynamic secret resource to read for the plan phase.                                                                                | Requires **v1.16.0** or later if self-managing agents. Must be present.                                                                      |
| `TFC_HVS_BACKED_GCP_APPLY_SECRET_RESOURCE_NAME`                                                                             | The name of the HCP Vault Secrets dynamic secret resource to read for the apply phase.                                                                                | Requires **v1.16.0** or later if self-managing agents. Must be present.                                                                      |

## Configure Terraform Providers
The final step is to directly configure your GCP and HCP Vault Secrets providers.

### Configure the GCP Provider
Ensure you pass values for the `project` and `region` arguments into the provider configuration block.

Ensure you are not setting values or environment variables for `GOOGLE_CREDENTIALS` or `GOOGLE_APPLICATION_CREDENTIALS`. Otherwise, these values may interfere with dynamic provider credentials.

### Specifying Multiple Configurations

~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.16.0](/terraform/cloud-docs/agents/changelog#1-16-0-10-02-2024) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog).

You can add additional variables to handle multiple distinct HCP Vault Secrets-backed GCP setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`.

For more details, see [Specifying Multiple Configurations](/terraform/cloud-docs/workspaces/dynamic-provider-credentials/specifying-multiple-configurations).

#### Required Terraform Variable

To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks.

```hcl
variable "tfc_hvs_backed_gcp_dynamic_credentials" {
  description = "Object containing HCP Vault Secrets-backed GCP dynamic credentials configuration"
  type = object({
    default = object({
      credentials = string
      access_token = string
    })
    aliases = map(object({
      credentials = string
      access_token = string
    }))
  })
}
```

#### Example Usage

##### Access Token

```hcl
provider "google" {
  access_token = var.tfc_hvs_backed_gcp_dynamic_credentials.default.access_token
}

provider "google" {
  alias = "ALIAS1"
  access_token = var.tfc_hvs_backed_gcp_dynamic_credentials.aliases["ALIAS1"].access_token
}
```

##### Credentials

```hcl
provider "google" {
  credentials = var.tfc_hvs_backed_gcp_dynamic_credentials.default.credentials
}

provider "google" {
  alias = "ALIAS1"
  credentials = var.tfc_hvs_backed_gcp_dynamic_credentials.aliases["ALIAS1"].credentials
}
```

page title  HCP Vault Secrets Backed Dynamic Credentials with the GCP Provider   Workspaces   HCP Terraform description       Use OpenID Connect and HCP Vault Secrets to get short term credentials for the GCP Terraform provider in   your HCP Terraform runs         HCP Vault Secrets Backed Dynamic Credentials with the GCP Provider       Important    If you are self hosting  HCP Terraform agents   terraform cloud docs agents   ensure your agents use  v1 16 0   terraform cloud docs agents changelog 1 16 0 10 02 2024  or above  To use the latest dynamic credentials features   upgrade your agents to the latest version   terraform cloud docs agents changelog    You can use HCP Terraform s native OpenID Connect integration with HCP to use  HCP Vault Secrets backed dynamic credentials   terraform cloud docs workspaces dynamic provider credentials hcp vault secrets backed  with the GCP provider in your HCP Terraform runs  Configuring the integration requires the following steps   1     Configure HCP Provider Credentials   configure hcp provider credentials     Set up a trust configuration between HCP Vault Secrets and HCP Terraform  create HCP Vault Secrets roles and policies for your HCP Terraform workspaces  and add environment variables to those workspaces  2     Configure HCP Vault Secrets   configure hcp vault secrets gcp secrets engine     Set up your HCP project s GCP integration and dynamic secret  3     Configure HCP Terraform   configure hcp terraform     Add additional environment variables to the HCP Terraform workspaces where you want to use HCP Vault Secrets backed dynamic credentials  4     Configure Terraform Providers   configure terraform providers     Configure your Terraform providers to work with HCP Vault Secrets backed dynamic credentials   Once you complete this setup  HCP Terraform automatically authenticates with GCP via HCP Vault Secrets generated credentials during the plan and apply phase of each run  The GCP provider s authentication is only valid for the length of the plan or apply phase      Configure HCP Provider Credentials You must first set up HCP dynamic provider credentials before you can use HCP Vault Secrets backed dynamic credentials  This includes creating a service principal  configuring trust between HCP and HCP Terraform  and populating the required environment variables in your HCP Terraform workspace    See the setup instructions for HCP dynamic provider credentials   terraform cloud docs workspaces dynamic provider credentials hcp configuration       Configure HCP Vault Secrets GCP Secrets Engine Follow the instructions in the HCP Vault Secrets documentation for  setting up the GCP integration in your HCP project   hcp docs vault secrets dynamic secrets gcp       Configure HCP Terraform Next  you need to set certain environment variables in your HCP Terraform workspace to authenticate HCP Terraform with GCP using HCP Vault Secrets backed dynamic credentials  These variables are in addition to those you previously set while configuring  HCP provider credentials   configure hcp provider credentials   You can add these as workspace variables or as a  variable set   terraform cloud docs workspaces variables managing variables variable sets        Required Common Environment Variables   Variable                                                                                Value                                                                          Notes                                                                                TFC HVS BACKED GCP AUTH  br    TFC HVS BACKED GCP AUTH  TAG   br     Default variable not supported       true                                                                          Requires   v1 16 0   or later if self managing agents  Must be present and set to  true   or HCP Terraform will not attempt to authenticate with GCP         TFC HVS BACKED GCP RUN SECRET RESOURCE NAME                                                              The name of the HCP Vault Secrets dynamic secret resource to read              Requires   v1 16 0   or later if self managing agents  Must be present                                                                                Optional Common Environment Variables You may need to set these variables  depending on your use case     Variable                                                                                Value                                                                                Notes                                                                                TFC HVS BACKED GCP HCP CONFIG  br    TFC HVS BACKED GCP HCP CONFIG  TAG   br    TFC DEFAULT HVS BACKED GCP HCP CONFIG        The name of the non default HCP configuration for workspaces using  multiple HCP configurations   terraform cloud docs workspaces dynamic provider credentials specifying multiple configurations     Requires   v1 16 0   or later if self managing agents  Will fall back to using the default HCP Vault Secrets configuration if not provided       TFC HVS BACKED GCP PLAN SECRET RESOURCE NAME                                                                                The name of the HCP Vault Secrets dynamic secret resource to read for the plan phase                                                                                Requires   v1 16 0   or later if self managing agents  Must be present                                                                            TFC HVS BACKED GCP APPLY SECRET RESOURCE NAME                                                                                The name of the HCP Vault Secrets dynamic secret resource to read for the apply phase                                                                                Requires   v1 16 0   or later if self managing agents  Must be present                                                                             Configure Terraform Providers The final step is to directly configure your GCP and HCP Vault Secrets providers       Configure the GCP Provider Ensure you pass values for the  project  and  region  arguments into the provider configuration block   Ensure you are not setting values or environment variables for  GOOGLE CREDENTIALS  or  GOOGLE APPLICATION CREDENTIALS   Otherwise  these values may interfere with dynamic provider credentials       Specifying Multiple Configurations       Important    If you are self hosting  HCP Terraform agents   terraform cloud docs agents   ensure your agents use  v1 16 0   terraform cloud docs agents changelog 1 16 0 10 02 2024  or above  To use the latest dynamic credentials features   upgrade your agents to the latest version   terraform cloud docs agents changelog    You can add additional variables to handle multiple distinct HCP Vault Secrets backed GCP setups  enabling you to use multiple  provider aliases   terraform language providers configuration alias multiple provider configurations  within the same workspace  You can configure each set of credentials independently  or use default values by configuring the variables prefixed with  TFC DEFAULT     For more details  see  Specifying Multiple Configurations   terraform cloud docs workspaces dynamic provider credentials specifying multiple configurations         Required Terraform Variable  To use additional configurations  add the following code to your Terraform configuration  This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks      hcl variable  tfc hvs backed gcp dynamic credentials      description    Object containing HCP Vault Secrets backed GCP dynamic credentials configuration    type   object       default   object         credentials   string       access token   string            aliases   map object         credentials   string       access token   string                          Example Usage        Access Token     hcl provider  google      access token   var tfc hvs backed gcp dynamic credentials default access token    provider  google      alias    ALIAS1    access token   var tfc hvs backed gcp dynamic credentials aliases  ALIAS1   access token              Credentials     hcl provider  google      credentials   var tfc hvs backed gcp dynamic credentials default credentials    provider  google      alias    ALIAS1    credentials   var tfc hvs backed gcp dynamic credentials aliases  ALIAS1   credentials


terraform your HCP Terraform runs page title Vault Backed Dynamic Credentials with the AWS Provider Workspaces HCP Terraform Vault Backed Dynamic Credentials with the AWS Provider Use OpenID Connect and Vault to get short term credentials for the AWS Terraform provider in Important If you are self hosting HCP Terraform agents terraform cloud docs agents ensure your agents use v1 8 0 terraform cloud docs agents changelog 1 8 0 04 18 2023 or above To use the latest dynamic credentials features upgrade your agents to the latest version terraform cloud docs agents changelog

Answer:
---
page_title: Vault-Backed Dynamic Credentials with the AWS Provider - Workspaces - HCP Terraform
description: >-
  Use OpenID Connect and Vault to get short-term credentials for the AWS Terraform provider in
  your HCP Terraform runs.
---

# Vault-Backed Dynamic Credentials with the AWS Provider

~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.8.0](/terraform/cloud-docs/agents/changelog#1-8-0-04-18-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog).

You can use HCP Terraform’s native OpenID Connect integration with Vault to use [Vault-backed dynamic credentials](/terraform/cloud-docs/workspaces/dynamic-provider-credentials/vault-backed) with the AWS provider in your HCP Terraform runs. Configuring the integration requires the following steps:

1. **[Configure Vault Dynamic Provider Credentials](#configure-vault-dynamic-provider-credentials)**: Set up a trust configuration between Vault and HCP Terraform, create Vault roles and policies for your HCP Terraform workspaces, and add environment variables to those workspaces.
2. **[Configure the Vault AWS Secrets Engine](#configure-vault-aws-secrets-engine)**: Set up the AWS secrets engine in your Vault instance.
3. **[Configure HCP Terraform](#configure-hcp-terraform)**: Add additional environment variables to the HCP Terraform workspaces where you want to use Vault-Backed Dynamic Credentials.
4. **[Configure Terraform Providers](#configure-terraform-providers)**: Configure your Terraform providers to work with Vault-backed dynamic credentials.

Once you complete this setup, HCP Terraform automatically authenticates with AWS via Vault-generated credentials during the plan and apply phase of each run. The AWS provider's authentication is only valid for the length of the plan or apply phase.

## Configure Vault Dynamic Provider Credentials
You must first set up Vault dynamic provider credentials before you can use Vault-backed dynamic credentials. This includes setting up the JWT auth backend in Vault, configuring trust between HCP Terraform and Vault, and populating the required environment variables in your HCP Terraform workspace.

[See the setup instructions for Vault dynamic provider credentials](/terraform/cloud-docs/workspaces/dynamic-provider-credentials/vault-configuration).

# Configure Vault AWS Secrets Engine
Follow the instructions in the Vault documentation for [setting up the AWS secrets engine in your Vault instance](/vault/docs/secrets/aws). You can also do this configuration through Terraform. Refer to our [example Terraform configuration](https://github.com/hashicorp/terraform-dynamic-credentials-setup-examples/tree/main/vault-backed/aws).

~> **Important**: carefully consider the limitations and differences between each supported credential type in the AWS secrets engine. These limitations carry over to HCP Terraform’s usage of these credentials for authenticating the AWS provider.

## Configure HCP Terraform
Next, you need to set certain environment variables in your HCP Terraform workspace to authenticate HCP Terraform with AWS using Vault-backed dynamic credentials. These variables are in addition to those you previously set while configuring [Vault dynamic provider credentials](#configure-vault-dynamic-provider-credentials). You can add these as workspace variables or as a [variable set](/terraform/cloud-docs/workspaces/variables/managing-variables#variable-sets). When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details.
### Common Environment Variables
The below variables apply to all AWS auth types.

#### Required Common Environment Variables
| Variable                                                                                | Value                                                                                | Notes                                                                                |
|-------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `TFC_VAULT_BACKED_AWS_AUTH`
`TFC_VAULT_BACKED_AWS_AUTH[_TAG]`
_(Default variable not supported)_                                | `true`                                                                                | Requires **v1.8.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate with AWS.                                                                                |
| `TFC_VAULT_BACKED_AWS_AUTH_TYPE`
`TFC_VAULT_BACKED_AWS_AUTH_TYPE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_AUTH_TYPE`                | Specifies the type of authentication to perform with AWS. Must be one of the following: `iam_user`, `assumed_role`, or `federation_token`. | Requires **v1.8.0** or later if self-managing agents.                                                                                |
| `TFC_VAULT_BACKED_AWS_RUN_VAULT_ROLE`
`TFC_VAULT_BACKED_AWS_RUN_VAULT_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_RUN_VAULT_ROLE` | The role to use in Vault.                                                                                | Requires **v1.8.0** or later if self-managing agents. Optional if `TFC_VAULT_BACKED_AWS_PLAN_VAULT_ROLE` and `TFC_VAULT_BACKED_AWS_APPLY_VAULT_ROLE` are both provided. These variables are described [below](#optional-common-environment-variables). |

#### Optional Common Environment Variables
You may need to set these variables, depending on your use case.

| Variable                                                                                | Value                                                                                | Notes                                                                                |
|-------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| `TFC_VAULT_BACKED_AWS_MOUNT_PATH`
`TFC_VAULT_BACKED_AWS_MOUNT_PATH[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_MOUNT_PATH`                   | The mount path of the AWS secrets engine in Vault.                                                                                | Requires **v1.8.0** or later if self-managing agents. Defaults to `aws`.                                                                               |
| `TFC_VAULT_BACKED_AWS_PLAN_VAULT_ROLE`
`TFC_VAULT_BACKED_AWS_PLAN_VAULT_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_PLAN_VAULT_ROLE`    | The Vault role to use the plan phase of a run.                                                                                | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_AWS_RUN_VAULT_ROLE` if not provided.            |
| `TFC_VAULT_BACKED_AWS_APPLY_VAULT_ROLE`
`TFC_VAULT_BACKED_AWS_APPLY_VAULT_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_APPLY_VAULT_ROLE` | The Vault role to use for the apply phase of a run.                                                                                | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_AWS_RUN_VAULT_ROLE` if not provided.            |
| `TFC_VAULT_BACKED_AWS_SLEEP_SECONDS`
`TFC_VAULT_BACKED_AWS_SLEEP_SECONDS[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_SLEEP_SECONDS`          | The amount of time to wait, in seconds, after obtaining temporary credentials from Vault. e.g., `30` for 30 seconds. Must be 1500 seconds (25 minutes) or less.                                         | Requires **v1.12.0** or later if self-managing agents. Can be used to mitigate eventual consistency issues in AWS when using the `iam_user` auth type. |
| `TFC_VAULT_BACKED_AWS_VAULT_CONFIG`
`TFC_VAULT_BACKED_AWS_VAULT_CONFIG[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_VAULT_CONFIG`             | The name of the non-default Vault configuration for workspaces using [multiple Vault configurations](/terraform/cloud-docs/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). | Requires **v1.12.0** or later if self-managing agents. Will fall back to using the default Vault configuration if not provided.                        |

### Assumed Role Specific Environment Variables
These environment variables are only valid if the `TFC_VAULT_BACKED_AWS_AUTH_TYPE` is `assumed_role`.

#### Required Assumed Role Specific Environment Variables
| Variable                                                                                | Value                                 | Notes                                                                                |
|-------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `TFC_VAULT_BACKED_AWS_RUN_ROLE_ARN`
`TFC_VAULT_BACKED_AWS_RUN_ROLE_ARN[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_RUN_ROLE_ARN` | The ARN of the role to assume in AWS. | Requires **v1.8.0** or later if self-managing agents. Optional if `TFC_VAULT_BACKED_AWS_PLAN_ROLE_ARN` and `TFC_VAULT_BACKED_AWS_APPLY_ROLE_ARN` are both provided. These variables are described [below](#optional-assume-role-specific-environment-variables). |

#### Optional Assumed Role Specific Environment Variables
You may need to set these variables, depending on your use case.

| Variable                                                                                | Value                                                    | Notes                                                                                |
|-------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
| `TFC_VAULT_BACKED_AWS_PLAN_ROLE_ARN`
`TFC_VAULT_BACKED_AWS_PLAN_ROLE_ARN[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_PLAN_ROLE_ARN`    | The ARN of the role to use for the plan phase of a run.  | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_AWS_RUN_ROLE_ARN` if not provided. |
| `TFC_VAULT_BACKED_AWS_APPLY_ROLE_ARN`
`TFC_VAULT_BACKED_AWS_APPLY_ROLE_ARN[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_APPLY_ROLE_ARN` | The ARN of the role to use for the apply phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_AWS_RUN_ROLE_ARN` if not provided. |

## Configure Terraform Providers
The final step is to directly configure your AWS and Vault providers.

### Configure the AWS Provider
Ensure you pass a value for the `region` argument in your AWS provider configuration block or set the `AWS_REGION` variable in your workspace.

Ensure you are not using any of the arguments or methods mentioned in the [authentication and configuration](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration) section of the provider documentation. Otherwise, these settings may interfere with dynamic provider credentials.

### Configure the Vault Provider
If you were previously using the Vault provider to authenticate the AWS provider, remove any existing usage of the AWS secrets engine from your Terraform Code.
This includes the [`vault_aws_access_credentials`](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/aws_access_credentials) data source and any instances of [`vault_generic_secret`](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret) you previously used to generate AWS credentials.

### Specifying Multiple Configurations

~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog).

You can add additional variables to handle multiple distinct Vault-backed AWS setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`.

For more details, see [Specifying Multiple Configurations](/terraform/cloud-docs/workspaces/dynamic-provider-credentials/specifying-multiple-configurations).

#### Required Terraform Variable

To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks.

```hcl
variable "tfc_vault_backed_aws_dynamic_credentials" {
  description = "Object containing Vault-backed AWS dynamic credentials configuration"
  type = object({
    default = object({
      shared_credentials_file = string
    })
    aliases = map(object({
      shared_credentials_file = string
    }))
  })
}
```

#### Example Usage

```hcl
provider "aws" {
  shared_credentials_files = [var.tfc_vault_backed_aws_dynamic_credentials.default.shared_credentials_file]
}

provider "aws" {
  alias = "ALIAS1"
  shared_credentials_files = [var.tfc_vault_backed_aws_dynamic_credentials.aliases["ALIAS1"].shared_credentials_file]
}
```

page title  Vault Backed Dynamic Credentials with the AWS Provider   Workspaces   HCP Terraform description       Use OpenID Connect and Vault to get short term credentials for the AWS Terraform provider in   your HCP Terraform runs         Vault Backed Dynamic Credentials with the AWS Provider       Important    If you are self hosting  HCP Terraform agents   terraform cloud docs agents   ensure your agents use  v1 8 0   terraform cloud docs agents changelog 1 8 0 04 18 2023  or above  To use the latest dynamic credentials features   upgrade your agents to the latest version   terraform cloud docs agents changelog    You can use HCP Terraform s native OpenID Connect integration with Vault to use  Vault backed dynamic credentials   terraform cloud docs workspaces dynamic provider credentials vault backed  with the AWS provider in your HCP Terraform runs  Configuring the integration requires the following steps   1     Configure Vault Dynamic Provider Credentials   configure vault dynamic provider credentials     Set up a trust configuration between Vault and HCP Terraform  create Vault roles and policies for your HCP Terraform workspaces  and add environment variables to those workspaces  2     Configure the Vault AWS Secrets Engine   configure vault aws secrets engine     Set up the AWS secrets engine in your Vault instance  3     Configure HCP Terraform   configure hcp terraform     Add additional environment variables to the HCP Terraform workspaces where you want to use Vault Backed Dynamic Credentials  4     Configure Terraform Providers   configure terraform providers     Configure your Terraform providers to work with Vault backed dynamic credentials   Once you complete this setup  HCP Terraform automatically authenticates with AWS via Vault generated credentials during the plan and apply phase of each run  The AWS provider s authentication is only valid for the length of the plan or apply phase      Configure Vault Dynamic Provider Credentials You must first set up Vault dynamic provider credentials before you can use Vault backed dynamic credentials  This includes setting up the JWT auth backend in Vault  configuring trust between HCP Terraform and Vault  and populating the required environment variables in your HCP Terraform workspace    See the setup instructions for Vault dynamic provider credentials   terraform cloud docs workspaces dynamic provider credentials vault configuration      Configure Vault AWS Secrets Engine Follow the instructions in the Vault documentation for  setting up the AWS secrets engine in your Vault instance   vault docs secrets aws   You can also do this configuration through Terraform  Refer to our  example Terraform configuration  https   github com hashicorp terraform dynamic credentials setup examples tree main vault backed aws         Important    carefully consider the limitations and differences between each supported credential type in the AWS secrets engine  These limitations carry over to HCP Terraform s usage of these credentials for authenticating the AWS provider      Configure HCP Terraform Next  you need to set certain environment variables in your HCP Terraform workspace to authenticate HCP Terraform with AWS using Vault backed dynamic credentials  These variables are in addition to those you previously set while configuring  Vault dynamic provider credentials   configure vault dynamic provider credentials   You can add these as workspace variables or as a  variable set   terraform cloud docs workspaces variables managing variables variable sets   When you configure dynamic provider credentials with multiple provider configurations of the same type  use either a default variable or a tagged alias variable name for each provider configuration  Refer to  Specifying Multiple Configurations   specifying multiple configurations  for more details      Common Environment Variables The below variables apply to all AWS auth types        Required Common Environment Variables   Variable                                                                                Value                                                                                Notes                                                                                TFC VAULT BACKED AWS AUTH  br    TFC VAULT BACKED AWS AUTH  TAG   br     Default variable not supported                                     true                                                                                Requires   v1 8 0   or later if self managing agents  Must be present and set to  true   or HCP Terraform will not attempt to authenticate with AWS                                                                                TFC VAULT BACKED AWS AUTH TYPE  br    TFC VAULT BACKED AWS AUTH TYPE  TAG   br    TFC DEFAULT VAULT BACKED AWS AUTH TYPE                   Specifies the type of authentication to perform with AWS  Must be one of the following   iam user    assumed role   or  federation token     Requires   v1 8 0   or later if self managing agents                                                                                TFC VAULT BACKED AWS RUN VAULT ROLE  br    TFC VAULT BACKED AWS RUN VAULT ROLE  TAG   br    TFC DEFAULT VAULT BACKED AWS RUN VAULT ROLE    The role to use in Vault                                                                                Requires   v1 8 0   or later if self managing agents  Optional if  TFC VAULT BACKED AWS PLAN VAULT ROLE  and  TFC VAULT BACKED AWS APPLY VAULT ROLE  are both provided  These variables are described  below   optional common environment variables           Optional Common Environment Variables You may need to set these variables  depending on your use case     Variable                                                                                Value                                                                                Notes                                                                                TFC VAULT BACKED AWS MOUNT PATH  br    TFC VAULT BACKED AWS MOUNT PATH  TAG   br    TFC DEFAULT VAULT BACKED AWS MOUNT PATH                      The mount path of the AWS secrets engine in Vault                                                                                Requires   v1 8 0   or later if self managing agents  Defaults to  aws                                                                                TFC VAULT BACKED AWS PLAN VAULT ROLE  br    TFC VAULT BACKED AWS PLAN VAULT ROLE  TAG   br    TFC DEFAULT VAULT BACKED AWS PLAN VAULT ROLE       The Vault role to use the plan phase of a run                                                                                Requires   v1 8 0   or later if self managing agents  Will fall back to the value of  TFC VAULT BACKED AWS RUN VAULT ROLE  if not provided                  TFC VAULT BACKED AWS APPLY VAULT ROLE  br    TFC VAULT BACKED AWS APPLY VAULT ROLE  TAG   br    TFC DEFAULT VAULT BACKED AWS APPLY VAULT ROLE    The Vault role to use for the apply phase of a run                                                                                Requires   v1 8 0   or later if self managing agents  Will fall back to the value of  TFC VAULT BACKED AWS RUN VAULT ROLE  if not provided                  TFC VAULT BACKED AWS SLEEP SECONDS  br    TFC VAULT BACKED AWS SLEEP SECONDS  TAG   br    TFC DEFAULT VAULT BACKED AWS SLEEP SECONDS             The amount of time to wait  in seconds  after obtaining temporary credentials from Vault  e g    30  for 30 seconds  Must be 1500 seconds  25 minutes  or less                                            Requires   v1 12 0   or later if self managing agents  Can be used to mitigate eventual consistency issues in AWS when using the  iam user  auth type       TFC VAULT BACKED AWS VAULT CONFIG  br    TFC VAULT BACKED AWS VAULT CONFIG  TAG   br    TFC DEFAULT VAULT BACKED AWS VAULT CONFIG                The name of the non default Vault configuration for workspaces using  multiple Vault configurations   terraform cloud docs workspaces dynamic provider credentials specifying multiple configurations     Requires   v1 12 0   or later if self managing agents  Will fall back to using the default Vault configuration if not provided                                Assumed Role Specific Environment Variables These environment variables are only valid if the  TFC VAULT BACKED AWS AUTH TYPE  is  assumed role         Required Assumed Role Specific Environment Variables   Variable                                                                                Value                                   Notes                                                                                TFC VAULT BACKED AWS RUN ROLE ARN  br    TFC VAULT BACKED AWS RUN ROLE ARN  TAG   br    TFC DEFAULT VAULT BACKED AWS RUN ROLE ARN    The ARN of the role to assume in AWS    Requires   v1 8 0   or later if self managing agents  Optional if  TFC VAULT BACKED AWS PLAN ROLE ARN  and  TFC VAULT BACKED AWS APPLY ROLE ARN  are both provided  These variables are described  below   optional assume role specific environment variables           Optional Assumed Role Specific Environment Variables You may need to set these variables  depending on your use case     Variable                                                                                Value                                                      Notes                                                                                TFC VAULT BACKED AWS PLAN ROLE ARN  br    TFC VAULT BACKED AWS PLAN ROLE ARN  TAG   br    TFC DEFAULT VAULT BACKED AWS PLAN ROLE ARN       The ARN of the role to use for the plan phase of a run     Requires   v1 8 0   or later if self managing agents  Will fall back to the value of  TFC VAULT BACKED AWS RUN ROLE ARN  if not provided       TFC VAULT BACKED AWS APPLY ROLE ARN  br    TFC VAULT BACKED AWS APPLY ROLE ARN  TAG   br    TFC DEFAULT VAULT BACKED AWS APPLY ROLE ARN    The ARN of the role to use for the apply phase of a run    Requires   v1 8 0   or later if self managing agents  Will fall back to the value of  TFC VAULT BACKED AWS RUN ROLE ARN  if not provided        Configure Terraform Providers The final step is to directly configure your AWS and Vault providers       Configure the AWS Provider Ensure you pass a value for the  region  argument in your AWS provider configuration block or set the  AWS REGION  variable in your workspace   Ensure you are not using any of the arguments or methods mentioned in the  authentication and configuration  https   registry terraform io providers hashicorp aws latest docs authentication and configuration  section of the provider documentation  Otherwise  these settings may interfere with dynamic provider credentials       Configure the Vault Provider If you were previously using the Vault provider to authenticate the AWS provider  remove any existing usage of the AWS secrets engine from your Terraform Code  This includes the   vault aws access credentials   https   registry terraform io providers hashicorp vault latest docs data sources aws access credentials  data source and any instances of   vault generic secret   https   registry terraform io providers hashicorp vault latest docs data sources generic secret  you previously used to generate AWS credentials       Specifying Multiple Configurations       Important    If you are self hosting  HCP Terraform agents   terraform cloud docs agents   ensure your agents use  v1 12 0   terraform cloud docs agents changelog 1 12 0 07 26 2023  or above  To use the latest dynamic credentials features   upgrade your agents to the latest version   terraform cloud docs agents changelog    You can add additional variables to handle multiple distinct Vault backed AWS setups  enabling you to use multiple  provider aliases   terraform language providers configuration alias multiple provider configurations  within the same workspace  You can configure each set of credentials independently  or use default values by configuring the variables prefixed with  TFC DEFAULT     For more details  see  Specifying Multiple Configurations   terraform cloud docs workspaces dynamic provider credentials specifying multiple configurations         Required Terraform Variable  To use additional configurations  add the following code to your Terraform configuration  This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks      hcl variable  tfc vault backed aws dynamic credentials      description    Object containing Vault backed AWS dynamic credentials configuration    type   object       default   object         shared credentials file   string            aliases   map object         shared credentials file   string                          Example Usage     hcl provider  aws      shared credentials files    var tfc vault backed aws dynamic credentials default shared credentials file     provider  aws      alias    ALIAS1    shared credentials files    var tfc vault backed aws dynamic credentials aliases  ALIAS1   shared credentials file