Dynamic Authentication with Azure using Federated Credentials and Claims Matching Expression

Avatar
Neha Bansal
  • Updated

Introduction:

Hashicorp has an official document which defines a basic process how to configure dynamic credentials with azure provider. We will get to know how we can utilise Claims matching expression (Preview) to configure single credentials for all the workspace or run phases.

Expected Outcome: Configure federated token for azure using Claim matching expression.

Prerequisites:

AzureRM provider:- 3.60.0 or later

Microsoft Entra ID provider:- 2.43.0 or later

If you are self-hosting HCP Terraform agents, ensure your agents use v1.12.0or above.

 

Use Case:

Enable dynamic Azure authentication via a single federated credential for:

  • All workspaces in a project

  • A specific run_phase (e.g., plan, apply)

Procedure: 

Create an App Registration and Service Principal, reference link:

1. Navigate to the Azure Active Directory overview within the Azure Portal 

2.Then select the App Registration blade. Click the New registration button at the top to add a new Application within Azure Active Directory. On this page, set the following values then press Create:

  • Name - this is a friendly identifier and can be anything (e.g. "Terraform")
  • Supported Account Types - this should be set to "Accounts in this organizational directory only (single-tenant)"
  • Redirect URI - you should choose "Web" for the URI type. the actual value can be left blank

Grant the application access to manage resources in azure subscription, reference link:

  1. Navigate to the Subscriptions blade within the Azure Portal, then select the Subscription you wish to use, then click Access Control (IAM), and finally Add > Add role assignment

  2. Specify a Role which grants the appropriate permissions needed for the Service Principal (for example, Contributor will grant Read/Write on all resources in the Subscription)

  3.  Search for and select the name of the Service Principal created in Azure Active Directory to assign it this role - then press Save.

Configure Microsoft Entra ID to trust a Generic User, reference link:

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.

    When subject identifier is static:

    You can choose Type as Explicit subject identifier and define it like below: 

    organization:<org-name>:project:<project-name>:workspace:<workspace-name>:run_phase:plan
     

 

Screenshot 2025-07-25 at 2.35.05 PM.png

 

When subject identifier is dynamic:

You can choose Type as Claims matching expression (Preview) and define an expression like below, it will use same credential for all workspaces present in Default Project and where run phase is plan:

  1. claims['sub'] matches 'organization:<org-name>:project:Default Project:workspace:*:run_phase:plan'

    Screenshot 2025-07-25 at 4.45.07 PM.png

Configure HCP Terraform,reference link:

  1. Below is the minimum required configuration:

terraform {
cloud {
organization = "<organisation_name>"
workspaces {
name = "<workspace_name"
}
}
required_providers {
azurerm = {
source = "hashicorp/azurerm"
}
}
}
 
provider "azurerm" {
features {}
subscription_id = "xxx"
use_oidc = true
tenant_id = "xxxx"
use_cli = false
}
 
resource "azurerm_resource_group" "example_token" {
name = "example-resource-group"
location = "East US"
tags = {
environment = "dev"
}
}
2. Define the following environment variables in each HCP Terraform workspace (or a Variable Set shared across workspaces):
 
TFC_DEFAULT_AZURE_RUN_CLIENT_ID: <client-id-of-subscription>
TFC_AZURE_PROVIDER_AUTH: true
 
3. Once configuration is complete, trigger a run from the workspace. Terraform Cloud will authenticate using the dynamic federated identity

 

Additional Information:

 

 

Articles in this section

See more

Related articles