Skip to main content

Theoretical Foundation: Configure identity-based access for Azure Files

1. Initial Intuition​

Imagine your company has a traditional Windows file server: a network shared folder where each employee accesses with their Active Directory login. The manager sees everything, the analyst sees only their department's folder, and the intern sees only public documents. This control is done through NTFS permissions linked to AD identities.

Azure Files is the equivalent of this network shared folder, but hosted in the cloud as a managed service. And identity-based access is exactly the capability to apply to Azure Files the same Active Directory access control model you already know: authentication with identity, permissions per user and group, ACLs at file and directory level.

Without identity-based access, Azure Files uses access keys (the physical key to the vault, as we saw in the previous module), where anyone with the key has full access. With identity-based access, you preserve the granularity and traceability of the Windows/Active Directory model in the cloud.

2. Context​

Azure Files supports the SMB (Server Message Block) protocol, the same protocol used by Windows for network file sharing. This means you can mount an Azure File Share on a Windows computer as if it were a network drive, using drive letter Z:\ for example.

100%
Scroll para zoom · Arraste para mover · 📱 Pinch para zoom no celular

Identity-based access to Azure Files uses two levels of control that work together, exactly like the Windows model:

  1. Share-level permissions: what the user can do in the file share as a whole (equivalent to network access)
  2. NTFS permissions (file-level): what the user can do in specific files and directories within the share (equivalent to NTFS permissions)

Both levels need to allow access for the user to reach the file. It's an AND logic: permission on the share AND permission on the file.

3. Building the Concepts​

3.1 Identity Sources for Authentication​

Azure Files supports four identity sources for identity-based authentication:

100%
Scroll para zoom · Arraste para mover · 📱 Pinch para zoom no celular
SourceEnvironmentProtocolPrerequisite
AD DS on-premisesHybridKerberosLocal Windows domain; storage account "joined" to domain via script
Microsoft Entra Domain ServicesCloud-onlyKerberosEntra ID DS provisioned; storage account enabled for AADDS
Microsoft Entra ID (Kerberos)Cloud / HybridKerberosEntra joined or Hybrid joined devices; works without on-premises AD
Local AD DS (via Azure File Sync)Hybrid with syncKerberosAzure File Sync configured; on-premises server as endpoint

For AZ-104, the two most relevant scenarios are AD DS on-premises (hybrid scenario) and Microsoft Entra ID Kerberos (modern scenario for Entra joined devices).

3.2 The Kerberos Protocol and Why It Matters​

Kerberos is the authentication protocol used by both traditional AD and Azure Files with identity-based access. When a Windows client accesses an Azure File Share with identity, the process is:

100%
Scroll para zoom · Arraste para mover · 📱 Pinch para zoom no celular

The KDC (Key Distribution Center) is the authority that issues tickets. In AD DS on-premises, it's the domain controller. In Entra ID Kerberos, it's Entra ID itself acting as KDC.

3.3 Share-Level Permissions: Azure RBAC​

Permissions at the share level are controlled by Azure RBAC, using specific roles for Azure Files:

RBAC RoleWhat it allowsWindows equivalent
Storage File Data SMB Share ReaderRead files and attributesRead & Execute
Storage File Data SMB Share ContributorRead, write and delete filesModify
Storage File Data SMB Share Elevated ContributorRead, write, delete AND modify ACLsFull Control
Storage File Data Privileged ReaderRead including permissions (for backup/restore)Backup Operator
Storage File Data Privileged ContributorComplete access including permissions for backupBackup Operator with write

These roles are assigned at the storage account scope (not at the individual file share, as RBAC granularity doesn't go directly to the share in the current model).

Important: the Storage File Data SMB Share * roles are DataActions, not Actions. They control access to data via SMB, not storage account management.

3.4 NTFS Permissions: Granular Control per File and Directory​

NTFS ACLs (Access Control Lists) are permissions defined directly on files and directories within the file share. They work exactly like NTFS permissions in Windows:

NTFS PermissionWhat it allows
Full ControlEverything, including modifying permissions
ModifyRead, write, execute, delete
Read & ExecuteRead and execute files
ReadRead only
WriteCreate and modify files
List Folder ContentsView directory contents

NTFS ACLs are defined from within Windows (via Explorer, icacls, PowerShell) after the share is mounted. They are stored in the file metadata in Azure Files and persist.

3.5 The Two-Level Logic​

The combination of both levels works like this:

100%
Scroll para zoom · Arraste para mover · 📱 Pinch para zoom no celular

The share-level is the entry gate: without it, the share won't mount. NTFS is the internal control: even with the share mounted, access to specific files can be denied.

Special case: when enabling identity-based access for the first time, Azure automatically assigns Full Control to all authenticated users in the NTFS ACLs at the share root. This means that for granular restrictions, you need to configure NTFS ACLs explicitly after mounting the share.

4. Structural View​

100%
Scroll para zoom · Arraste para mover · 📱 Pinch para zoom no celular

5. Practical Operation​

Configuration for AD DS On-Premises (Hybrid Scenario)​

This is the most used path in companies that already have local Windows AD:

100%
Scroll para zoom · Arraste para mover · 📱 Pinch para zoom no celular

Step 2 in detail: the AzFilesHybrid module is a PowerShell module available on Microsoft's GitHub that executes the "domain join" process of the storage account. What this means technically: it creates a computer account object (or service account) in the local AD representing the storage account, and registers the relationship in Azure. After that, the storage account accepts Kerberos tickets issued by your AD.

# Install the AzFilesHybrid module
Install-Module -Name AzFilesHybrid

# Connect to Azure
Connect-AzAccount

# Execute the storage account domain join
Join-AzStorageAccountForAuth `
  -ResourceGroupName "rg-producao" `
  -StorageAccountName "minhaconta" `
  -DomainAccountType "ComputerAccount" `
  -OrganizationalUnitDistinguishedName "OU=AzureFileStorage,DC=contoso,DC=com"

Configuration for Microsoft Entra ID Kerberos (Modern Scenario)​

For Entra joined or Hybrid joined devices without the need for on-premises AD:

# Enable Entra ID Kerberos on storage account via CLI
az storage account update \
  --name minhaconta \
  --resource-group rg-producao \
  --enable-files-aadkerb true

After enabling, users with Entra joined devices can access the share using their Entra ID credentials, without needing an on-premises AD.

Additional requirement: the Windows client needs to have the Entra ID Kerberos extension installed. In Windows 11 and Windows 10 21H2+, this is already available. In older versions, it requires an update.

Important and Non-Obvious Behaviors​

NTFS ACLs vs. Share-level: which prevails? The most restrictive permission from each level applies. If share-level says "Contributor" (read and write) but the NTFS ACL on the file says "Read only", the user can only read. If share-level says "Reader" but the NTFS ACL says "Full Control", the user can still only read (share-level is the upper limit).

The storage account needs to be "domain joined" to accept Kerberos: unlike Blob Storage, where any storage account accepts Entra ID authentication via RBAC, Azure Files requires an explicit configuration step (domain join or enable Entra Kerberos) to accept identity authentication. An unconfigured storage account only accepts access keys.

ACLs are preserved in Azure Files: NTFS ACLs configured on files and directories are stored as metadata in Azure Files and persist. If you unmount the share, reconfigure permissions and mount again, the NTFS ACLs are still there.

AD password synchronization: for the scenario with AD DS on-premises, AD user passwords are not synchronized to Azure. Kerberos authentication works because the local AD issues tickets that Azure Files validates, without ever seeing the user's password.

6. Implementation Methods​

6.1 Azure Portal​

When to use: verify configuration status, assign share-level permissions (RBAC), configure which identity source is enabled.

Path to enable identity-based access: Storage Account > File shares > Active Directory

In this screen you see the status of each option:

  • Windows Server Active Directory (AD DS on-premises): Configured / Not configured
  • Microsoft Entra Domain Services: Enabled / Disabled
  • Microsoft Entra Kerberos: Enabled / Disabled

Path for share-level permissions: Storage Account > Access control (IAM) > Add role assignment

Select one of the Storage File Data SMB Share * roles and assign to user or group.

Limitation: domain join for AD DS on-premises cannot be done through the portal. Requires the AzFilesHybrid PowerShell module.

6.2 PowerShell​

Check identity-based access configuration status:

Get-AzStorageAccount `
  -ResourceGroupName "rg-producao" `
  -Name "minhaconta" |
  Select-Object -ExpandProperty AzureFilesIdentityBasedAuth

Enable Microsoft Entra Domain Services:

Set-AzStorageAccount `
  -ResourceGroupName "rg-producao" `
  -Name "minhaconta" `
  -EnableAzureActiveDirectoryDomainServicesForFile $true

Configure NTFS ACLs via icacls (executed from within the mounted share):

# Mount the share with access key to configure initial ACLs
$connectTestResult = Test-NetConnection -ComputerName "minhaconta.file.core.windows.net" -Port 445
if ($connectTestResult.TcpTestSucceeded) {
    $password = ConvertTo-SecureString -String "<access-key>" -AsPlainText -Force
    $credential = New-Object System.Management.Automation.PSCredential("Azure\minhaconta", $password)
    New-PSDrive -Name Z -PSProvider FileSystem `
      -Root "\\minhaconta.file.core.windows.net\meu-share" `
      -Credential $credential
}

# Configure NTFS ACL for an AD group
icacls Z:\ /grant "CONTOSO\Grupo-Financeiro:(OI)(CI)(M)"

# Configure NTFS ACL for specific folder
icacls "Z:\Projetos\Confidencial" /grant "CONTOSO\Gerentes:(OI)(CI)(F)"
icacls "Z:\Projetos\Confidencial" /deny "CONTOSO\Estagiarios:(OI)(CI)(R)"

The icacls flags mean:

  • (OI): Object Inherit - applies to files within the directory
  • (CI): Container Inherit - applies to subdirectories
  • (M): Modify
  • (F): Full Control
  • (R): Read

6.3 Azure CLI​

Check identity-based access configuration:

az storage account show \
  --name minhaconta \
  --resource-group rg-producao \
  --query "azureFilesIdentityBasedAuth" \
  --output json

Enable Microsoft Entra Kerberos:

az storage account update \
  --name minhaconta \
  --resource-group rg-producao \
  --enable-files-aadkerb true

Enable Microsoft Entra Domain Services:

az storage account update \
  --name minhaconta \
  --resource-group rg-producao \
  --enable-files-aadds true

Assign share-level role via CLI:

az role assignment create \
  --assignee "grupo-financeiro@contoso.com" \
  --role "Storage File Data SMB Share Contributor" \
  --scope "/subscriptions/<sub-id>/resourceGroups/rg-producao/providers/Microsoft.Storage/storageAccounts/minhaconta"

7. Control and Security​

The Separation Between Mounting and Data Access​

A critical behavior for diagnosis: share-level permission controls whether the share can be mounted, but is not checked at every file operation. NTFS ACL is checked at every file or directory access.

This means:

  • User without share-level permission: cannot mount the share (error in SMB connection)
  • User with share-level permission but without NTFS permission: mounts the share, but receives "Access denied" when trying to open specific files

"Super User" Permission for Initial Configuration​

There is a special role for administrators who need to configure NTFS ACLs without restrictions: Storage File Data Privileged Contributor. It grants privileged access that bypasses existing NTFS ACLs, allowing the administrator to configure initial permissions even on a share where ACLs block access.

In practice, the recommended flow for initial configuration is:

  1. Mount the share using the access key (which always has full access)
  2. Configure the correct NTFS ACLs
  3. After configuration, apply share-level RBAC for end users
  4. In the future, administrators use the Privileged Contributor role when they need to adjust ACLs

Protocol Compatibility​

ProtocolSupports identity-based auth?Notes
SMB 3.0+YesMain protocol, with encryption
SMB 2.1YesNo encryption in-transit
NFS 4.1NoAzure Files NFS uses network-based access control (VNet), not identity
REST APINo (via Entra RBAC DataActions)Not SMB; uses different authentication model

Access via NFS 4.1 to Azure Files (available only on Premium shares) uses a completely different model: access control is based on network (IP/VNet restriction) and Linux UID/GID, not on AD or Entra ID. This protocol is for Linux and HPC workloads, not for the Windows scenario described in this module.

8. Decision Making​

Which identity source to choose?​

SituationRecommended sourceReason
Company with on-premises AD and domain-joined VMs in AzureOn-premises AD DSReuses existing identities, no additional infrastructure
Cloud-only company without AD, users on Azure VMsMicrosoft Entra Domain ServicesAD as a managed service, no servers to maintain
Modern devices (Windows 10/11 Entra joined) without VMsMicrosoft Entra ID KerberosSimpler, no Entra DS, more modern
Branch office without local AD that needs to access sharesMicrosoft Entra ID KerberosDoesn't require local AD at the branch
Linux workloads that need shared accessNFS 4.1 with network restrictionIdentity-based auth doesn't apply to NFS

Which share-level RBAC role to assign?​

SituationRoleReason
Regular users who read and edit filesStorage File Data SMB Share ContributorAllows read, write and delete
Users who only consult filesStorage File Data SMB Share ReaderLeast privilege
Admin who needs to configure NTFS ACLsStorage File Data SMB Share Elevated ContributorCan modify permissions
Backup system that needs to access everythingStorage File Data Privileged Reader / ContributorBypasses ACLs for complete backup

9. Best Practices​

Configure share-level permissions with groups, not individual users: exactly like in general Azure RBAC, assigning roles to groups facilitates management. A new employee in the finance department joins the "Finance-Group" and automatically inherits the SMB Share permissions from the group.

Configure NTFS ACLs mirroring the business folder structure: the NTFS permissions hierarchy should reflect the organizational structure. Create AD groups for each necessary access level ("Project-Readers", "Project-Alpha-Editors", etc.) and configure NTFS ACLs using those groups.

Use NTFS ACL inheritance: when configuring ACLs with (OI)(CI) flags, permissions automatically propagate to new files and subdirectories created within the folder. This eliminates the need to manually reconfigure permissions for each new file.

Keep the AD computer object synchronized: in the scenario with on-premises AD DS, the storage account is represented as a computer object in AD with a password that expires periodically. The AzFilesHybrid module has a cmdlet to update this credential; configure automated rotation to prevent Kerberos from stopping when the password expires.

# Update the storage account credential in AD
Update-AzStorageAccountADObjectPassword `
  -ResourceGroupName "rg-producao" `
  -StorageAccountName "minhaconta" `
  -RotateToKerbKey kerb1

10. Common Errors​

Assigning share-level permission but forgetting to configure NTFS ACLs

The user receives the Contributor RBAC role, mounts the share without problems, but when trying to create or modify files receives "Access denied". The reason: when enabling identity-based access, Azure configures the share root NTFS ACLs with default permissions that may not include the user. The share mounts (share-level OK) but file access fails (NTFS ACL not configured). The solution is to explicitly configure NTFS ACLs after enabling identity-based access.

Trying to enable on-premises AD DS through the portal or CLI without the AzFilesHybrid module

The portal and CLI allow "enabling" on-premises AD DS, but without executing the domain join via AzFilesHybrid, the configuration is incomplete. The storage account needs the computer object created in the local AD to issue valid Kerberos tickets. Without this, authentication fails even with the checkbox marked in the portal.

Forgetting to renew the computer object password in AD

In the on-premises AD DS scenario, the storage account has a computer object in AD with a password. This password expires following the domain password policy (usually 90 days). When it expires, Kerberos stops working: users receive authentication errors when trying to mount the share. Configure a scheduled task or pipeline to renew this credential periodically.

Trying to access Azure Files with identity-based auth from a client not joined to the domain

If the user's device is not in the AD domain (nor Entra joined for the Entra Kerberos case), the client has no way to obtain a Kerberos ticket for the storage account. Access via identity-based auth requires the client to be in one of the supported identity models. A personal laptop without domain configuration cannot use identity authentication; it would need to use the access key directly.

Confusing NFS 4.1 with SMB for identity-based access

An administrator configures identity-based access on the storage account and expects Linux VMs accessing via NFS 4.1 to also benefit from identity authentication. NFS 4.1 in Azure Files doesn't use AD or Entra ID; access control is via network restriction (VNet/subnet). They are two protocols with completely different security models in Azure Files.

11. Operation and Maintenance​

Check Configuration Status​

# Complete identity-based configuration status
$account = Get-AzStorageAccount `
  -ResourceGroupName "rg-producao" `
  -Name "minhaconta"

$account.AzureFilesIdentityBasedAuth | ConvertTo-Json -Depth 5

The result shows which method is active, AD settings and computer object status.

Authentication Problem Diagnosis​

Azure Files logs authentication errors in the Storage Account via Storage Analytics Logging or Azure Monitor. For PowerShell diagnosis:

# Check if the storage account is correctly domain-joined
Debug-AzStorageAccountAuth `
  -StorageAccountName "minhaconta" `
  -ResourceGroupName "rg-producao" `
  -Verbose

The Debug-AzStorageAccountAuth cmdlet (part of the AzFilesHybrid module) performs a series of automated checks and reports specific configuration issues.

Important Limits​

ItemDetail
Supported protocols for identity authSMB 2.1 and 3.0/3.1
Windows versions supported for Entra KerberosWindows 10 21H2+, Windows 11, Windows Server 2022+
Maximum NTFS ACL sizeNo specific documented limit
AD object password renewalFollowing domain policy (usually 90 days)
Premium vs. Standard sharesIdentity-based auth works on both

12. Integration and Automation​

Azure File Sync with Identity-Based Access​

Azure File Sync synchronizes an on-premises Windows file server with an Azure File Share. In this scenario, the on-premises server is the primary endpoint where users access files. The NTFS ACLs configured on the on-premises server are synchronized to Azure Files and preserved.

In this model, on-premises AD is the identity source for both local users and those accessing Azure Files directly.

Domain Join Automation via CI/CD Pipeline​

For automated provisioning of storage accounts with identity-based access already configured:

# Storage account creation pipeline with automatic domain join
param(
    [string]$resourceGroup,
    [string]$storageAccountName,
    [string]$ouDN
)

# 1. Create the storage account
New-AzStorageAccount `
  -ResourceGroupName $resourceGroup `
  -Name $storageAccountName `
  -SkuName Standard_LRS `
  -Kind StorageV2 `
  -Location "brazilsouth"

# 2. Domain join via AzFilesHybrid
Join-AzStorageAccountForAuth `
  -ResourceGroupName $resourceGroup `
  -StorageAccountName $storageAccountName `
  -DomainAccountType "ComputerAccount" `
  -OrganizationalUnitDistinguishedName $ouDN

# 3. Assign default role to user group
$scope = "/subscriptions/$((Get-AzContext).Subscription.Id)/resourceGroups/$resourceGroup/providers/Microsoft.Storage/storageAccounts/$storageAccountName"

New-AzRoleAssignment `
  -ObjectId (Get-AzADGroup -DisplayName "SMB-FileShare-Users").Id `
  -RoleDefinitionName "Storage File Data SMB Share Contributor" `
  -Scope $scope

13. Final Summary​

Essential points:

  • Azure Files supports identity-based access via on-premises AD DS, Microsoft Entra Domain Services and Microsoft Entra ID Kerberos. The protocol used is Kerberos, the same as traditional Windows AD.
  • Access control has two independent levels: share-level permissions (Azure RBAC) and file-level permissions (NTFS ACLs). Both need to allow access for the user to reach the file.
  • The specific RBAC roles for Azure Files are DataActions in the Storage File Data SMB Share * family, not to be confused with generic roles like Contributor.
  • Domain join of the storage account to on-premises AD requires the AzFilesHybrid PowerShell module and cannot be done through the portal.

Critical differences:

  • Share-level (RBAC) vs. File-level (NTFS ACL): share-level controls access to the share as a whole (mounting); NTFS ACL controls access to specific files and directories. The two combine with AND logic.
  • On-premises AD DS vs. Entra ID Kerberos: on-premises AD DS requires domain join via script and computer object in AD; Entra ID Kerberos only needs an az storage account update and Entra joined devices.
  • SMB with identity auth vs. NFS 4.1: SMB supports identity-based access; NFS 4.1 uses network-based access control, without AD or Entra ID.
  • Storage File Data SMB Share Contributor vs. Storage File Data SMB Share Elevated Contributor: Contributor allows reading and writing files; Elevated Contributor can additionally modify NTFS ACLs.

What needs to be remembered:

  • When enabling identity-based access, Azure assigns Full Control to all authenticated users in the root NTFS ACLs by default. Configure ACLs explicitly for granular restrictions.
  • In the on-premises AD DS scenario, the computer object in AD has a password that expires. Configure automatic renewal to avoid interruptions in Kerberos authentication.
  • Share-level permissions are assigned at the storage account scope, not individual file share.
  • For initial NTFS ACL configuration on a new share, the most practical path is to mount with the access key (full access), configure ACLs, and then use only identity-based authentication.
  • The Storage File Data Privileged Contributor role bypasses NTFS ACLs and is intended for backup and administration operations, not for regular users.