OIDC Authentication for the AzureRM Provider in Terraform

Overview

OpenID Connect (OIDC) provides a secure, short‑lived, and secretless authentication model for Terraform when deploying resources to Azure. Instead of storing service principal secrets or dynamically generating service principals, Terraform retrieves a runtime‑generated OIDC token from the execution environment. Azure validates this token and exchanges it for a temporary access token that Terraform uses for planning, applying, and managing resources.

This approach improves security, removes secret rotation overhead, reduces operational friction associated with dynamic service principals, and aligns with the principle of ephemeral, least‑privilege access.

---

How OIDC Authentication Works

1. Terraform Runs in a Trusted Environment

Terraform executes inside Terraform Enterprise (TFE). This environment acts as an OIDC identity provider, capable of minting signed OpenID Connect tokens for each run.

2. The Platform Generates an OIDC Token During the Run

When Terraform begins a plan or apply, the platform mints a short‑lived OIDC token and writes it to a temporary file on disk. TFE exposes the file path to Terraform through environment variables or through explicit file‑path wiring when dynamic credentials are enabled.

3. Azure Validates the Short‑Lived Token

The AzureRM provider submits the OIDC ID token to Azure Entra ID for exchange. Azure validates:

• The token signature and issuer (iss),
• The audience (aud),
• The subject (sub) aligned with the pipeline identity,
• The expiration (exp) and not‑before (nbf) claims, and
• The presence of a Federated Identity Credential on the target application.

If validation succeeds, Azure issues a short‑lived ARM access token.

4. Terraform Uses the Temporary ARM Access Token

Terraform performs all authenticated operations, including plan and apply, using the short‑lived ARM access token. The Azure SDK stores this token in memory, refreshes it only as needed, and never writes it to disk or Terraform state.

---

Our Setup

1. App registrations created through Secure

At https://secure.optum.com, create app registrations using the Secure‑imposed naming convention: ENV-OHEMR-EPIC-OIDC-001.

Create additional app registrations as needed based on workspace scale and Federated Identity Credential limits.

2. Federated Identity Credentials in Entra ID

Each Azure AD application used by Terraform must contain Federated Identity Credentials (FICs) that trust the TFE issuer and match the expected audience and subject.

You must create one credential per workspace and per action (plan and apply).
Each FIC represents one trust relationship. Because Azure supports a maximum of 20 FICs per app registration, each app registration supports a maximum of 10 workspaces.

When creating the FIC, configure the subject using the required schema:

organization:ORG:project:PROJECT:workspace:WORKSPACE_NAME:run_phase:PHASE

3. RBAC roles added to App Registrations

Each app registration must receive the appropriate RBAC roles to allow Terraform to provision infrastructure successfully. In addition to OHEMR subscription‑level permissions, app registrations must also receive RBAC roles for the enterprise‑managed Golden Image Gallery.

To assign subscription‑level roles, an individual with contributor or owner access to the subscription generated a script to apply the necessary roles to each app registration. The shell script provides an example.

For Golden Image Gallery access, request the required roles through a ServiceNow ticket assigned to the Public Cloud Developer Toolkit – ENG group.

4. Terraform provider configuration

Update the Terraform provider configuration to enable OIDC. The following example shows the dynamic credentials object and provider wiring:

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
    }))
  })
}

provider "azurerm" {
  features {}
  use_cli              = false
  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      = var.subscription_id
  tenant_id            = var.tenant_id
}

5. Workspace Modifications

To enable OIDC authentication in a workspace, configure the following TFE variables:

• TFC_AZURE_PROVIDER_AUTH = true
• TFC_AZURE_RUN_CLIENT_ID = Client ID GUID for the corresponding app registration

Ensure these variables are set on every workspace using OIDC‑based authentication.

Converting Pre-existing Workspaces

Workspaces were previously configured with dynamic service principals. To convert workspaces to OIDC from dynamic service principal authentication, please reference this guide.

Summary

OIDC provides a secure and efficient authentication mechanism for Terraform deployments to Azure. The architecture eliminates long‑lived secrets, reduces operational overhead, and enforces ephemeral access. App registrations require Federated Identity Credentials for each workspace and action, which results in a maximum of 10 workspaces per registration. Each app registration must also receive the appropriate RBAC roles for both subscription access and Golden Image Gallery integration.