Enable access to Azure file shares using OAuth over REST
Summary — Access Azure file shares using Microsoft Entra ID with Azure Files OAuth over REST
What this feature does
Enables admin-level read/write access to Azure file shares via OAuth 2.0 using Microsoft Entra ID (Azure AD) for REST API–based access.
Supports users, groups, first‑party services (Azure portal), third‑party apps, and tools (PowerShell, Azure CLI, AzCopy, Storage Explorer) that call file REST APIs.
Requires callers to explicitly indicate intent to use the privileged access via a request header or specific client/command parameter.
Important links
General identity-based SMB overview: Overview of Azure Files identity-based authentication for SMB access
REST API versioning: Versioning for Azure Storage
Applies to
Supported for specific Storage account types and redundancy options (see original table). SMB is supported in applicable SKUs. (Table retained in original article.)
Limitations
OAuth authorizing file data operations is supported only for REST API versions 2022-11-02 and later.
Support for FileService and FileShare management via REST is available with REST API versions 2024-11-04 and later.
Customer use cases
Application development & service integration: let apps/services access Azure Files via Microsoft Entra identities; eliminate distribution of account keys.
Managed identities: enable backup/restore/auditing services to access file share data using managed identities.
Storage account key replacement: replace shared key access with OAuth for improved security and auditing.
Privileges, permissions, and built‑in roles
Two new data actions required in RBAC roles:
Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action
Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action
Two new built-in roles:
Storage File Data Privileged Reader — includes readFileBackupSemantics/action and read access to files (bypasses file/directory NTFS ACLs).
Storage File Data Privileged Contributor — includes writeFileBackupSemantics/action plus read/write/delete/modify ACLs (bypasses file/directory NTFS ACLs).
These roles grant storage account–wide data privileges that bypass file/directory ACLs, but they only include data-plane permissions (not file share management actions).
RBAC scope nuance: in management (control) plane use "shares" in resource paths; in data plane use "fileshares". For RBAC assignments and data action strings use fileshares (example path in original article).
Wildcard scopes (e.g., Microsoft.Storage/storageAccounts/fileServices/*) inherit these extra privileges — explicit intent is required to use them and customers should avoid overly permissive wildcard RBAC.
Authorize access in application code
Azure Identity client libraries integrate with Storage SDKs (.NET, Java, Python, JS, Go) to simplify acquiring tokens and using TokenCredential with Share/File clients.
Example .NET (C#) shows using ClientSecretCredential and ShareClientOptions.ShareTokenIntent = Backup to set x-ms-file-intent=backup automatically. (Code included in original article.)
Authorize access using FileREST data plane API (Portal, PowerShell, CLI)
Azure portal:
Portal can use either Microsoft Entra account or storage account key. If you have role with Microsoft.Storage/storageAccounts/listkeys/action the portal uses the account key; otherwise it tries Microsoft Entra account.
Portal access via Microsoft Entra requires both file data permissions and an ARM role (for navigation) such as Reader scoped to the storage account or higher.
Portal indicates which authorization scheme is in use. See Choose how to authorize access to file data in the Azure portal.
PowerShell:
PowerShell extensions return an OAuth token when signed in with Microsoft Entra credentials; PowerShell uses it automatically for supported data operations.
The storage context with OAuth requires the explicit -EnableFileBackupRequestIntent parameter to indicate intent to use privileged access.
Supported only for file and directory operations and Get/Set permissions on shares; other operations still require account key or SAS.
Steps to authorize and perform operations (converted to a stepper for clarity):
Azure CLI:
Core az storage file/directory commands support Files OAuth over REST if called with --backup-intent or --enable-file-backup-request-intent and --auth-mode login.
Supported groups/commands: az storage file, az storage directory, az storage share list-handle, az storage share close-handle. Other operations require account key or SAS.
Steps to authorize and perform operations (stepper):
Prerequisites
Azure resource group and storage account.
Appropriate RBAC role assignments that include explicit permissions for data operations against file shares (including the new data actions when privileged access is needed).
See Permissions for calling data operations in the original article for details.
Install / tooling
PowerShell: Install latest Az.Storage module:
Azure CLI: install latest Azure CLI (see original article).
Additional notes
OAuth data-plane support requires callers to explicitly indicate backup/privileged intent (header, client option, or command parameter).
The feature provides storage account–wide privileged data access that bypasses file/directory ACLs — use with care and avoid wildcard RBAC assignments to prevent over-privileged access.
Related links
Choose how to authorize access to file data in the Azure portal
Last updated: 09/30/2025
(For full details, examples, and exact resource paths, see the original article.)
Was this helpful?