Use Managed Identities with Azure Files (preview)

Here’s a concise summary of the article, preserving the original structure and key actions.

Overview

Purpose: Use managed identities (Microsoft Entra ID) to access SMB Azure file shares (preview) from Windows and Linux VMs, replacing storage account keys with identity-based OAuth authentication and RBAC.
Outcome: Create/enable a storage account with SMBOAuth, assign a managed identity to a VM, grant the managed identity the appropriate RBAC role, obtain OAuth tokens for the identity, and mount the Azure file share using Kerberos/CIFS with that identity.

Why use managed identities?

Managed identity types

System-assigned: one per resource, tied to resource lifecycle, not supported on Linux VMs.
User-assigned: standalone resource, reusable across VMs; required for Linux VMs. Windows VMs can use either.

Prerequisites

Azure subscription with permission to create storage accounts and assign roles (Microsoft.Authorization/roleAssignments/write).
Clients that will authenticate with a managed identity must NOT be domain-joined (for the managed identity flow described).

Prepare PowerShell (Windows admin tasks)

Set execution policy: Set-ExecutionPolicy Unrestricted -Scope CurrentUser
Install/Import PowerShellGet and Az module.
Connect: Connect-AzAccount -Environment AzureChinaCloud
Set subscription context: Set-AzContext -SubscriptionId "" (or use subscription name)

Configure storage account for SMBOAuth

SMBOAuth property must be enabled on the storage account that hosts the file share.
Create new storage account with SMBOAuth: New-AzStorageAccount -ResourceGroupName -Name -SkuName Standard_LRS -Location -EnableSmbOAuth $true
Or enable SMBOAuth on an existing account: Set-AzStorageAccount -ResourceGroupName -Name -EnableSmbOAuth $true
If blocked by policy, try: Set-AzStorageAccount -ResourceGroupName -Name -EnableSmbOAuth $true -AllowBlobPublicAccess $false
Create the SMB share: $storageAccount = Get-AzStorageAccount -ResourceGroupName -Name New-AzStorageShare -Name -Context $storageAccount.Context

Enable and assign managed identities

Create a Windows VM (Windows Server 2019+ for servers or any Windows client SKU).
Enable a managed identity on the VM (system-assigned or user-assigned). If both exist, Azure defaults to system-assigned; assign only one when possible.

Navigate to the storage account → Access Control (IAM) → Add role assignment.
Select role: Storage File Data SMB MI Admin.
Assign access to: Managed identity (for VM/Azure Arc) or User, group, or service principal (for application identity).
Select the managed identity (or application identity) as the member and complete Review + assign.

Linux-specific managed identity setup (high-level)

System-assigned managed identities are not supported on Linux VMs — use a user-assigned managed identity.
Create a user-assigned managed identity in the Azure portal, copy its Client ID.
Grant Storage File Data SMB MI Admin role to the user-assigned managed identity on the storage account.
Add the user-assigned managed identity to the VM (VM → Identity → User assigned → Add).

Prepare the client to authenticate (Windows)

On the VM/device with the managed identity, open PowerShell as administrator (PowerShell 5.1+ or 7+).
Install and import the AzFilesSMBMIClient PowerShell module: Install-Module AzFilesSMBMIClient Import-Module AzFilesSMBMIClient
Ensure execution policy allows running the module (Get-ExecutionPolicy -List; Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser if needed).

Copy storage account URI (include trailing slash): https://.file.core.chinacloudapi.cn/
Run: AzFilesSMBMIClient.exe refresh --uri https://.file.core.chinacloudapi.cn/
If VM has both user and system identities and you want to use a user-assigned identity, add --clientId .
The tool inserts an OAuth token into the Kerberos cache and will auto-refresh near expiration.

Prepare the client to authenticate (Linux)

Install azfilesauth package (commands vary by distro):
- Azure Linux 3.0: tdnf update; tdnf install azfilesauth
- Ubuntu 22.04 / 24.04: add Microsoft package repo (curl ... packages-microsoft-prod.deb; sudo dpkg -i ...; sudo apt-get update) then sudo apt-get install azfilesauth
Configure authentication: Option 1 — VM managed identity (recommended for user-assigned identity): sudo azfilesauthmanager set https://<storage_account>.file.core.chinacloudapi.cn --imds-client-id sudo azfilesauthmanager list Option 2 — Supply OAuth token directly: The token must have audience aud = https://storage.azure.com (no trailing slash). sudo azfilesauthmanager set https://.file.core.chinacloudapi.cn sudo azfilesauthmanager list

Mount the file share

Windows: access via UNC path in File Explorer: \.file.core.chinacloudapi.cn<file-share-name>
Linux (example mount command — replace credential-id from /etc/azfilesauth/config.yaml): sudo mount -t cifs //.file.core.chinacloudapi.cn/ /mnt/smb -o sec=krb5,cruid=,dir_mode=0755,file_mode=0755,serverino,nosharesock,mfsymlinks,actimeo=30
Verify: ls -la /mnt/smb

Refresh credentials on Linux

Start refresh service (requires user-assigned managed identity on the VM): sudo systemctl start azfilesauth
Tokens can be refreshed manually via azfilesauthmanager set or automated by the shared library APIs.

Troubleshooting (high-level)

Use SMB diagnostics steps available in the azure-files-samples SMBDiagnostics repo for deeper analysis.

Developer integration options

Windows (.NET): Microsoft.Azure.AzFilesSmbMI NuGet package (Install-Package Microsoft.Azure.AzFilesSmbMI -version 1.2.3168.94) — managed assembly integration.
Native integration: AzFilesSmbMIClient native DLL (Windows) for C/C++ (GitHub links and API header referenced).
Linux: Shared library installed with azfilesauth provides C-compatible APIs (extern_smb_set_credential_oauth_token, extern_smb_clear_credential, extern_smb_list_credential, extern_smb_version).

APIs (brief)

Native DLL (Windows) and shared library (Linux) expose methods to set/refresh/clear credentials and list credentials for a file endpoint. Returned values follow standard C conventions.