Use dynamic credentials with the Azure provider

You can use HCP Terraform’s native OpenID Connect integration with Azure to get dynamic credentials for the AzureRM or Microsoft Entra ID providers in your HCP Terraform runs. Configuring the integration requires the following steps:

1. Configure Azure: Set up a trust configuration between Azure and HCP Terraform. Then, you must create Azure roles and policies for your HCP Terraform workspaces.
2. 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 Azure during each run. The Azure provider authentication is valid for the length of the plan or apply.

Configure Azure

You must enable and configure an application and service principal with accompanying federated credentials and permissions on Azure. These instructions use the Azure portal, but you can also use Terraform to configure Azure. Refer to our example Terraform configuration.

Create an Application and Service Principal

Follow the steps mentioned in the AzureRM provider docs here: Creating the Application and Service Principal.

As mentioned in the documentation it will be important to make note of the client_id for the application as you will use this later for authentication.

Grant the Application Access to Manage Resources in Your Azure Subscription

You must now give the created Application permission to modify resources within your Subscription.

Follow the steps mentioned in the AzureRM provider docs here: Granting the Application access to manage resources in your Azure Subscription.

Configure Microsoft Entra ID Application to Trust a Generic Issuer

Finally, you must create federated identity credentials which validate the contents of the token sent to Azure from HCP Terraform.

Follow the steps mentioned in the AzureRM provider docs here: Configure Azure Microsoft Entra ID Application to Trust a Generic Issuer.

The following information should be specified:

• Federated credential scenario: Must be set to Other issuer.
• Issuer: The address of HCP Terraform (e.g., https://app.terraform.io).
  • Important: make sure this value starts with https:// and does not have a trailing slash.
• Subject identifier: The subject identifier from HCP Terraform that this credential will match. This will be in the form organization:my-org-name:project:my-project-name:workspace:my-workspace-name:run_phase:plan where the run_phase can be one of plan or apply.
• Name: A name for the federated credential, such as tfc-plan-credential. Note that this cannot be changed later.

The following is optional, but may be desired:

• Audience: Enter the audience value that will be set when requesting the identity token. This will be api://AzureADTokenExchange by default. This should be set to the value of TFC_AZURE_WORKLOAD_IDENTITY_AUDIENCE if this has been configured.

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 Azure using dynamic credentials. You can set these as workspace variables. 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 for more details.

Required Environment Variables

Optional Environment Variables

You may need to set these variables, depending on your use case.

Configure the AzureRM or Microsoft Entra ID Provider

Make sure that you’re passing values for the subscription_id and tenant_id arguments into the provider configuration block or setting the ARM_SUBSCRIPTION_ID and ARM_TENANT_ID variables in your workspace.

Make sure that you’re not setting values for client_id, use_oidc, or oidc_token in the provider or setting any of ARM_CLIENT_ID, ARM_USE_OIDC, ARM_OIDC_TOKEN.

Specifying Multiple Configurations

You can add additional variables to handle multiple distinct Azure setups, enabling you to use multiple provider aliases 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.

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.

variable "tfc_azure_dynamic_credentials" {
  description = "Object containing Azure dynamic credentials configuration"
  type = object({
    default = object({
      client_id_file_path = string
      oidc_token_file_path = string
    })
    aliases = map(object({
      client_id_file_path = string
      oidc_token_file_path = string
    }))
  })
}

Example Usage

AzureRM Provider

provider "azurerm" {
  features {}
  // use_cli should be set to false to yield more accurate error messages on auth failure.
  use_cli              = false
  // use_oidc must be explicitly set to true when using multiple configurations.
  use_oidc             = true
  client_id_file_path  = var.tfc_azure_dynamic_credentials.default.client_id_file_path
  oidc_token_file_path = var.tfc_azure_dynamic_credentials.default.oidc_token_file_path
  subscription_id      = "00000000-0000-0000-0000-000000000000"
  tenant_id            = "10000000-0000-0000-0000-000000000000"
}

provider "azurerm" {
  features {}
  // use_cli should be set to false to yield more accurate error messages on auth failure.
  use_cli              = false
  // use_oidc must be explicitly set to true when using multiple configurations.
  use_oidc             = true
  alias                = "ALIAS1"
  client_id_file_path  = var.tfc_azure_dynamic_credentials.aliases["ALIAS1"].client_id_file_path
  oidc_token_file_path = var.tfc_azure_dynamic_credentials.aliases["ALIAS1"].oidc_token_file_path
  subscription_id      = "00000000-0000-0000-0000-000000000000"
  tenant_id            = "20000000-0000-0000-0000-000000000000"
}

Microsoft Entra ID Provider (formerly Azure AD)

provider "azuread" {
  features {}
  // use_cli should be set to false to yield more accurate error messages on auth failure.
  use_cli              = false
  // use_oidc must be explicitly set to true when using multiple configurations.
  use_oidc             = true
  client_id_file_path  = var.tfc_azure_dynamic_credentials.default.client_id_file_path
  oidc_token_file_path = var.tfc_azure_dynamic_credentials.default.oidc_token_file_path
  subscription_id      = "00000000-0000-0000-0000-000000000000"
  tenant_id            = "10000000-0000-0000-0000-000000000000"
}

provider "azuread" {
  features {}
  // use_cli should be set to false to yield more accurate error messages on auth failure.
  use_cli              = false
  // use_oidc must be explicitly set to true when using multiple configurations.
  use_oidc             = true
  alias                = "ALIAS1"
  client_id_file_path  = var.tfc_azure_dynamic_credentials.aliases["ALIAS1"].client_id_file_path
  oidc_token_file_path = var.tfc_azure_dynamic_credentials.aliases["ALIAS1"].oidc_token_file_path
  subscription_id      = "00000000-0000-0000-0000-000000000000"
  tenant_id            = "20000000-0000-0000-0000-000000000000"
}