Access Azure file shares using Microsoft Entra ID with Azure Files OAuth over REST

Azure Files OAuth over REST enables admin-level read and write access to Azure file shares for users and applications via the OAuth authentication protocol, using Microsoft Entra ID for REST API based access. Users, groups, first-party services such as Azure portal, and third-party services and applications using REST interfaces can now use OAuth authentication and authorization with a Microsoft Entra account to access data in Azure file shares. PowerShell cmdlets and Azure CLI commands that call REST APIs can also use OAuth to access Azure file shares.


You must call the REST API using an explicit header to indicate your intent to use the additional privilege. This is also true for Azure PowerShell and Azure CLI access.


Azure Files OAuth over REST only supports the FileREST Data APIs that support operations on files and directories. OAuth isn't supported on FilesREST data plane APIs that manage FileService and FileShare resources. These management APIs are called using the Storage Account Key or SAS token, and are exposed through the data plane for legacy reasons. We recommend using the control plane APIs (the storage resource provider - Microsoft.Storage) that support OAuth for all management activities related to FileService and FileShare resources.

Authorizing file data operations with Microsoft Entra ID is supported only for REST API versions 2022-11-02 and later. See Versioning for Azure Storage.

Customer use cases

OAuth authentication and authorization with Azure Files over the REST API interface can benefit customers in the following scenarios.

Application development and service integration

OAuth authentication and authorization enable developers to build applications that access Azure Storage REST APIs using user or application identities from Microsoft Entra ID.

Customers and partners can also enable first-party and third-party services to configure necessary access securely and transparently to a customer storage account.

DevOps tools such as the Azure portal, PowerShell, and CLI, AzCopy, and Storage Explorer can manage data using the user's identity, eliminating the need to manage or distribute storage access keys.

Managed identities

Customers with applications and managed identities that require access to file share data for backup, restore, or auditing purposes can benefit from OAuth authentication and authorization. Enforcing file- and directory-level permissions for each identity adds complexity and might not be compatible with certain workloads. For instance, customers might want to authorize a backup solution service to access Azure file shares with read-only access to all files with no regard to file-specific permissions.

Storage account key replacement

Microsoft Entra ID provides superior security and ease of use over shared key access. You can replace storage account key access with OAuth authentication and authorization to access Azure File shares with read-all/write-all privileges. This approach also offers better auditing and tracking specific user access.

Privileged access and access permissions for data operations

To use the Azure Files OAuth over REST feature, there are additional permissions that are required to be included in the RBAC role assigned to the user, group, or service principal. Two new data actions are introduced as part of this feature:



Users, groups, or service principals that call the REST API with OAuth must have either the readFileBackupSemantics or writeFileBackupSemantics action assigned to the role that allows data access. This is a requirement to use this feature. For details on the permissions required to call specific File service operations, see Permissions for calling data operations.

This feature provides two new built-in roles that include these new actions.

Role Data actions
Storage File Data Privileged Reader Microsoft.Storage/storageAccounts/fileServices/fileShares/files/read
Storage File Data Privileged Contributor Microsoft.Storage/storageAccounts/fileServices/fileShares/files/read

These new roles are similar to the existing Storage File Data SMB Share Reader and Storage File Data SMB Share Elevated Contributor built-in roles, but there are some differences:

  • The new roles contain the additional data actions that are required for OAuth access.

  • When the user, group, or service principal that's assigned Storage File Data Privileged Reader or Storage File Data Privileged Contributor roles calls the FilesREST Data API using OAuth, the user, group, or the service principal will have:

    • Storage File Data Privileged Reader: Full read access on all the data in the shares for all the configured storage accounts regardless of the file/directory level NTFS permissions that are set.
    • Storage File Data Privileged Contributor: Full read, write, modify ACLs, delete access on all the data in the shares for all the configured storage accounts regardless of the file/directory level NTFS permissions that are set.
  • With these special permissions and roles, the system will bypass any file/directory level permissions and allow access to file share data.

With the new roles and data actions, this feature will provide storage account-wide privileges that supersede all permissions on files and folders under all file shares in the storage account. However, the new roles only contain permissions to access data services. They don't include any permissions to access file share management services (actions on file shares). To use this feature, make sure you have permissions to access:

  • the storage account
  • file share management services
  • data services (the data in the file share)

There are many built-in roles that provide access to management services. You can also create custom roles with the appropriate permissions. To learn more about role-based access control, see Azure RBAC. For more information about how built-in roles are defined, see Understand role definitions.


Any wildcard use cases defined for the path Microsoft.Storage/storageAccounts/fileServices/* or higher scope will automatically inherit the additional access and permissions granted through this new data action. To prevent unintended or over-privileged access to Azure Files, we've implemented additional checks that require users and applications to explicitly indicate their intent to use the additional privilege. Furthermore, we strongly recommend that customers review their user RBAC role assignments and replace any wildcard usage with explicit permissions to ensure proper data access management.

Authorize access to file data in application code

The Azure Identity client library simplifies the process of getting an OAuth 2.0 access token for authorization with Microsoft Entra ID via the Azure SDK. The latest versions of the Azure Storage client libraries for .NET, Java, Python, JavaScript, and Go integrate with the Azure Identity libraries for each of those languages to provide a simple and secure means to acquire an access token for authorization of requests from the Azure file service.

An advantage of the Azure Identity client library is that it enables you to use the same code to acquire the access token whether your application is running in the development environment or in Azure. The Azure Identity client library returns an access token for a security principal. When your code is running in Azure, the security principal may be a managed identity for Azure resources, a service principal, or a user or group. In the development environment, the client library provides an access token for either a user or a service principal for testing purposes.

The access token returned by the Azure Identity client library is encapsulated in a token credential. You can then use the token credential to get a service client object to use in performing authorized operations against the Azure Files service.

Here's some sample code:

using Azure.Core;
using Azure.Identity;
using Azure.Storage.Files.Shares;
using Azure.Storage.Files.Shares.Models;

namespace FilesOAuthSample
    internal class Program
        static async Task Main(string[] args)
            string tenantId = "";
            string appId = "";
            string appSecret = "";
            string aadEndpoint = "";
            string accountUri = "";
            string connectionString = "";
            string shareName = "test-share";
            string directoryName = "testDirectory";
            string fileName = "testFile"; 

            ShareClient sharedKeyShareClient = new ShareClient(connectionString, shareName); 
            await sharedKeyShareClient.CreateIfNotExistsAsync(); 

            TokenCredential tokenCredential = new ClientSecretCredential(
                new TokenCredentialOptions()
                    AuthorityHost = new Uri(aadEndpoint)

            ShareClientOptions clientOptions = new ShareClientOptions(ShareClientOptions.ServiceVersion.V2023_05_03);

            // Set Allow Trailing Dot and Source Allow Trailing Dot.
            clientOptions.AllowTrailingDot = true;
            clientOptions.AllowSourceTrailingDot = true;

            // x-ms-file-intent=backup will automatically be applied to all APIs
            // where it is required in derived clients.

            clientOptions.ShareTokenIntent = ShareTokenIntent.Backup;
            ShareServiceClient shareServiceClient = new ShareServiceClient(
                new Uri(accountUri),

            ShareClient shareClient = shareServiceClient.GetShareClient(shareName);
            ShareDirectoryClient directoryClient = shareClient.GetDirectoryClient(directoryName);
            await directoryClient.CreateAsync();

            ShareFileClient fileClient = directoryClient.GetFileClient(fileName);
            await fileClient.CreateAsync(maxSize: 1024);
            await fileClient.GetPropertiesAsync();
            await sharedKeyShareClient.DeleteIfExistsAsync();

Authorize access using FileREST data plane API

You can also authorize access to file data using the Azure portal or Azure PowerShell.

The Azure portal can use either your Microsoft Entra account or the storage account access key to access file data in an Azure storage account. Which authorization scheme the Azure portal uses depends on the Azure roles that are assigned to you.

When you attempt to access file data, the Azure portal first checks whether you've been assigned an Azure role with Microsoft.Storage/storageAccounts/listkeys/action. If you've been assigned a role with this action, then the Azure portal uses the account key for accessing file data via shared key authorization. If you haven't been assigned a role with this action, then the Azure portal attempts to access data using your Microsoft Entra account.

To access file data from the Azure portal using your Microsoft Entra account, you need permissions to access file data, and you also need permissions to navigate through the storage account resources in the Azure portal. The built-in roles provided by Azure grant access to file resources, but they don't grant permissions to storage account resources. For this reason, access to the portal also requires assigning an Azure Resource Manager (ARM) role such as the Reader role, scoped to the level of the storage account or higher. The Reader role grants the most restrictive permissions, but any ARM role that grants access to storage account management resources is acceptable.

The Azure portal indicates which authorization scheme is in use when you navigate to a container. For more information about data access in the portal, see Choose how to authorize access to file data in the Azure portal.

See also