Restrict the source of copy operations to a storage account

For security reasons, storage administrators might want to limit the environments from which data can be copied to storage accounts. Limiting the scope of permitted copy operations helps prevent the infiltration of unwanted data from untrusted tenants or virtual networks. This article shows you how

This article shows you how to limit the source accounts of copy operations to accounts within the same tenant as the destination account, or with private links to the same virtual network as the destination.

Important

Permitted scope for copy operations is currently in PREVIEW. See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

About Permitted scope for copy operations (preview)

The AllowedCopyScope property of a storage account is used to specify the environments from which data can be copied to the destination account. It is displayed in the Azure portal as configuration setting Permitted scope for copy operations (preview). The property is not set by default and does not return a value until you explicitly set it. It has three possible values:

(null) (default): Allow copying from any storage account to the destination account.
Microsoft Entra ID: Permits copying only from accounts within the same Microsoft Entra tenant as the destination account.
PrivateLink: Permits copying only from storage accounts that have private links to the same virtual network as the destination account.

The following table details operations that require the x-ms-copy-source request header that this setting applies to:

REST API	Permitted scope applies
Put Block From Url	Yes
Append Block From Url	Yes
Put Blob From Url	Yes
Put Page From Url	Yes
Copy Blob	Yes
Copy Blob From URL	Yes
Incremental Copy Blob	Yes
Put Range From Url	Yes
Copy File	Yes

Note

Storage clients such as AzCopy that rely on these APIs will be impacted by this setting. Please review the APIs associated with other features and services to ensure compatibility.

The error “The copy operation is not within the allowed copy scope” indicates that the attempted copy operation falls outside the permitted scope for your account. Should you encounter the error “This request is not authorized to perform this operation” please verify whether permitted scope or a related firewall rule is denying the request.

When the source of a copy request does not meet the requirements specified by this setting, the request fails with HTTP status code 403 (Forbidden).

The AllowedCopyScope property is supported for storage accounts that use the Azure Resource Manager deployment model only. For information about which storage accounts use the Azure Resource Manager deployment model, see Types of storage accounts.

Identify the source storage accounts of copy operations

Before changing the value of AllowedCopyScope for a storage account, identify users, applications or services that would be affected by the change. Depending on your findings, it might be necessary to adjust the setting to a scope that includes all of the desired copy sources, or to adjust the network or Microsoft Entra configuration for some of the source storage accounts.

Azure Storage logs capture details in Azure Monitor about requests made against the storage account, including the source and destination of copy operations. For more information, see Monitor Azure Storage. Enable and analyze the logs to identify copy operations that might be affected by changing AllowedCopyScope for the destination storage account.

Create a diagnostic setting in the Azure portal

To log Azure Storage data with Azure Monitor and analyze it with Azure Log Analytics, you must first create a diagnostic setting that indicates what types of requests and for which storage services you want to log data. After you configure logging for your storage account, the logs are available in the Log Analytics workspace. To create a workspace, see Create a Log Analytics workspace in the Azure portal.

To learn how to create a diagnostic setting in the Azure portal, see Create diagnostic settings in Azure Monitor.

For a reference of fields available in Azure Storage logs in Azure Monitor, see Resource logs.

Query logs for copy requests

Azure Storage logs include all requests to copy data to a storage account from another source. The log entries include the name of the destination storage account and the URI of the source object, along with information to help identify the client requesting the copy. For a complete reference of fields available in Azure Storage logs in Azure Monitor, see Resource logs.

To retrieve logs for requests to copy blobs made in the last seven days, follow these steps:

Navigate to your storage account in the Azure portal.
In the Monitoring section, select Logs.
Paste the following query into a new log query and run it. This query displays the source objects most frequently referenced in requests to copy data to the specified storage account. In the following example, replace the placeholder text <account-name> with your own storage account name.
```
StorageBlobLogs
| where OperationName has "CopyBlobSource" and TimeGenerated > ago(7d) and AccountName == "<account-name>"
| summarize count() by Uri, CallerIpAddress, UserAgentHeader
```

The results of the query should look similar to the following:

Open diagram: Screenshot showing how a Copy Blob Source log query might look.

The URI is the full path to the source object being copied, which includes the storage account name, the container name and the file name. From the list of URIs, determine whether the copy operations would be blocked if a specific AllowedCopyScope setting was applied.

You can also configure an alert rule based on this query to notify you about Copy Blob requests for the account. For more information, see Create, view, and manage log alerts using Azure Monitor.

Restrict the Permitted scope for copy operations (preview)

When you are confident that you can safely restrict the sources of copy requests to a specific scope, you can set the AllowedCopyScope property for the storage account to that scope.

Permissions for changing the Permitted scope for copy operations (preview)

To set the AllowedCopyScope property for the storage account, a user must have permissions to create and manage storage accounts. Azure role-based access control (Azure RBAC) roles that provide these permissions include the Microsoft.Storage/storageAccounts/write or Microsoft.Storage/storageAccounts/* action. Built-in roles with this action include:

The Azure Resource Manager Owner role
The Azure Resource Manager Contributor role
The Storage Account Contributor role

These roles do not provide access to data in a storage account via Microsoft Entra ID. However, they include the Microsoft.Storage/storageAccounts/listkeys/action, which grants access to the account access keys. With this permission, a user can use the account access keys to access all data in a storage account.

Role assignments must be scoped to the level of the storage account or higher to permit a user to restrict the scope of copy operations for the account. For more information about role scope, see Understand scope for Azure RBAC.

Be careful to restrict assignment of these roles only to those who require the ability to create a storage account or update its properties. Use the principle of least privilege to ensure that users have the fewest permissions that they need to accomplish their tasks. For more information about managing access with Azure RBAC, see Best practices for Azure RBAC.

Note

The classic subscription administrator roles Service Administrator and Co-Administrator include the equivalent of the Azure Resource Manager Owner role. The Owner role includes all actions, so a user with one of these administrative roles can also create and manage storage accounts. For more information, see Azure roles, Microsoft Entra roles, and classic subscription administrator roles.

Configure the Permitted scope for copy operations (preview)

Using an account that has the necessary permissions, configure the permitted scope for copy operations in the Azure portal, with PowerShell or using the Azure CLI.

To configure the permitted scope for copy operations for an existing storage account in the Azure portal, follow these steps:

Navigate to your storage account in the Azure portal.
Under Settings, select Configuration.
Set Permitted scope for copy operations (preview) to one of the following:
- From any storage account
- From storage accounts in the same Microsoft Entra tenant
- From storage accounts that have a private endpoint to the same virtual network
Open diagram: Screenshot showing how to disallow Shared Key access for a storage account.
Select Save.

To configure the permitted scope for copy operations for a new or existing storage account with PowerShell, install the Az.Storage PowerShell module, version 4.9.0 or later. Next, configure the AllowedCopyScope property for a new or existing storage account. The only supported values for the allowedCopyScope parameter are Microsoft Entra ID or PrivateLink. To set AllowedCopyScope to the default setting of From any storage account, you will need to change it in the Azure portal.

The following example shows how to set the AllowedCopyScope property for an existing storage account to allow copying data only from storage accounts within the same Microsoft Entra tenant. Replace the placeholder values in angle brackets (<>) with your own values:

Set-AzStorageAccount -ResourceGroupName <resource-group> `
    -AccountName <storage-account> `
    -allowedCopyScope "AAD"

The following example shows how to set the AllowedCopyScope property for an existing storage account to allow copying data only from storage accounts with private links to the same virtual network. Replace the placeholder values in angle brackets (<>) with your own values:

Set-AzStorageAccount -ResourceGroupName <resource-group> `
    -AccountName <storage-account> `
    -allowedCopyScope "PrivateLink"

To configure the permitted scope for copy operations for a new or existing storage account with the Azure CLI, perform the following steps:

Install the latest version of the Azure CLI. For more information, see Install the Azure CLI.
Install the Azure CLI storage preview extension using the command az extension add -n storage-preview.

Important

The Azure CLI storage preview extension adds support for features or arguments that are currently in PREVIEW.

See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
Use the allowed-copy-scope argument of the az storage account create or az storage account update command to configure the AllowedCopyScope property for a new or existing storage account. The only supported values for the argument are Microsoft Entra ID or PrivateLink. To set AllowedCopyScope to the default setting of From any storage account, you will need to change it in the Azure portal.

The following example shows how to configure the AllowedCopyScope property for an existing storage account to allow copying data to the destination account only from storage accounts within the same Microsoft Entra tenant. Replace the placeholder values in angle brackets (<>) with your own values:

az storage account update \
    --name <storage-account> \
    --resource-group <resource-group> \
    --allowed-copy-scope "AAD"

The following example shows how to configure the permitted scope of copy operations for an existing storage account to allow copying data to the destination account only from storage accounts with private links to the same virtual network. Replace the placeholder values in angle brackets (<>) with your own values:

az storage account update \
    --name <storage-account> \
    --resource-group <resource-group> \
    --allowed-copy-scope "PrivateLink"