Backend Type: azurerm

Stores the state as a Blob with the given Key within the Blob Container within the Blob Storage Account.

This backend supports state locking and consistency checking with Azure Blob Storage native capabilities.

Example Configurations

Access Key

This examples authenticates using the Access Key associated with the Storage Account:

Code Block
terraform {
  backend "azurerm" {
    storage_account_name = "abcd1234"
    container_name       = "tfstate"
    key                  = "prod.terraform.tfstate"

    access_key = "abcdefghijklmnopqrstuvwxyz0123456789..."
  }
}

We recommend using the environment variable ARM_ACCESS_KEY instead of storing sensitive information in your source code.

Shared Access Signature

This example authenticates using the SAS Token, which is a set of query parameters signed with the Access Key associated with the Storage Account:

Code Block
terraform {
  backend "azurerm" {
    storage_account_name = "tofu123abc"
    container_name       = "tofu-state"
    key                  = "prod.terraform.tfstate"

    sas_token = "sv=2024-11-04&ss=b&srt=sco&sp=rwdlaciytfx&se=2025-08-05T23:46:49Z&st=2025-08-05T15:31:49Z&spr=https&sig=abcdefg..."
  }
}

We recommend using the environment variable ARM_SAS_TOKEN instead of storing sensitive information in your source code.

Using Entra ID (Previously AzureAD)

The previous two authentication methods are specific to the storage account, and are not tied to any Service Principal. Every authentication method after those two can be modified to use Entra ID authentication rather than storage account-based authentication using the following parameter:

Code Block
...
use_azuread_auth = true
...

Using Entra ID, you can authenticate directly to the storage account or storage container using the service principal, which only requires the Storage Blob Data Contributor role. Without this parameter, OpenTofu will authenticate and try to obtain the Access Key for the Storage Account.

Note

The Owner role does not automatically grant access to the storage container through Entra ID; you need to explicitly provide a role for the storage account such as Storage Blob Data Contributor. However, having an Owner role does allow the principal to obtain the Access Key to the Storage Account.

Note

If you do not set use_azuread_auth = true, you must set the resource_group_name. A resource_group_name is not required when using Entra ID authentication.

CLI Authentication

This example authenticates the user with the azure profile set up by the az command.

Code Block
terraform {
  backend "azurerm" {
    resource_group_name  = "tofu-rg"
    storage_account_name = "tofu123abc"
    container_name       = "tofu-state"
    key                  = "prod.terraform.tfstate"
  }
}

Note

You can disable CLI Authentication by setting use_cli = false.

Certificate Authentication

This example authenticates the principal using a certificate authentication.

Code Block
terraform {
  backend "azurerm" {
    resource_group_name  = "tofu-rg"
    storage_account_name = "tofu123abc"
    container_name       = "tofu-state"
    key                  = "prod.terraform.tfstate"

    subscription_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    tenant_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    client_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    client_certificate_path = "cert.pfx"
  }
}

Basic Authentication

This example authenticates the principal using a basic secret.

Code Block
terraform {
  backend "azurerm" {
    resource_group_name  = "tofu-rg"
    storage_account_name = "tofu123abc"
    container_name       = "tofu-state"
    key                  = "prod.terraform.tfstate"

    subscription_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    tenant_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    client_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    client_secret = "hunter2"
  }
}

We recommend using the environment variable ARM_CLIENT_SECRET instead of storing sensitive information in your source code.

OpenID Connect Token

This example authenticates the principal using an OpenID Connect token for Federated Credentials.

Code Block
terraform {
  backend "azurerm" {
    resource_group_name  = "tofu-rg"
    storage_account_name = "tofu123abc"
    container_name       = "tofu-state"
    key                  = "prod.terraform.tfstate"

    subscription_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    tenant_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    client_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    use_oidc = true
    oidc_token_file_path = "token.env"
  }
}

GitHub Token Request

If you're using GitHub Actions, the environment variables ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN will provide you with a way to obtain the OIDC request token. OpenTofu is programmed to accept these environment variables; a workload with OpenTofu on GitHub Actions using OIDC will have this backend configuration to authenticate.

Code Block
terraform {
  backend "azurerm" {
    resource_group_name  = "tofu-rg"
    storage_account_name = "tofu123abc"
    container_name       = "tofu-state"
    key                  = "prod.terraform.tfstate"

    subscription_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    tenant_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    client_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    use_oidc = true
  }
}

Managed Service Identity

This example authenticates a managed service identity attached to the Azure VM or other compute.

Code Block
terraform {
  backend "azurerm" {
    resource_group_name  = "tofu-rg"
    storage_account_name = "tofu123abc"
    container_name       = "tofu-state"
    key                  = "prod.terraform.tfstate"

    subscription_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    tenant_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    use_msi = true
  }
}

AKS Workload Identity

This example authenticates using workload identity on Azure Kubernetes.

Code Block
terraform {
  backend "azurerm" {
    resource_group_name  = "tofu-rg"
    storage_account_name = "tofu123abc"
    container_name       = "tofu-state"
    key                  = "prod.terraform.tfstate"

    subscription_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    tenant_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    use_aks_workload_identity = true
  }
}

Data Source Configuration

Authentication for a data source works equivalently to the remote state authentication shown above, though with slightly different syntax. For example, this is how to obtain the remote state using CLI Authentication:

Code Block
data "terraform_remote_state" "foo" {
  backend = "azurerm"
  config = {
    resource_group_name  = "tofu-rg"
    storage_account_name = "tofu123abc"
    container_name       = "tofu-state"
    key                  = "prod.terraform.tfstate"
  }
}

Configuration Variables

Warning

We recommend using environment variables to supply credentials and other sensitive data. If you use -backend-config or hardcode these values directly in your configuration, OpenTofu will include these values in both the .terraform subdirectory and in plan files. Refer to Credentials and Sensitive Data for details.

The following configuration options are supported:

storage_account_name - (Required) The Name of the Storage Account.
container_name - (Required) The Name of the Storage Container within the Storage Account.
key - (Required) The name of the Blob used to retrieve/store OpenTofu's State file inside the Storage Container.
resource_group_name - (Required when not using Entra ID auth) The name of the Resource Group in which the Storage Account exists.
environment - (Optional) The Azure Cloud Configuration which should be used; set this for special compliance environments like Azure China or Azure US Government. This can also be sourced from the ARM_ENVIRONMENT environment variable. Possible values are public, china, and usgovernment. Defaults to public.
endpoint - (Deprecated in 1.1x.xx) The Custom Endpoint for Azure Resource Manager. This can also be sourced from the ARM_ENDPOINT environment variable.

Note
An endpoint should only be configured when using Azure Stack. This variable has no effect on operation from OpenTofu version 1.1x.xx onward.
timeout_seconds - (Optional) The number of seconds before a timeout is reached when attempting to initialize a client, retrieve a Blob or a Metadata from Azure. This can also be sourced from the ARM_TIMEOUT_SECONDS environment variable. Defaults to 300 (5 minutes). To disable the timeout, set this to 0.

Note
Setting timeout_seconds to 0 or a large value only disables/extends timeouts originating from OpenTofu. Requests will still time out based on your system's network configuration.
metadata_host - (Optional) The Hostname of the Azure Metadata Service (for example management.azure.com), used to obtain the Cloud Environment when using a Custom Azure Environment. This can also be sourced from the ARM_METADATA_HOSTNAME Environment Variable.

Note
We recommend metadata_host only be configured when using Azure Stack.
snapshot - (Optional) Should the Blob used to store the OpenTofu Statefile be snapshotted before use? Defaults to false. This value can also be sourced from the ARM_SNAPSHOT environment variable.

Note
Rather than using snapshots, we recommend enabling versioning and soft deletion on your Azure storage container.

When authenticating using the Managed Service Identity (MSI) - the following fields are also supported:

msi_endpoint - (Deprecated in 1.1x.xx) The path to a custom Managed Service Identity endpoint which is automatically determined if not specified. This can also be sourced from the ARM_MSI_ENDPOINT environment variable.

Note
We recommend using the MSI_ENDPOINT environment variable instead.
subscription_id - (Optional) The Subscription ID in which the Storage Account exists. This can also be sourced from the ARM_SUBSCRIPTION_ID environment variable.
tenant_id - (Optional) The Tenant ID in which the Subscription exists. This can also be sourced from the ARM_TENANT_ID environment variable.
use_msi - (Optional) Should Managed Service Identity authentication be used? This can also be sourced from the ARM_USE_MSI environment variable.

When authenticating using the AKS Workload Identity - the following fields are also supported:

subscription_id - (Optional) The Subscription ID in which the Storage Account exists. This can also be sourced from the ARM_SUBSCRIPTION_ID environment variable.
tenant_id - (Optional) The Tenant ID in which the Subscription exists. This can also be sourced from the ARM_TENANT_ID environment variable.
use_aks_workload_identity - (Optional) Set to true to if you want to use Azure's AKS Workload Identity to authenticate to Azure. This will only work if Workload Identity is set up on your Kubernetes workload. This can also be sourced from the ARM_USE_AKS_WORKLOAD_IDENTITY environment variable.

When authenticating using a Service Principal with OpenID Connect (OIDC) - the following fields are also supported:

client_id - (Optional) The Client ID of the Service Principal. This can also be sourced from the ARM_CLIENT_ID environment variable.
client_id_file_path - (Optional) The path to a file containing the Client ID of the Service Principal. This can also be sourced from the ARM_CLIENT_ID_FILE_PATH environment variable.
subscription_id - (Optional) The Subscription ID in which the Storage Account exists. This can also be sourced from the ARM_SUBSCRIPTION_ID environment variable.
tenant_id - (Optional) The Tenant ID in which the Subscription exists. This can also be sourced from the ARM_TENANT_ID environment variable.
oidc_request_url - (Optional) The URL for the OIDC provider from which to request an ID token. This can also be sourced from the ARM_OIDC_REQUEST_URL or ACTIONS_ID_TOKEN_REQUEST_URL environment variables.
oidc_request_token - (Optional) The bearer token for the request to the OIDC provider. This can also be sourced from the ARM_OIDC_REQUEST_TOKEN or ACTIONS_ID_TOKEN_REQUEST_TOKEN environment variables.
oidc_token - (Optional) The ID token when authenticating using OpenID Connect (OIDC). This can also be sourced from the ARM_OIDC_TOKEN environment variable.
oidc_token_file_path - (Optional) The path to a file containing an ID token when authenticating using OpenID Connect (OIDC). This can also be sourced from the ARM_OIDC_TOKEN_FILE_PATH environment variable.
use_oidc - (Optional) Should OIDC authentication be used? This can also be sourced from the ARM_USE_OIDC environment variable.

When authenticating using a SAS Token associated with the Storage Account - the following fields are also supported:

sas_token - (Optional) The SAS Token used to access the Blob Storage Account. This can also be sourced from the ARM_SAS_TOKEN environment variable.

When authenticating using the Storage Account's Access Key - the following fields are also supported:

access_key - (Optional) The Access Key used to access the Blob Storage Account. This can also be sourced from the ARM_ACCESS_KEY environment variable.

When authenticating using Entra ID Authentication - the following fields are also supported:

use_azuread_auth - (Optional) Whether to use Entra ID Authentication to access the Storage Account or Container. This can also be sourced from the ARM_USE_AZUREAD environment variable.

Note
When using Entra ID for Authentication to Storage you also need to ensure the Storage Blob Data Contributor role is assigned.

When authenticating using the command line - the following fields are also supported:

use_cli - (Optional) Whether to authenticate with the CLI. Defaults to true. This can also be sourced from the ARM_USE_CLI environment variable.

When authenticating using a Service Principal with a Client Certificate - the following fields are also supported:

client_id - (Optional) The Client ID of the Service Principal. This can also be sourced from the ARM_CLIENT_ID environment variable.
client_id_file_path - (Optional) The path to a file containing the Client ID of the Service Principal. This can also be sourced from the ARM_CLIENT_ID_FILE_PATH environment variable.
client_certificate - (Optional) A Base64-encoded PKCS#12 (PFX, not PEM) certificate used as the Client Certificate when authenticating as a Service Principal. The provided data string must encode both the public certificate and its private key. This can also be sourced from the ARM_CLIENT_CERTIFICATE environment variable.
client_certificate_password - (Optional) The password associated with the Client Certificate specified in client_certificate or client_certificate_path. This can also be sourced from the ARM_CLIENT_CERTIFICATE_PASSWORD environment variable.
client_certificate_path - (Optional) The path to the PKCS#12 PFX file used as the Client Certificate when authenticating as a Service Principal. The file must encode both the public certificate and its private key. This can also be sourced from the ARM_CLIENT_CERTIFICATE_PATH environment variable.
subscription_id - (Optional) The Subscription ID in which the Storage Account exists. This can also be sourced from the ARM_SUBSCRIPTION_ID environment variable.
tenant_id - (Optional) The Tenant ID in which the Subscription exists. This can also be sourced from the ARM_TENANT_ID environment variable.

When authenticating using a Service Principal with a Client Secret - the following fields are also supported:

client_id - (Optional) The Client ID of the Service Principal. This can also be sourced from the ARM_CLIENT_ID environment variable.
client_id_file_path - (Optional) The path to a file containing the Client ID of the Service Principal. This can also be sourced from the ARM_CLIENT_ID_FILE_PATH environment variable.
client_secret - (Optional) The Client Secret of the Service Principal. This can also be sourced from the ARM_CLIENT_SECRET environment variable.
client_secret_file_path - (Optional) The path to a file containing the Client Secret of the Service Principal. This can also be sourced from the ARM_CLIENT_SECRET_FILE_PATH environment variable.
subscription_id - (Optional) The Subscription ID in which the Storage Account exists. This can also be sourced from the ARM_SUBSCRIPTION_ID environment variable.
tenant_id - (Optional) The Tenant ID in which the Subscription exists. This can also be sourced from the ARM_TENANT_ID environment variable.

Backend Type: azurerm

Example Configurations​

Access Key​

Shared Access Signature​

Using Entra ID (Previously AzureAD)​

CLI Authentication​

Certificate Authentication​

Basic Authentication​

OpenID Connect Token​

GitHub Token Request​

Managed Service Identity​

AKS Workload Identity​

Data Source Configuration​

Configuration Variables​

Example Configurations

Access Key

Shared Access Signature

Using Entra ID (Previously AzureAD)

CLI Authentication

Certificate Authentication

Basic Authentication

OpenID Connect Token

GitHub Token Request

Managed Service Identity

AKS Workload Identity

Data Source Configuration

Configuration Variables