AKS CrashLoopBackOff, Pending Pods, and NotReady Nodes — The Real Fixes Engineers Use

Engineering WalkthroughRBACAzure FilesIdentity2026

How We Implemented RBAC
for Azure Files

Azure Files uses a two-layer permission model that most engineers implement only halfway. They assign the share-level RBAC role, mount the share, and declare it done — then wonder why some users can list files but not open them, or why an administrator cannot change ACLs. This walkthrough covers both layers, every role, the hybrid identity sync requirement, and every failure pattern we encountered along the way.

2 layers

Share-level RBAC controls whether a user can mount the share. Windows NTFS ACLs control what they can do inside it. Both must be configured — neither alone is sufficient.

4 roles

Four built-in RBAC roles for Azure Files: Reader, Contributor, Elevated Contributor, and Owner (privileged admin). Each maps to a specific access level over SMB.

30 min

Typical propagation delay after assigning a share-level RBAC role before it takes effect. Attempting to mount immediately after assignment will fail with access denied.

Groups only

The architecture decision that saved us from 200 individual RBAC assignments: assign roles to Entra ID groups, never to individual users. Groups are the unit of access management.

Table of Contents

1. 01The Two-Layer Permission Model: How Azure Files Access Control Works
2. 02The Four Built-In RBAC Roles and What They Actually Grant
3. 03Step 1 — Choose and Enable the Identity Source
4. 04Step 2 — Design the Group Structure Before Assigning Any Roles
5. 05Step 3 — Assign Share-Level RBAC Roles
6. 06Step 4 — Configure Directory and File-Level Windows ACLs
7. 07Step 5 — Verify Access and Test Every Role
8. 08Common Failure Patterns and How We Fixed Them
9. 09Auditing Who Has Access to What

When we migrated 47 file shares from on-premises Windows file servers to Azure Files, implementing access control was the step we most underestimated. The documentation is accurate but non-linear — the share-level RBAC guide, the directory-level ACL guide, and the identity source guide are three separate articles that each assume you have read the other two. This post is the unified walkthrough we wished existed: everything in sequence, with the failure patterns and fixes included.

Our environment used on-premises Active Directory Domain Services with Entra Connect Sync to Azure. All users were hybrid identities — they existed in both on-premises AD and Entra ID under different UPNs. If your environment is cloud-only (Entra ID only), the principles are the same, but you use Entra ID Kerberos instead of AD DS and skip the domain-join steps.

The Two-Layer Permission Model: How Azure Files Access Control Works

Azure Files access control operates at two independent layers, and both must be configured for access to work correctly. The most common implementation mistake is configuring one layer and assuming the other is inherited or defaulted. It is not.

Layer 1 — Share-level RBAC controls whether an authenticated user can mount the file share at all. This is enforced by Azure's control plane using Entra ID groups and Azure RBAC roles. A user without a share-level role assignment cannot mount the share — they receive an access denied at the SMB connection level, before the file system is even visible.

Layer 2 — Directory and file-level Windows ACLs (NTFS permissions) control what an authenticated user who has already mounted the share can do inside it — which folders they can list, which files they can open, which they can write to, and which they cannot see at all. These are standard Windows NTFS ACLs enforced by Azure Files' SMB implementation, identical in format to what you configure on an on-premises Windows file server.

The combination of these two layers is what makes Azure Files access control both powerful and confusing. A user needs to pass Layer 1 to reach Layer 2. A user who passes Layer 1 but has no Layer 2 ACL entries gets access determined by the share root's inherited ACLs. And the tool used to configure each layer is completely different.

Figure 1 — The two-layer Azure Files permission model: RBAC controls share mount access; Windows ACLs control file-level permissions

Layer 1 (RBAC) is evaluated at the Azure control plane when the user attempts to mount the share — it uses Entra ID groups and Azure RBAC roles. Layer 2 (NTFS ACLs) is evaluated by the Azure Files SMB server on every file operation inside the mounted share — it uses standard Windows ACL entries identical to on-premises NTFS. A user needs to pass Layer 1 before Layer 2 is ever evaluated. Both layers must be configured — neither has a permissive default that makes the other optional.

The Four Built-In RBAC Roles and What They Actually Grant

Azure Files provides four built-in RBAC roles scoped to the data plane. These roles are not the general storage account RBAC roles — they are specific to file share access over SMB. Understanding the distinction between these roles is essential before assigning any of them, because the names are similar but the access levels are significantly different.

A critical point that the documentation buries: share-level RBAC roles grant a ceiling, not a floor. A user with the Contributor role can write to the share root — but Windows NTFS ACLs at Layer 2 can still restrict them to read-only access on specific folders. The RBAC role and the NTFS ACL are evaluated independently, and the more restrictive of the two determines the effective access. You cannot use RBAC to grant access that a Deny ACL blocks. You cannot use a Deny ACL to block access if no share-level RBAC role is assigned — the user simply cannot mount the share.

RBAC Role	Share Mount	Read Files	Write / Modify Files	Change ACLs / Ownership	Use For
Storage File Data SMB Share Reader	Yes	Yes (subject to ACLs)	No	No	Read-only users: report consumers, auditors, service accounts that only read
Storage File Data SMB Share Contributor	Yes	Yes (subject to ACLs)	Yes (subject to ACLs)	No	Most end users: the standard role for users who need to read and write files
Storage File Data SMB Share Elevated Contributor	Yes	Yes (subject to ACLs)	Yes (subject to ACLs)	Yes — can modify ACLs on files and directories they own	Department administrators who manage their own folder permissions without needing full admin
Storage File Data SMB Share Owner (privileged)	Yes	Yes	Yes	Yes — full ACL control, equivalent to storage account key access over SMB	Storage administrators configuring initial ACLs. Assign this temporarily then revoke. Never as a permanent standing assignment.

Owner Role Warning

The Storage File Data SMB Share Owner role grants admin access equivalent to using the storage account key over SMB. It overrides Windows ACLs and allows the holder to read any file, modify any ACL, and take ownership of any object in the share. Assign this role temporarily when configuring ACLs, then revoke it. Never leave it as a standing assignment for any user account. Use Elevated Contributor for permanent department administrators.

Figure 2 — Azure Files RBAC role hierarchy: each role is a superset of the one below it

Each role is a superset of the one below it. Reader is the minimum for any interactive user. Contributor is the correct role for most end users. Elevated Contributor should be used sparingly for department admins. Owner should only be assigned temporarily to configure ACLs, then immediately revoked. NTFS ACLs (Layer 2) can only restrict access within the RBAC ceiling — they cannot grant access above it.

Step 1Choose and Enable the Identity SourceIdentity · Prerequisites

Before assigning any RBAC roles, you must configure an identity source on the storage account. The identity source determines how Kerberos tickets are issued when users authenticate to the file share over SMB. Without an identity source configured, the file share falls back to storage account key authentication only — which provides no per-user access control and no audit trail.

Choose one identity source per storage account — you cannot configure both AD DS and Entra ID Kerberos simultaneously. Our environment used AD DS because we already had on-premises domain controllers and all our users were hybrid identities. If you are building a new cloud-native environment with no on-premises AD, choose Entra ID Kerberos.

Identity Source	Requires	Best For	What We Chose
AD DS (on-premises)	On-prem domain controller. Storage account domain-joined to AD via AzFilesHybrid. Users/groups synced to Entra ID for RBAC.	Hybrid environments with existing AD infrastructure and domain-joined Windows clients	Yes — matched our existing environment
Entra ID Kerberos	Entra ID tenant. No on-prem DC required. Cloud-only or hybrid identities both work.	Cloud-native environments. AVD deployments. No on-prem DC dependency.	N/A for our deployment
Azure AD DS	Azure AD Domain Services managed domain (additional cost and complexity)	Legacy scenarios needing managed domain without on-prem investment	N/A — we already had AD DS

1a

Install AzFilesHybrid PowerShell Module (AD DS path)

Download and import the AzFilesHybrid module from the Microsoft GitHub repository. This module contains the Join-AzStorageAccountForAuth cmdlet that domain-joins your storage account to on-premises AD DS — creating a computer account in Active Directory that the storage account uses as its Kerberos service principal.

1b

Domain-Join the Storage Account to AD DS

Run Join-AzStorageAccountForAuth from a domain-joined Windows machine with Active Directory RSAT tools installed. This creates a computer account (or service logon account) in your AD that represents the storage account's identity. The password on this AD object must be updated every 30 days — set a calendar reminder or automate with a scheduled task.

1c

Enable Entra ID Kerberos (Entra ID Kerberos path)

For cloud-native environments without AD DS, enable Entra ID Kerberos directly in the Azure Portal: Storage account → Data storage → Classic file shares → Identity-based access → Set up (under Microsoft Entra Kerberos). No AzFilesHybrid module needed. Kerberos tickets are issued directly by Entra ID with AES-256 encryption.

1d

Verify Identity Source is Active

After configuration, confirm the identity source is active: az storage account show --name stfiles001 --resource-group rg-files-prod --query "azureFilesIdentityBasedAuthentication" -o table. The output should show your configured identity source as Active. If it shows Disabled or None, the configuration did not complete correctly.

PowerShell — Domain-join storage account to AD DS using AzFilesHybrid# Run from a domain-joined machine with AD RSAT tools and storage account Owner role # Install AzFilesHybrid module (one-time) Install-Module -Name AzFilesHybrid -Force Import-Module AzFilesHybrid # Sign in to Azure Connect-AzAccount # Set variables $SubscriptionId = "<your-subscription-id>" $ResourceGroupName = "rg-files-prod" $StorageAccountName = "stfiles001" # Select subscription Select-AzSubscription -SubscriptionId $SubscriptionId # Join the storage account to AD DS # This creates a computer account in your AD under the specified OU Join-AzStorageAccountForAuth ` -ResourceGroupName $ResourceGroupName ` -StorageAccountName $StorageAccountName ` -DomainAccountType "ComputerAccount" ` -OrganizationalUnitDistinguishedName "OU=AzureStorageAccounts,DC=contoso,DC=com" ` -EncryptionType "AES256" # Verify the join succeeded Debug-AzStorageAccountAuth ` -StorageAccountName $StorageAccountName ` -ResourceGroupName $ResourceGroupName ` -Verbose

Azure CLI — Enable Entra ID Kerberos (cloud-native environments)# Enable Entra ID Kerberos authentication on the storage account az storage account update \ --name stfiles001 \ --resource-group rg-files-prod \ --enable-files-aadkerb true # Verify the configuration az storage account show \ --name stfiles001 \ --resource-group rg-files-prod \ --query "azureFilesIdentityBasedAuthentication" -o table

Step 2Design the Group Structure Before Assigning Any RolesArchitecture · Access Design

This is the step most implementations skip, and it is the reason access management becomes unmanageable six months after go-live. If you assign RBAC roles to individual users, you end up with hundreds of individual role assignments that cannot be audited, bulk-modified, or delegated. The correct pattern is to assign RBAC roles exclusively to Entra ID groups, and manage access by managing group membership.

Our naming convention: We created one Entra ID group per share per access level. For a share called hr-shared, we created three groups: AzFiles-hr-shared-Read, AzFiles-hr-shared-Contribute, and AzFiles-hr-shared-Admin. Department managers own their respective Contribute and Read groups and add or remove users directly in Entra ID. The RBAC assignments on the share never change after initial setup — only group membership changes when access changes.

Figure 3 — Group-based access model: Entra ID groups map to RBAC roles; membership changes drive access changes

RBAC role assignments are static and assigned once to groups at share scope. Access changes happen by modifying group membership in Entra ID — which department managers can do themselves without touching Azure RBAC. This model scales to hundreds of users across dozens of shares without creating hundreds of individual RBAC assignments to track and audit.

Azure CLI — Create Entra ID groups for a file share access model# Create the three groups for hr-shared (repeat for each file share) az ad group create \ --display-name "AzFiles-hr-shared-Read" \ --mail-nickname "AzFiles-hr-shared-Read" \ --description "Read-only access to the hr-shared Azure file share" az ad group create \ --display-name "AzFiles-hr-shared-Contribute" \ --mail-nickname "AzFiles-hr-shared-Contribute" \ --description "Read-write access to the hr-shared Azure file share" az ad group create \ --display-name "AzFiles-hr-shared-Admin" \ --mail-nickname "AzFiles-hr-shared-Admin" \ --description "Elevated contributor access to hr-shared - for HR dept admin only" # Get the Object IDs for use in RBAC assignments az ad group list --display-name "AzFiles-hr-shared-Read" --query "[].id" -o tsv az ad group list --display-name "AzFiles-hr-shared-Contribute" --query "[].id" -o tsv az ad group list --display-name "AzFiles-hr-shared-Admin" --query "[].id" -o tsv

Step 3Assign Share-Level RBAC RolesRBAC · Azure CLI / Portal

Share-level RBAC role assignments must be scoped to the individual file share resource, not the storage account. This is one of the most important scoping decisions in the implementation. A role assigned at the storage account scope grants the same access level to every file share in that account — which is almost never what you want for a multi-share storage account used by different departments. Assign at the file share scope to achieve per-share access control.

After making a role assignment, wait at least 30 minutes before attempting to mount the share with the affected identity. Share-level RBAC propagation can take up to 30 minutes, and attempting to connect immediately after assignment will result in an access denied that looks like a configuration error but is simply a propagation delay.

Azure CLI — Assign RBAC roles at file share scope (not storage account scope)# Get the resource ID of the specific file share SHARE_ID=$(az storage share-rm show \ --storage-account stfiles001 \ --resource-group rg-files-prod \ --name hr-shared \ --query id -o tsv) echo "File share resource ID: $SHARE_ID" # Get group Object IDs READ_GROUP=$(az ad group list \ --display-name "AzFiles-hr-shared-Read" --query "[].id" -o tsv) CONTRIBUTE_GROUP=$(az ad group list \ --display-name "AzFiles-hr-shared-Contribute" --query "[].id" -o tsv) ADMIN_GROUP=$(az ad group list \ --display-name "AzFiles-hr-shared-Admin" --query "[].id" -o tsv) # Assign Reader role to the Read group — at SHARE scope az role assignment create \ --assignee-object-id $READ_GROUP \ --assignee-principal-type Group \ --role "Storage File Data SMB Share Reader" \ --scope $SHARE_ID # Assign Contributor role to the Contribute group — at SHARE scope az role assignment create \ --assignee-object-id $CONTRIBUTE_GROUP \ --assignee-principal-type Group \ --role "Storage File Data SMB Share Contributor" \ --scope $SHARE_ID # Assign Elevated Contributor to the Admin group — at SHARE scope az role assignment create \ --assignee-object-id $ADMIN_GROUP \ --assignee-principal-type Group \ --role "Storage File Data SMB Share Elevated Contributor" \ --scope $SHARE_ID # Verify assignments az role assignment list --scope $SHARE_ID \ --query "[].{Role:roleDefinitionName,Assignee:principalName}" -o table

Scope at the File Share, Not the Storage Account

Always scope role assignments to the individual file share resource ID, not the storage account resource ID. The storage account ID looks like: /subscriptions/.../storageAccounts/stfiles001. The file share ID looks like: /subscriptions/.../storageAccounts/stfiles001/fileServices/default/shares/hr-shared. Assigning at the storage account scope grants access to all shares. Assigning at the file share scope grants access to only that share. Use the az storage share-rm show --query id command to get the correct share-level resource ID.

Step 4Configure Directory and File-Level Windows ACLsNTFS ACLs · icacls · Layer 2

With share-level RBAC propagated (wait 30 minutes after Step 3), configure the Windows NTFS ACLs that control per-folder and per-file access. This is Layer 2 of the permission model. ACLs are configured by mounting the share using an account with the Storage File Data SMB Share Owner role (temporarily assigned for this purpose), then using icacls or Windows File Explorer to set permissions.

The most critical instruction in this entire guide: Set the ACLs on the root directory of the share before copying any data in, or before expecting end users to connect. Changing root-level ACLs after a large file migration triggers recursive ACL propagation that can take hours on a multi-million file share and blocks all user access during propagation. Configure the ACL structure first on an empty share, verify it is correct, then populate data.

4a

Temporarily Assign Owner Role to the Admin Account

The account that will configure ACLs needs the Storage File Data SMB Share Owner role on the share. Assign it temporarily before starting, and revoke it immediately after the ACL configuration is complete. Run this from the Azure CLI or Portal and wait 30 minutes for propagation.

4b

Mount the Share from a Domain-Joined Machine

On a domain-joined Windows machine, mount the share using net use. Do not use PowerShell New-PSDrive for this — net use creates the correct SMB mount that supports ACL configuration. The machine must have network connectivity to an on-premises domain controller (for AD DS authentication) or be able to reach Entra ID (for Entra ID Kerberos).

4c

Set Root Directory ACLs Using icacls

Set the root directory ACLs first. The root ACL establishes inheritance for all child objects. Use icacls to grant permissions to the groups, not to individual users. Inheritance flags are critical: (OI)(CI) means the permission applies to the folder itself, all subfolders, and all files (Object Inherit + Container Inherit).

4d

Verify ACLs Then Revoke the Owner Role

After setting and verifying ACLs, immediately revoke the Storage File Data SMB Share Owner role from the admin account. The role has been used for its temporary purpose. Leaving it assigned permanently is a standing privilege escalation risk.

Windows CMD — Mount the share and configure ACLs with icaclsREM Step 4a: Mount the share using the domain identity (no password needed with Kerberos SSO) net use Z: \\stfiles001.file.core.windows.net\hr-shared REM Step 4b: View current ACLs on the root icacls Z:\ REM Step 4c: Set root directory ACLs REM (OI)(CI) = Object Inherit + Container Inherit = applies to folder, subfolders, and files REM (F) = Full Control (M) = Modify (RX) = Read & Execute (R) = Read REM Remove all inherited ACLs first (clean slate on root) icacls Z:\ /inheritance:r REM Grant the Admin group Full Control on the share root icacls Z:\ /grant "CONTOSO\AzFiles-hr-shared-Admin:(OI)(CI)(F)" REM Grant the Contribute group Modify access on the share root icacls Z:\ /grant "CONTOSO\AzFiles-hr-shared-Contribute:(OI)(CI)(M)" REM Grant the Read group Read & Execute access on the share root icacls Z:\ /grant "CONTOSO\AzFiles-hr-shared-Read:(OI)(CI)(RX)" REM Create a subfolder with more restrictive access (payroll - only Contribute group, not Read) mkdir Z:\payroll icacls Z:\payroll /inheritance:r icacls Z:\payroll /grant "CONTOSO\AzFiles-hr-shared-Admin:(OI)(CI)(F)" icacls Z:\payroll /grant "CONTOSO\AzFiles-hr-shared-Contribute:(OI)(CI)(M)" REM Note: Read group is NOT added to payroll - they will get Access Denied when trying to open it REM Verify the ACLs look correct icacls Z:\ icacls Z:\payroll REM Unmount when done net use Z: /delete

Step 5Verify Access and Test Every RoleTesting · Validation

Before informing users that the share is ready, systematically test each role with a real account that has only that role assignment. Do not test with the Owner role account that set up the ACLs — it bypasses ACL checks and will always show full access regardless of what normal users will see. Use one test account per role level to exercise the actual access path.

Test Account	Group Membership	Expected: Share Root	Expected: /payroll	Expected: Cannot Do
test-reader@contoso.com	AzFiles-hr-shared-Read	Can list and open files	Access Denied when opening folder	Cannot create, modify, or delete any file
test-contributor@contoso.com	AzFiles-hr-shared-Contribute	Can create, modify, delete files	Can create, modify, delete files in /payroll	Cannot change ACLs on any file or folder
test-admin@contoso.com	AzFiles-hr-shared-Admin	Full control including ACL changes	Full control including ACL changes	Cannot access files in other shares (verify scope isolation)

PowerShell — Test share access from each role account# Test mount (run as each test account, on a domain-joined machine) $SharePath = "\\stfiles001.file.core.windows.net\hr-shared" # Test 1: Can the account mount the share? net use T: $SharePath if ($?) { Write-Host "PASS: Share mounted" } else { Write-Host "FAIL: Cannot mount share" } # Test 2: Can the account list the root? try { Get-ChildItem T:\ | Out-Null; Write-Host "PASS: Can list root" } catch { Write-Host "FAIL: Cannot list root - $_" } # Test 3: Can the account read a file? try { Get-Content "T:\test-file.txt" | Out-Null; Write-Host "PASS: Can read file" } catch { Write-Host "FAIL: Cannot read file - $_" } # Test 4: Can the account write a file? (Should FAIL for Reader group) try { "test" | Out-File "T:\write-test.txt"; Write-Host "PASS/CONCERN: Can write file" } catch { Write-Host "EXPECTED FAIL for Reader: Cannot write - $_" } # Test 5: Can the account access /payroll? (Should FAIL for Read group) try { Get-ChildItem "T:\payroll" | Out-Null; Write-Host "CONCERN: Can access payroll" } catch { Write-Host "EXPECTED FAIL for Read group: Access denied to payroll - $_" } # Unmount net use T: /delete

Common Failure Patterns and How We Fixed Them

These are the failure patterns we encountered during our 47-share implementation. Each one cost us time we would not have lost if we had known about it in advance.

What Actually Went Wrong (and the Fix)

1Access denied immediately after RBAC assignment. We assigned the RBAC role and immediately tried to mount. Access was denied. Fix: wait 30 minutes. Share-level RBAC propagation can take up to 30 minutes. This is not negotiable and cannot be forced. We added a 30-minute wait step to our automation runbook.

2Non-synced users blocked by RBAC even though their AD group had access. Several users existed in on-premises AD but had not been synced to Entra ID via Connect Sync. Because share-level RBAC requires Entra ID identities, these users could not mount the share despite being in the correct AD group. Fix: sync users to Entra ID, or use the Default Share-Level Permission option (which grants all authenticated users the same level) if granular per-group RBAC is not required for all users.

3icacls applying to the wrong identity format. When running icacls with Entra ID Kerberos (not AD DS), the group name format is different — it uses the Entra ID group name prefixed with the tenant, not the on-premises DOMAIN\group format. We initially ran icacls commands with the on-premises format and they appeared to succeed but were not enforced correctly. Fix: for Entra ID Kerberos environments, use the UPN format (group@contoso.com) in icacls commands, not the DOMAIN\name format.

4Role assigned at storage account scope, not share scope. One share's RBAC was accidentally assigned at the storage account scope level. Users in the Read group could mount and read all shares in the account, not just the one intended. Fix: always use az storage share-rm show --query id to get the share-level resource ID and use that as the --scope parameter. Audit with az role assignment list --scope <storage-account-id> to find any assignments at the wrong scope.

5Owner role not revoked after ACL configuration. Two storage administrators were left with the Owner role after configuring ACLs. We discovered this three weeks later during an access review. Fix: implement a policy that any Owner role assignment on a file share must include a Privileged Identity Management (PIM) time-bound activation with a maximum duration of 4 hours, and never as a standing assignment.

6AD DS computer account password expired. The AD computer account created by AzFilesHybrid has a password that must be renewed every 30 days. We missed the first renewal and all Kerberos authentication against the share failed with a cryptic "no logon servers available" error. Fix: automate the password renewal with a scheduled task using the Update-AzStorageAccountADObjectPassword cmdlet, or set a calendar alert. This is the most operationally demanding aspect of the AD DS authentication path.

Auditing Who Has Access to What

After implementation, ongoing access auditing is the control that prevents privilege drift — where users accumulate access over time as they move between teams and roles, but no one removes the old access. We run two types of audit: a monthly RBAC audit of which groups have which roles on which shares, and a quarterly group membership review delegated to department managers via Entra ID Access Reviews.

Azure CLI + PowerShell — Export all Azure Files RBAC assignments across all shares# Get all file shares in the storage account $StorageAccount = "stfiles001" $ResourceGroup = "rg-files-prod" $shares = az storage share-rm list \ --storage-account $StorageAccount \ --resource-group $ResourceGroup \ --query "[].name" -o tsv # For each share, list all RBAC assignments at share scope foreach ($share in $shares) { $shareId = az storage share-rm show \ --storage-account $StorageAccount \ --resource-group $ResourceGroup \ --name $share --query id -o tsv Write-Host "=== Share: $share ===" az role assignment list --scope $shareId \ --query "[].{Role:roleDefinitionName,Principal:principalName,Type:principalType}" \ -o table } # Also check for any assignments at the storage account scope (should be none for data plane roles) $saId = az storage account show --name $StorageAccount \ --resource-group $ResourceGroup --query id -o tsv az role assignment list --scope $saId \ --query "[?contains(roleDefinitionName,'File Data')].{Role:roleDefinitionName,Principal:principalName}" \ -o table

Implementation Summary: What to Do and What Not to Do

→Assign RBAC roles to groups, never individuals. Every individual RBAC assignment is a maintenance burden that compounds with scale. Groups managed in Entra ID by department owners give you access control that survives employee turnover without requiring Azure RBAC changes.

→Scope role assignments at the file share resource, not the storage account. Use az storage share-rm show --query id to get the exact share resource ID. Any RBAC assignment at the storage account scope grants access to every share in that account.

→Set root ACLs before copying any data. Root ACL changes after a large file population trigger recursive propagation that takes hours. Configure the ACL structure first on an empty share, verify it is correct, then populate data.

→The Owner role is a temporary tool, not a standing assignment. Assign it to configure ACLs, revoke it when done. Use Privileged Identity Management (PIM) for just-in-time activation if you need it occasionally. Never leave it as a permanent standing assignment.

→Wait 30 minutes after RBAC assignment before testing. Share-level RBAC propagation is not instant. Building this wait into your automation and user communication prevents a flood of "access denied" support tickets from users who try to connect immediately after being added to a group.

→If using AD DS authentication, automate the computer account password renewal. The AD DS computer account created by AzFilesHybrid has a password that must be renewed every 30 days. Missing this renewal breaks all Kerberos authentication for the storage account with a misleading error. Automate the renewal with a scheduled task running Update-AzStorageAccountADObjectPassword.

Frequently Asked Questions

Can I assign RBAC roles to computer accounts (machine accounts) in Azure Files?

No. Computer accounts cannot be synced to Entra ID, so they cannot be assigned specific RBAC roles on Azure file shares. If a computer account needs access to an Azure file share — for example, a service running as LocalSystem or a backup agent running as a machine account — use the Default Share-Level Permission instead. This option grants all authenticated users a specific level of access at the share level, allowing computer accounts to access the share without individual RBAC assignments. Alternatively, configure the service to run as a dedicated service account (user identity) rather than as the machine account, and assign that service account to the appropriate Entra ID group.

Can a user have both the Reader and Contributor roles on the same share?

Yes, and if they do, the higher permission level applies. Azure RBAC is additive at the share level — a user who is a member of both a Reader group and a Contributor group on the same share gets Contributor access (the more permissive role). This is different from how Windows NTFS ACLs work, where an explicit Deny always takes precedence over Allow. At the RBAC layer, higher permissions always win. At the NTFS ACL layer (Layer 2), an explicit Deny ACL on a folder or file will block access even if the user has the Contributor RBAC role at Layer 1.

How do we handle users who need access to some folders but not others within the same share?

Use the two-layer model exactly as designed. Assign all users who need any access to the share the Contributor RBAC role (Layer 1 — they can mount the share). Then use Windows NTFS ACLs (Layer 2) to restrict access at the folder level — grant explicit access to the folders they are allowed to see and omit them (or add an explicit Deny) on the folders they should not access. A user with the Contributor RBAC role who has no NTFS ACL entry for a specific folder will receive Access Denied when they try to open that folder, because the NTFS ACL evaluation says no. The RBAC role only enables them to mount the share — it does not override NTFS ACLs.

How do we migrate existing Windows ACLs from an on-premises file server to Azure Files?

Use RoboCopy with the /COPYALL flag, which copies NTFS ACLs along with the file data. Running RoboCopy with /COPYALL requires the account to have SeBackupPrivilege on the source and SeRestorePrivilege on the destination, which requires either local Administrator rights or explicit privilege assignment. The AzFilesHybrid module also includes the Move-OnPremSharePermissionsToAzureFileShare PowerShell cmdlet, which automatically converts the root directory ACLs from an on-premises share into Azure RBAC assignments on the corresponding Azure file share. This cmdlet handles the root level only — sub-directory and file ACLs are carried over by RoboCopy.

Related FAVRITE Articles

• Designing a Secure File Storage Architecture in Azure
• Key Considerations Before Migrating File Shares to Azure
• Stop Using Connection Strings: A Step-by-Step Guide to Azure Managed Identities in 2026
• How to Secure Azure Resources Using Microsoft Defender for Cloud