|
| 1 | +--- |
| 2 | +title: How to use managed identities with Azure File Sync |
| 3 | +description: Learn how to configure Azure File Sync to use managed identities. |
| 4 | +author: khdownie |
| 5 | +ms.service: azure-file-storage |
| 6 | +ms.topic: conceptual |
| 7 | +ms.date: 10/30/2024 |
| 8 | +ms.author: kendownie |
| 9 | +--- |
| 10 | + |
| 11 | +# How to use managed identities with Azure File Sync (preview) |
| 12 | + |
| 13 | +Azure File Sync support for system-assigned managed identities is now in preview. |
| 14 | + |
| 15 | +Managed Identity support eliminates the need for shared keys as a method of authentication by utilizing a system-assigned managed identity provided by Microsoft Entra ID. |
| 16 | + |
| 17 | +When you enable this configuration, the system-assigned managed identities will be used for the following scenarios: |
| 18 | +- Storage Sync Service authentication to Azure file share |
| 19 | +- Registered server authentication to Azure file share |
| 20 | +- Registered server authentication to Storage Sync Service |
| 21 | + |
| 22 | +To learn more about the benefits of using managed identities, see [Managed identities for Azure resources](/entra/identity/managed-identities-azure-resources/overview). |
| 23 | + |
| 24 | +To configure your Azure File Sync deployment to utilize system-assigned managed identities, please follow the guidance in the subsequent sections. |
| 25 | + |
| 26 | +## Prerequisites |
| 27 | +- You need to have a **Storage Sync Service** [deployed](file-sync-deployment-guide.md) with at least one **registered server**. |
| 28 | +- **Azure File Sync agent version 19.1.0.0 or later** must be installed on the registered server. |
| 29 | +- On your **storage accounts** used by Azure File Sync: |
| 30 | + - You must be a **member of the Owner management role** or have “Microsoft.Authorization/roleassignments/write” permissions. |
| 31 | + - **Allow Azure services on the trusted services list to access this storage account** exception must be enabled for preview. [Learn more](file-sync-networking-endpoints.md#grant-access-to-trusted-azure-services-and-restrict-access-to-the-storage-account-public-endpoint-to-specific-virtual-networks) |
| 32 | + - **Allow storage account key access** must be enabled for preview. To check this setting, navigate to your storage account and select **Configuration** under the Settings section. |
| 33 | +- **Az.StorageSync [PowerShell module](https://www.powershellgallery.com/packages/Az.StorageSync) version 2.2.0 or later** must be installed on the machine that will be used to configure Azure File Sync to use managed identities. |
| 34 | + - To install the latest Az.StorageSync PowerShell module, run the following command from an elevated PowerShell window: |
| 35 | + |
| 36 | + ```powershell |
| 37 | + Install-Module Az.StorageSync -Force |
| 38 | + ``` |
| 39 | + |
| 40 | +## Regional availability |
| 41 | + |
| 42 | +Azure File Sync support for system-assigned managed identities (preview) is available in [all Azure Public and Gov regions](https://azure.microsoft.com/global-infrastructure/locations/) that support Azure File Sync. |
| 43 | + |
| 44 | +## Enable a system-assigned managed identity on your registered servers |
| 45 | +Before you can configure Azure File Sync to use managed identities, your registered servers must have a system-assigned managed identity that will be used to authenticate to the Azure File Sync service and Azure file shares. |
| 46 | + |
| 47 | +To enable a system-assigned managed identity on a registered server that has the Azure File Sync v19 agent installed, perform the following steps: |
| 48 | +- If the server is hosted outside of Azure, it must be an **Azure Arc-enabled server** to have a system-assigned managed identity. For more information on Azure Arc-enabled servers and how to install the Azure Connected Machine agent, see: [Azure Arc-enabled servers Overview](/entra/identity/managed-identities-azure-resources/overview). |
| 49 | +- If the server is an Azure virtual machine, **enable the system-assigned managed identity setting on the VM**. For more information, see: [Configure managed identities on Azure virtual machines](/entra/identity/managed-identities-azure-resources/how-to-configure-managed-identities?pivots=qs-configure-portal-windows-vm#enable-system-assigned-managed-identity-on-an-existing-vm). |
| 50 | + |
| 51 | +> [!NOTE] |
| 52 | +> - At least one registered server must have a system-assigned managed identity before you can configure the Storage Sync Service to use a system-assigned identity. |
| 53 | +> - Once the Storage Sync Service is configured to use managed identities, registered servers that do not have a system-assigned managed identity will continue to use a shared key to authenticate to your Azure file shares. |
| 54 | + |
| 55 | +### How to check if your registered servers have a system-assigned managed identity |
| 56 | + |
| 57 | +To check if your registered servers have a system-assigned managed identity, run the following PowerShell command: |
| 58 | + |
| 59 | +```powershell |
| 60 | +Get-AzStorageSyncServer -ResourceGroupName <string> -StorageSyncServiceName <string> |
| 61 | +``` |
| 62 | + |
| 63 | +Verify the **LatestApplicationId** property has a GUID which indicates the server has a system-assigned managed identity but is not currently configured to use the managed identity. |
| 64 | + |
| 65 | +If the value for the **ActiveAuthType** property is **Certificate** and the **LatestApplicationId** does not have a GUID, the server does not have a system-assigned managed identity and will use shared keys to authenticate to the Azure file share. |
| 66 | + |
| 67 | +> [!NOTE] |
| 68 | +> Once a server is configured to use the system-assigned managed identity by following the steps in the following section, the **LatestApplicationId** property is no longer used (will be empty), the **ActiveAuthType** property value will be changed to **ManagedIdentity**, and the **ApplicationId** property will have a GUID which is the system-assigned managed identity. |
| 69 | +
|
| 70 | +## Configure your Azure File Sync deployment to use system-assigned managed identities |
| 71 | +To configure the Storage Sync Service and registered servers to use system-assigned managed identities, run the following command from an elevated PowerShell window: |
| 72 | + |
| 73 | +```powershell |
| 74 | +Set-AzStorageSyncServiceIdentity -ResourceGroupName <string> -StorageSyncServiceName <string> -Verbose |
| 75 | +``` |
| 76 | +The **Set-AzStorageSyncServiceIdentity** cmdlet performs the following steps for you and will take several minutes (or longer for large topologies) to complete: |
| 77 | +- Validates at least one registered server has a system assigned managed identity. |
| 78 | + - The cmdlet will stop at this step if there are no registered servers with a system-assigned managed identity. |
| 79 | +- Enables a system-assigned managed identity for Storage Sync Service resource. |
| 80 | +- Grants the Storage Sync Service system-assigned managed identity access to your Storage Accounts (Storage Account Contributor role). |
| 81 | +- Grants the Storage Sync Service system-assigned managed identity access to your Azure file shares (Storage File Data Privileged Contributor role). |
| 82 | +- Grants the registered server(s) system-assigned managed identity access to the Azure file shares (Storage File Data Privileged Contributor role). |
| 83 | +- Configures the Storage Sync Service to use system-assigned managed identity. |
| 84 | +- Configures registered server(s) to use system-assigned managed identity. |
| 85 | + |
| 86 | +Use the **Set-AzStorageSyncServiceIdentity** cmdlet anytime you need to configure additional registered servers to use managed identities. |
| 87 | + |
| 88 | +> [!NOTE] |
| 89 | +> Once the registered server(s) are configured to use a system-assigned managed identity, it can take up to one hour before the server uses the system-assigned managed identity to authenticate to the Storage Sync Service and file shares. |
| 90 | +
|
| 91 | +### How to check if the Storage Sync Service is using a system-assigned managed identity |
| 92 | +To check if the Storage Sync Service is using a system-assigned managed identity, run the following command from an elevated PowerShell window: |
| 93 | + |
| 94 | +```powershell |
| 95 | +Get-AzStorageSyncService -ResourceGroupName <string> -StorageSyncServiceName <string> |
| 96 | +``` |
| 97 | +Verify the value for the **UseIdentity** property is **True**. If the value is **False**, the Storage Sync Service is using shared keys to authenticate to the Azure file shares. |
| 98 | + |
| 99 | +### How to check if a registered server is configured to use a system-assigned managed identity |
| 100 | +To check if a registered server is configured to use a system-assigned managed identity, run the following command from an elevated PowerShell window: |
| 101 | + |
| 102 | +```powershell |
| 103 | +Get-AzStorageSyncServer -ResourceGroupName <string> -StorageSyncServiceName <string> |
| 104 | +``` |
| 105 | +Verify the **ApplicationId** property has a GUID which indicates the server is configured to use the managed identity. The value for the **ActiveAuthType** property will be updated to **ManagedIdentity** once the server is using the system-assigned managed identity. |
| 106 | + |
| 107 | +> [!NOTE] |
| 108 | +> Once the registered server(s) are configured to use a system-assigned managed identity, it can take up to one hour before the server uses the system-assigned managed identity to authenticate to the Storage Sync Service and Azure file shares. |
| 109 | +
|
| 110 | +## More information |
| 111 | +Once the Storage Sync Service and registered server(s) are configured to use a system-assigned managed identity: |
| 112 | + - New endpoints (cloud or server) that are created will use a system-assigned managed identity to authenticate to the Azure file share. |
| 113 | + - Use the Set-AzStorageSyncServiceIdentity cmdlet anytime you need to configure additional registered servers to use managed identities. |
0 commit comments