Enable Active Directory authentication over SMB for Azure file shares

Azure Files supports identity-based authentication over Server Message Block (SMB) through two types of Domain Services: Azure Active Directory Domain Services (Azure AD DS) (GA) and Active Directory (AD) (preview). This article focuses on the newly introduced (preview) support of leveraging Active Directory Domain Service for authentication to Azure file shares. If you are interested in enabling Azure AD DS (GA) authentication for Azure file shares, refer to our article on the subject.

Note

Azure file shares only support authentication against one domain service, either Azure Active Directory Domain Service (Azure AD DS) or Active Directory (AD).

AD identities used for Azure file share authentication must be synced to Azure AD. Password hash synchronization is optional.

AD authentication does not support authentication against Computer accounts created in AD.

AD authentication can only be supported against one AD forest where the storage account is registered to. You can only access Azure file shares with the AD credentials from a single AD forest by default. If you need to access your Azure file share from a different forest, make sure that you have the proper forest trust configured, see FAQ for details.

AD authentication for SMB access and ACL persistence is supported for Azure file shares managed by Azure File Sync.

Azure Files supports Kerberos authentication with AD with RC4-HMAC encryption. AES Kerberos encryption is not yet supported.

When you enable AD for Azure file shares over SMB, your AD domain joined machines can mount Azure file shares using your existing AD credentials. This capability can be enabled with an AD environment hosted either in on-prem machines or hosted in Azure.

AD identities used to access Azure file shares must be synced to Azure AD to enforce share level file permissions through the standard role-based access control (RBAC) model. Windows-style DACLs on files/directories carried over from existing file servers will be preserved and enforced. This feature offers seamless integration with your enterprise AD domain infrastructure. As you replace on-prem file servers with Azure file shares, existing users can access Azure file shares from their current clients with a single sign-on experience, without any change to the credentials in use.

Prerequisites

Before you enable AD authentication for Azure file shares, make sure you have completed the following prerequisites:

  • Select or create your AD environment and sync it to Azure AD.

    You can enable the feature on a new or existing AD environment. Identities used for access must be synced to Azure AD. The Azure AD tenant and the file share that you are accessing must be associated with the same subscription.

    To setup an AD domain environment, refer to Active Directory Domain Services Overview. If you have not synced your AD to your Azure AD, follow the guidance in What is hybrid identity with Azure Active Directory? in order to determine your preferred authentication method and Azure AD Connect setup option.

  • Domain-join an on-premises machine or an Azure VM to AD (also referred as AD DS).

    To access a file share by using AD credentials from a machine or VM, your device must be domain-joined to AD. For information about how to domain-join to AD, refer to Join a Computer to a Domain.

  • Select or create an Azure storage account in a supported region.

    Make sure that the storage account containing your file shares is not already configured for Azure AD DS Authentication. If Azure Files Azure AD DS Authentication is enabled on the storage account, it needs to be disabled before changing to use AD. This implies that existing ACLs configured in Azure AD DS environment will need to be reconfigured for proper permission enforcement.

    For information about creating a new file share, see Create a file share in Azure Files.

    For optimal performance, we recommend that you deploy the storage account in the same region as the VM from which you plan to access the share.

  • Verify connectivity by mounting Azure file shares using your storage account key.

    To verify that your device and file share are properly configured, try mounting the file share using your storage account key. For more information, see Use an Azure file share with Windows.

Regional availability

Azure Files AD authentication (preview) is available in most public regions.

Azure Files AD authentication is not available in:

  • West US

Workflow overview

Before you enable AD Authentication over SMB for Azure file shares, we recommend that you walk through the prerequisites and make sure you've completed all the steps. The prerequisites validate that your AD, Azure AD, and Azure Storage environments are properly configured.

Next, grant access to Azure Files resources with AD credentials:

  • Enable Azure Files AD authentication on your storage account.

  • Assign access permissions for a share to the Azure AD identity (a user, group, or service principal) that is in sync with the target AD identity.

  • Configure ACLs over SMB for directories and files.

  • Mount an Azure file share from an AD domain joined VM.

The following diagram illustrates the end-to-end workflow for enabling Azure AD authentication over SMB for Azure file shares.

Files AD workflow diagram

Note

AD authentication over SMB for Azure file shares is only supported on machines or VMs running on OS versions newer than Windows 7 or Windows Server 2008 R2.

Enable AD authentication for your account

To enable AD authentication over SMB for Azure file shares, you need to first register your storage account with AD and then set the required domain properties on the storage account. When the feature is enabled on the storage account, it applies to all new and existing file shares in the account. Use join-AzStorageAccountForAuth to enable the feature. You can find the detailed description of the end-to-end workflow in the section below.

Important

The Join-AzStorageAccountForAuth cmdlet will make modifications to your AD environment. Read the following explanation to better understand what it is doing to ensure you have the proper permissions to execute the command and that the applied changes align with the compliance and security policies.

The Join-AzStorageAccountForAuth cmdlet will perform the equivalent of an offline domain join on behalf of the indicated storage account. It will create an account in your AD domain, either a computer account or a service logon account. The created AD account represents the storage account in the AD domain. If the AD account is created under an AD Organizational Unit (OU) that enforces password expiration, you must update the password before the maximum password age. Failing to update AD account password will result in authentication failures when accessing Azure file shares. To learn how to update the password, see Update AD account password.

You can use the following script to perform the registration and enable the feature or, alternatively, you can manually perform the operations that the script would. Those operations are described in the section following the script. You do not need to do both.

1. Check prerequisites

  • Download and unzip the AzFilesHybrid module
  • Install and execute the module in a device that is domain joined to AD with AD credentials that have permissions to create a service logon account or a computer account in the target AD.
  • Run the script using an AD credential that is synced to your Azure AD. The AD credential must have either the storage account owner or the contributor RBAC role permissions.
  • Make sure your storage account is in a supported region.

2. Domain join your storage account

Remember to replace the placeholder values with your own in the parameters below before executing it in PowerShell.

#Change the execution policy to unblock importing AzFilesHybrid.psm1 module
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

# Navigate to where AzFilesHybrid is unzipped and stored and run to copy the files into your path
.\CopyToPSPath.ps1 

#Import AzFilesHybrid module
Import-Module -Name AzFilesHybrid

#Login with an Azure AD credential that has either storage account owner or contributer RBAC assignment
Connect-AzAccount

#Select the target subscription for the current session
Select-AzSubscription -SubscriptionId "<your-subscription-id-here>"

# Register the target storage account with your active directory environment under the target OU (for example: "OU=ComputersOU,DC=prod,DC=corp,DC=contoso,DC=com")
# You can choose to create the identity that represents the storage account as either a Service Logon Account or Computer Account, depends on the AD permission you have and preference. 
Join-AzStorageAccountForAuth `
        -ResourceGroupName "<resource-group-name-here>" `
        -Name "<storage-account-name-here>" `
        -DomainAccountType "ComputerAccount" `
        -OrganizationalUnitName "<ou-name-here>"

The following description summarizes all actions performed when the Join-AzStorageAccountForAuth cmdlet gets executed. You may perform these steps manually, if you prefer not to use the command:

Note

If you have already executed the Join-AzStorageAccountForAuth script above successfully, go to the next section "3. Confirm that the feature is enabled". You do not need to perform the operations below again.

a. Checking environment

First, it checks your environment. Specifically it checks if the Active Directory PowerShell is installed and if the shell is being executed with administrator privileges. Then it checks to see if the Az.Storage 1.11.1-preview module is installed, and installs it if it isn't. If those checks pass, then it will check your AD to see if there is either a computer account (default) or service logon account that has already been created with SPN/UPN as "cifs/your-storage-account-name-here.file.core.windows.net". If the account doesn't exist, it will create one as described in section b below.

b. Creating an identity representing the storage account in your AD manually

To create this account manually, create a new kerberos key for your storage account using New-AzStorageAccountKey -KeyName kerb1. Then, use that kerberos key as the password for your account. This key is only used during set up and cannot be used for any control or data plane operations against the storage account.

Once you have that key, create either a service or computer account under your OU. Use the following specification: SPN: "cifs/your-storage-account-name-here.file.core.windows.net" Password: Kerberos key for your storage account.

If your OU enforces password expiration, you must update the password before the maximum password age to prevent authentication failures when accessing Azure file shares. See Update AD account password for details.

Keep the SID of the newly created account, you'll need it for the next step. The AD identity you have just created that represent the storage account does not need to be synced to Azure AD.

c. Enable the feature on your storage account

The script would then enable the feature on your storage account. To perform this setup manually, provide some configuration details for the domain properties in the following command, then run it. The storage account SID required in the following command is the SID of the identity you created in AD (section b above).

# Set the feature flag on the target storage account and provide the required AD domain information
Set-AzStorageAccount `
        -ResourceGroupName "<your-resource-group-name-here>" `
        -Name "<your-storage-account-name-here>" `
        -EnableActiveDirectoryDomainServicesForFile $true `
        -ActiveDirectoryDomainName "<your-domain-name-here>" `
        -ActiveDirectoryNetBiosDomainName "<your-netbios-domain-name-here>" `
        -ActiveDirectoryForestName "<your-forest-name-here>" `
        -ActiveDirectoryDomainGuid "<your-guid-here>" `
        -ActiveDirectoryDomainsid "<your-domain-sid-here>" `
        -ActiveDirectoryAzureStorageSid "<your-storage-account-sid>"

3. Confirm that the feature is enabled

You can check to confirm whether the feature is enabled on your storage account, you can use the following script:

# Get the target storage account
$storageaccount = Get-AzStorageAccount `
        -ResourceGroupName "<your-resource-group-name-here>" `
        -Name "<your-storage-account-name-here>"

# List the directory service of the selected service account
$storageAccount.AzureFilesIdentityBasedAuth.DirectoryServiceOptions

# List the directory domain information if the storage account has enabled AD authentication for file shares
$storageAccount.AzureFilesIdentityBasedAuth.ActiveDirectoryProperties

You've now successfully enabled the feature on your storage account. Even though the feature is enabled, you still need to complete additional actions to be able to use the feature properly.

Assign access permissions to an identity

To access Azure Files resources with identity based authentication, an identity (a user, group, or service principal) must have the necessary permissions at the share level. This process is similar to specifying Windows share permissions, where you specify the type of access that a particular user has to a file share. The guidance in this section demonstrates how to assign read, write, or delete permissions for a file share to an identity.

We have introduced three Azure built-in roles for granting share-level permissions to users:

  • Storage File Data SMB Share Reader allows read access in Azure Storage file shares over SMB.
  • Storage File Data SMB Share Contributor allows read, write, and delete access in Azure Storage file shares over SMB.
  • Storage File Data SMB Share Elevated Contributor allows read, write, delete and modify NTFS permissions in Azure Storage file shares over SMB.

Important

Full administrative control of a file share, including the ability to take ownership of a file, requires using the storage account key. Administrative control is not supported with Azure AD credentials.

You can use the Azure portal, PowerShell, or Azure CLI to assign the built-in roles to the Azure AD identity of a user for granting share-level permissions.

Note

Remember to sync your AD credentials to Azure AD if you plan to use your AD for authentication. Password hash sync from AD to Azure AD is optional. Share level permission will be granted to the Azure AD identity that is synced from AD.

Azure portal

To assign an RBAC role to an Azure AD identity, using the Azure portal, follow these steps:

  1. In the Azure portal, go to your file share, or Create a file share.
  2. Select Access Control (IAM).
  3. Select Add a role assignment
  4. In the Add role assignment blade, select the appropriate built-in role (Storage File Data SMB Share Reader, Storage File Data SMB Share Contributor) from the Role list. Leave Assign access to at the default setting: Azure AD user, group, or service principal. Select the target Azure AD identity by name or email address.
  5. Select Save to complete the role assignment operation.

PowerShell

The following PowerShell sample shows how to assign an RBAC role to an Azure AD identity, based on sign-in name. For more information about assigning RBAC roles with PowerShell, see Manage access using RBAC and Azure PowerShell.

Before you run the following sample script, remember to replace placeholder values, including brackets, with your own values.

#Get the name of the custom role
$FileShareContributorRole = Get-AzRoleDefinition "<role-name>" #Use one of the built-in roles: Storage File Data SMB Share Reader, Storage File Data SMB Share Contributor, Storage File Data SMB Share Elevated Contributor
#Constrain the scope to the target file share
$scope = "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>/fileServices/default/fileshares/<share-name>"
#Assign the custom role to the target identity with the specified scope.
New-AzRoleAssignment -SignInName <user-principal-name> -RoleDefinitionName $FileShareContributorRole.Name -Scope $scope

CLI

The following CLI 2.0 command shows how to assign an RBAC role to an Azure AD identity, based on sign-in name. For more information about assigning RBAC roles with Azure CLI, see Manage access by using RBAC and Azure CLI.

Before you run the following sample script, remember to replace placeholder values, including brackets, with your own values.

#Assign the built-in role to the target identity: Storage File Data SMB Share Reader, Storage File Data SMB Share Contributor, Storage File Data SMB Share Elevated Contributor
az role assignment create --role "<role-name>" --assignee <user-principal-name> --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>/fileServices/default/fileshares/<share-name>"

Configure NTFS permissions over SMB

After you assign share-level permissions with RBAC, you must assign proper NTFS permissions at the root, directory, or file level. Think of share-level permissions as the high-level gatekeeper that determines whether a user can access the share. Whereas NTFS permissions act at a more granular level to determine what operations the user can do at the directory or file level.

Azure Files supports the full set of NTFS basic and advanced permissions. You can view and configure NTFS permissions on directories and files in an Azure file share by mounting the share and then using Windows File Explorer or running the Windows icacls or Set-ACL command.

To configure NTFS with superuser permissions, you must mount the share by using your storage account key from your domain-joined VM. Follow the instructions in the next section to mount an Azure file share from the command prompt and to configure NTFS permissions accordingly.

The following sets of permissions are supported on the root directory of a file share:

  • BUILTIN\Administrators:(OI)(CI)(F)
  • NT AUTHORITY\SYSTEM:(OI)(CI)(F)
  • BUILTIN\Users:(RX)
  • BUILTIN\Users:(OI)(CI)(IO)(GR,GE)
  • NT AUTHORITY\Authenticated Users:(OI)(CI)(M)
  • NT AUTHORITY\SYSTEM:(F)
  • CREATOR OWNER:(OI)(CI)(IO)(F)

Configure NTFS permissions with icacls

Use the following Windows command to grant full permissions to all directories and files under the file share, including the root directory. Remember to replace the placeholder values in the example with your own values.

icacls <mounted-drive-letter>: /grant <user-email>:(f)

For more information on how to use icacls to set NTFS permissions and on the different types of supported permissions, see the command-line reference for icacls.

Mount a file share from the command prompt

Use the Windows net use command to mount the Azure file share. Remember to replace the placeholder values in the following example with your own values. For more information about mounting file shares, see Use an Azure file share with Windows.

net use <desired-drive-letter>: \\<storage-account-name>.file.core.windows.net\<share-name> <storage-account-key> /user:Azure\<storage-account-name>

Configure NTFS permissions with Windows File Explorer

Use Windows File Explorer to grant full permission to all directories and files under the file share, including the root directory.

  1. Open Windows File Explorer and right click on the file/directory and select Properties
  2. Click on the Security tab
  3. Click on Edit... button to change permissions
  4. You can change the permission of existing users, or click on Add... to grant permissions to new users
  5. In the prompt window for adding new users, enter the target user name you want to grant permission to in the Enter the object names to select box, and click on Check Names to find the full UPN name of the target user.
  6. Click on OK
  7. In the Security tab, select all permissions you want to grant to the newly add user
  8. Click on Apply

Mount a file share from a domain-joined VM

The following process verifies that your file share and access permissions were set up correctly and that you can access an Azure File share from a domain-joined VM:

Sign in to the VM by using the Azure AD identity to which you have granted permissions, as shown in the following image. If you have enabled AD authentication for Azure Files, use the AD credential. For Azure AD DS authentication, log in with Azure AD credential.

Screenshot showing Azure AD sign-in screen for user authentication

Use the following command to mount the Azure file share. Remember to replace the placeholder values with your own values. Because you've been authenticated, you don't need to provide the storage account key, the AD credentials, or the Azure AD credentials. Single sign-on experience is supported for authentication with either AD or Azure AD DS.

net use <desired-drive-letter>: \\<storage-account-name>.file.core.windows.net\<share-name>

You have now successfully enabled AD authentication over SMB and assigned a custom role that provides access to an Azure file share with an AD identity. To grant additional users access to your file share, follow the instructions in the Assign access permissions to use an identity and Configure NTFS permissions over SMB sections.

Update AD account password

If you registered the AD identity/account representing your storage account under an OU that enforces password expiration time, you must rotate the password before the maximum password age. Failing to update the password of the AD account will result in authentication failures to access Azure file shares.

To trigger password rotation, you can run the Update-AzStorageAccountADObjectPassword command from the AzFilesHybrid module. The cmdlet performs actions similar to storage account key rotation. It gets the second Kerberos key of the storage account and uses it to update the password of the registered account in AD. Then it regenerates the target Kerberos key of the storage account and updates the password of the registered account in AD. You must run this cmdlet in an AD domain joined environment.

#Update the password of the AD account registered for the storage account
Update-AzStorageAccountADObjectPassword `
        -RotateToKerbKey kerb2 `
        -ResourceGroupName "<your-resource-group-name-here>" `
        -StorageAccountName "<your-storage-account-name-here>"

Next steps

For more information about Azure Files and how to use AD over SMB, see these resources: