docs: backend azurerm auth permissions and entra id terminology (#903)

rcskosir · web-flow · commit 764084db1a28 · 2025-09-16T11:19:07.000-05:00
# Description This PR is to update the azurerm backend docs to show least privilege permissions and update the terminology from `Azure Active Directory` to `Microsoft Entra ID` on the next minor release. NOTE: I wrote the original content for this page before it was moved over to this new repo. I have re-written it twice in the past. Just giving you some context as to why I am updating it as you can't see my name in the git history. # Terraform Enterprise  - **App Deadline Date:**  - **Release Branch:**  - **Release Slack Channel:** #proj-tfe-releases ## Contributor Sign Off Congratulations, if your name is on this list that means you contributed to this release. You must sign off on your contributions by checking the box in front of your username. The number in front of your username is the number of pull requests authored by you that are going into this release. Please review the changelog entries for your contributions. Your changelog entries should be **feature-focused**, define the **what** and **why**, and include any necessary information for customers. Each changelog entry should make it clear why the customer should care about the change. More information on [how to write release notes can be found in confluence](https://hashicorp.atlassian.net/wiki/spaces/TFENG/pages/2369355816/How+to+Write+Release+Notes+for+TFE). Place your changelog entry into one of the following categories. - **Known Issues:** Issues present in this release. Ideally each issue will describe a workaround or provide information on which release resolves the issue. This category is typically added after a release is published. - **Breaking Changes:** Changes that will require a customer to take some action to modify their workflow, processes, monitoring, etc. - **Deprecations:** Things that will no longer be supported by the application. Can be operating systems going end-of-life, settings being removed, etc. - **Highlights:** Noteworthy changes that the customer should see when reading the release notes. These should be approved by your Product Manager and/or Engineering Manager. - **Features:** Newly added functionality to the application. - **Improvements:** Updates to existing components of the application. - **Bug Fixes:** Fixes to issues reported with the application. - **Security:** Security enhancements to the application and its infrastructure and patches for Common Vulnerabilities and Exposures (CVEs). When you are finished reviewing your contributions, check the box next to your name.  Please let @hashicorp/technical-program-mgmt know if you have any questions.
diff --git a/content/terraform/v1.13.x/docs/language/backend/azurerm.mdx b/content/terraform/v1.13.x/docs/language/backend/azurerm.mdx
@@ -68,10 +68,9 @@ These optional configuration options apply when [looking up the data plane URI](
 
 ### Storage Account Required Role Assignments
 
-The recommended data plane role assignments required for this method are either one of:
+The recommended data plane role assignment required for this method is:
 
-- `Storage Blob Data Owner` on the storage account container (Recommended)
-- `Storage Blob Data Contributor` on the storage account
+- `Storage Blob Data Contributor` on the storage account container (Recommended for least privilege)
 
 The recommended management plane role assignments required for this method are:
 
@@ -337,10 +336,9 @@ These optional configuration options apply when [looking up the data plane URI](
 
 ### Storage Account Required Role Assignments
 
-The recommended data plane role assignments required for this method are either one of:
+The recommended data plane role assignment required for this method is:
 
-- `Storage Blob Data Owner` on the storage account container (Recommended)
-- `Storage Blob Data Contributor` on the storage account
+- `Storage Blob Data Contributor` on the storage account container (Recommended for least privilege)
 
 The recommended management plane role assignments required for this method are:
 
diff --git a/content/terraform/v1.14.x (alpha)/docs/language/backend/azurerm.mdx b/content/terraform/v1.14.x (alpha)/docs/language/backend/azurerm.mdx
@@ -17,14 +17,14 @@ The `azurerm` backend needs to authenticate to the storage account data plane in
 
 The `azurerm` backend supports 5 methods to authenticate to the storage account data plane:
 
-- [Azure Active Directory](#azure-active-directory) **(Recommended)**
+- [Microsoft Entra ID](#microsoft-entra-id) **(Recommended)**
 - [SAS Token](#sas-token) *(Not recommended for new workloads)*
 - [Access Key](#access-key) *(Not recommended for new workloads)*
 - [Access Key Lookup](#access-key-lookup) *(Not recommended for new workloads)*
 
-### Azure Active Directory and Access Key Lookup Authentication Types
+### Microsoft Entra ID and Access Key Lookup Authentication Types
 
-There are 5 types of Azure Active Directory authentication supported, which apply to the Azure Active Directory and Access Key Lookup methods.
+There are 5 types of Microsoft Entra ID authentication supported, which apply to the Microsoft Entra ID and Access Key Lookup methods.
 
 - OpenID Connect / Workload identity federation **(Recommended)**
   - User Assigned Managed Identity with Federated Credentials **(Recommended)**
@@ -44,16 +44,16 @@ In most cases, you can infer the data plane URI from the `storage_account_name`
 
 If you are using the ['Azure DNS zone endpoints' feature](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-overview#azure-dns-zone-endpoints-preview), the backend will need to lookup the data plane URI from the management plane. This requires that you set the `lookup_blob_endpoint` configuration option to `true` and the `Reader` role assignment on the storage account.
 
-## Azure Active Directory
+## Microsoft Entra ID
 
-This method requires a valid Azure Active Directory principal and a predictable storage account data plane URI.
+This method requires a valid Microsoft Entra ID principal and a predictable storage account data plane URI.
 
 ### Required Configuration Options
 
 The following configuration options are always required for this method:
 
-- `use_azuread_auth` - Set to `true` to use Azure Active Directory authentication to the storage account data plane. This can also be set via the `ARM_USE_AZUREAD` environment variable.
-- `tenant_id` - The tenant ID of the Azure Active Directory principal is required to authenticate to the storage account data plane. If using Azure CLI, this can be inferred from the CLI session. This can also be set via the `ARM_TENANT_ID` environment variable.
+- `use_azuread_auth` - Set to `true` to use Microsoft Entra ID authentication to the storage account data plane. This can also be set via the `ARM_USE_AZUREAD` environment variable.
+- `tenant_id` - The tenant ID of the Microsoft Entra ID principal is required to authenticate to the storage account data plane. If using Azure CLI, this can be inferred from the CLI session. This can also be set via the `ARM_TENANT_ID` environment variable.
 - `storage_account_name` - The name of the storage account to write the state file blob to.
 - `container_name` - The name of the storage account container to write the state file blob to.
 - `key` - The name of the blob within the storage account container to write the state file to.
@@ -68,23 +68,22 @@ These optional configuration options apply when [looking up the data plane URI](
 
 ### Storage Account Required Role Assignments
 
-The recommended data plane role assignments required for this method are either one of:
+The recommended data plane role assignment required for this method is:
 
-- `Storage Blob Data Owner` on the storage account container (Recommended)
-- `Storage Blob Data Contributor` on the storage account
+- `Storage Blob Data Contributor` on the storage account container (Recommended for least privilege)
 
 The recommended management plane role assignments required for this method are:
 
 - `Reader` on the storage account *(Only required if `lookup_blob_endpoint` is set to `true`)*
 
-### Azure Active Directory with OpenID Connect / Workload identity federation
+### Microsoft Entra ID with OpenID Connect / Workload identity federation
 
 #### Required Configuration Options
 
 The following additional configuration options are always required for this sub-type:
 
 - `use_oidc` - Set to `true` to use OpenID Connect / Workload identity federation to authenticate to the storage account data plane. This can also be set via the `ARM_USE_OIDC` environment variable.
-- `client_id` - The client ID of the Azure Active Directory Service Principal / App Registration or User Assigned Managed Identity is required to authenticate to the storage account data plane. This can also be set via the `ARM_CLIENT_ID` environment variable.
+- `client_id` - The client ID of the Microsoft Entra ID Service Principal / App Registration or User Assigned Managed Identity is required to authenticate to the storage account data plane. This can also be set via the `ARM_CLIENT_ID` environment variable.
 
 #### Example Configuration for GitHub
 
@@ -123,7 +122,7 @@ terraform {
 }
 ```
 
-### Azure Active Directory with Compute Attached Managed Identity
+### Microsoft Entra ID with Compute Attached Managed Identity
 
 #### Required Configuration Options
 
@@ -153,7 +152,7 @@ terraform {
 }
 ```
 
-### Azure Active Directory with Azure CLI
+### Microsoft Entra ID with Azure CLI
 
 You must have a pre-authenticated Azure CLI session using any supported method.
 
@@ -178,7 +177,7 @@ terraform {
 }
 ```
 
-### Azure Active Directory with Client Secret
+### Microsoft Entra ID with Client Secret
 
 Terraform retains this method for backwards compatibility only, do not use it for any new workloads.
 
@@ -188,8 +187,8 @@ Terraform retains this method for backwards compatibility only, do not use it fo
 
 The following additional configuration options are always required for this sub-type:
 
-- `client_id` - The client ID of the Azure Active Directory Service Principal / App Registration is required to authenticate to the storage account data plane. This can also be set via the `ARM_CLIENT_ID` environment variable.
-- `client_secret` - The client secret of the Azure Active Directory Service Principal / App Registration is required to authenticate to the storage account data plane. This can also be set via the `ARM_CLIENT_SECRET` environment variable.
+- `client_id` - The client ID of the Microsoft Entra ID Service Principal / App Registration is required to authenticate to the storage account data plane. This can also be set via the `ARM_CLIENT_ID` environment variable.
+- `client_secret` - The client secret of the Microsoft Entra ID Service Principal / App Registration is required to authenticate to the storage account data plane. This can also be set via the `ARM_CLIENT_SECRET` environment variable.
 
 #### Example Configuration
 
@@ -207,7 +206,7 @@ terraform {
 }
 ```
 
-### Azure Active Directory with Client Certificate
+### Microsoft Entra ID with Client Certificate
 
 Terraform retains this method for backwards compatibility only, do not use it for any new workloads.
 
@@ -217,7 +216,7 @@ Terraform retains this method for backwards compatibility only, do not use it fo
 
 The following additional configuration options are always required for this sub-type:
 
-- `client_id` - The client ID of the Azure Active Directory Service Principal / App Registration is required to authenticate to the storage account data plane. This can also be set via the `ARM_CLIENT_ID` environment variable.
+- `client_id` - The client ID of the Microsoft Entra ID Service Principal / App Registration is required to authenticate to the storage account data plane. This can also be set via the `ARM_CLIENT_ID` environment variable.
 - `client_certificate_path` - The path to the client certificate bundle is required to authenticate to the storage account data plane. This can also be set via the `ARM_CLIENT_CERTIFICATE_PATH` environment variable.
 - `client_certificate_password` - The password for the client certificate bundle is required to authenticate to the storage account data plane. This can also be set via the `ARM_CLIENT_CERTIFICATE_PASSWORD` environment variable.
 
@@ -312,7 +311,7 @@ terraform {
 
 ## Access Key Lookup
 
-This method requires a valid Azure Active Directory principal and is a fallback for when Azure Active Directory authentication cannot be used on the storage account data plane.
+This method requires a valid Microsoft Entra ID principal and is a fallback for when Microsoft Entra ID authentication cannot be used on the storage account data plane.
 
 This method queries the management plane to get the storage account Access Key and then uses that Access Key to authenticate to the storage account data plane. It requires elevated permissions on the storage account.
 
@@ -322,7 +321,7 @@ Terraform retains this method for backwards compatibility, we do not recommend i
 
 The following configuration options are always required for this method:
 
-- `tenant_id` - The tenant ID of the Azure Active Directory principal is required to authenticate to the storage account management and data plane. If using Azure CLI, this can be inferred from the CLI session. This can also be set via the `ARM_TENANT_ID` environment variable.
+- `tenant_id` - The tenant ID of the Microsoft Entra ID principal is required to authenticate to the storage account management and data plane. If using Azure CLI, this can be inferred from the CLI session. This can also be set via the `ARM_TENANT_ID` environment variable.
 - `subscription_id` - The subscription ID of the storage account is required to query the management plane. If using Azure CLI, this can be inferred from the CLI session. This can also be set via the `ARM_SUBSCRIPTION_ID` environment variable.
 - `resource_group_name` - The resource group name of the storage account is required to query the management plane.
 - `storage_account_name` - The name of the storage account to write the state file blob to.
@@ -337,10 +336,9 @@ These optional configuration options apply when [looking up the data plane URI](
 
 ### Storage Account Required Role Assignments
 
-The recommended data plane role assignments required for this method are either one of:
+The recommended data plane role assignment required for this method is:
 
-- `Storage Blob Data Owner` on the storage account container (Recommended)
-- `Storage Blob Data Contributor` on the storage account
+- `Storage Blob Data Contributor` on the storage account container (Recommended for least privilege)
 
 The recommended management plane role assignments required for this method are:
 
@@ -356,7 +354,7 @@ OpenID Connect / Workload identity federation is the recommended method for this
 The following additional configuration options are always required for this sub-type:
 
 - `use_oidc` - Set to `true` to use OpenID Connect / Workload identity federation to authenticate to the storage account management and data plane. This can also be set via the `ARM_USE_OIDC` environment variable.
-- `client_id` - The client ID of the Azure Active Directory Service Principal / App Registration or User Assigned Managed Identity is required to authenticate to the storage account management and data plane. This can also be set via the `ARM_CLIENT_ID` environment variable.
+- `client_id` - The client ID of the Microsoft Entra ID Service Principal / App Registration or User Assigned Managed Identity is required to authenticate to the storage account management and data plane. This can also be set via the `ARM_CLIENT_ID` environment variable.
 
 #### Example Configuration for GitHub
 
@@ -493,7 +491,7 @@ terraform {
 
 To use the `terraform_remote_state` data source with the `azurerm` backend, you must use the exact same configuration as you would for the `backend` block in your configuration.
 
-For example to use [Direct Azure Active Directory authentication with OpenID Connect / Workload identity federation for GitHub](#azure-active-directory-with-openid-connect--workload-identity-federation) you would use the following configuration:
+For example to use [Direct Microsoft Entra ID authentication with OpenID Connect / Workload identity federation for GitHub](#microsoft-entra-id-with-openid-connect--workload-identity-federation) you would use the following configuration:
 
 ```hcl
 data "terraform_remote_state" "foo" {
@@ -534,7 +532,7 @@ The following configuration options are supported:
 
 * `tenant_id` - (Optional) The Tenant ID of the principal. This can also be sourced from the `ARM_TENANT_ID` environment variable.
 
-* `use_azuread_auth` - (Optional) Whether Azure Active Directory Authentication for storage account data plane authentication. This can also be sourced from the `ARM_USE_AZUREAD` environment variable.
+* `use_azuread_auth` - (Optional) Whether Microsoft Entra ID Authentication for storage account data plane authentication. This can also be sourced from the `ARM_USE_AZUREAD` environment variable.
 
 * `subscription_id` - (Optional) The Subscription ID of the storage account required for management plane authentication. This can also be sourced from the `ARM_SUBSCRIPTION_ID` environment variable.
 
@@ -548,7 +546,7 @@ The following configuration options are supported:
 
 * `use_oidc` - (Optional) Set to `true` to use OpenID Connect / Workload identity federation authentication for authentication to the storage account management and data plane. This can also be sourced from the `ARM_USE_OIDC` environment variable.
 
-* `client_id` - (Optional) The Client ID of the Azure Active Directory Principal required for some authentication sub-types. This can also be sourced from the `ARM_CLIENT_ID` environment variable.
+* `client_id` - (Optional) The Client ID of the Microsoft Entra ID Principal required for some authentication sub-types. This can also be sourced from the `ARM_CLIENT_ID` environment variable.
 
 * `ado_pipeline_service_connection_id` - (Optional) The Azure DevOps Pipeline Service Connection ID required for Open ID Connect / Workload identity federation authentication with Azure DevOps. This can also be sourced from the `ARM_ADO_PIPELINE_SERVICE_CONNECTION_ID` or `ARM_OIDC_AZURE_SERVICE_CONNECTION_ID` environment variables. The provider will look for values in this order and use the first it finds configured.
 
