使用 Microsoft Entra ID 的托管标识访问 SMB Azure 文件共享（预览版）

适用于： ✔️ SMB 文件共享

本文介绍如何使用托管标识允许Windows和 Linux 虚拟机（VM）通过基于标识的身份验证和Microsoft Entra ID（预览版）来访问 SMB Azure文件共享。

托管标识是Entra ID中的一个标识，由Azure自动管理。通常，您在开发云应用程序时使用托管标识来管理凭据，以便对 Azure 服务进行身份验证。

本指南结束时，将创建一个存储帐户，该存储帐户已准备好使用托管标识进行访问。此外，还了解如何为 VM 创建托管标识并为其生成 OAuth 令牌。然后使用基于托管标识的身份验证和授权挂载文件共享。使用托管标识无需使用存储帐户密钥。

为何使用托管标识进行身份验证？

出于安全原因，我们不建议使用存储帐户密钥访问文件共享。将托管标识分配给 VM 或使用应用程序标识时，可以使用该标识对Azure Files进行身份验证。

优点包括：

增强安全性：不依赖于存储帐户密钥来管理或公开。
简化管理：无需密钥轮换。
精细访问控制：身份级别的基于角色的访问。
自动化友好：可轻松与持续集成和持续交付（CI/CD）管道、Azure Kubernetes Service (AKS) 工作负载和客户应用程序集成。
经济高效：托管标识无需额外的存储成本。

系统分配的托管标识和用户分配的托管标识

Azure提供两种类型的托管标识：系统分配的托管标识和用户分配的托管标识。

系统分配的托管标识仅限于每个资源一个，并绑定到资源的生命周期。可以使用Azure基于角色的访问控制（Azure RBAC）授予对托管标识的权限。托管标识通过 Microsoft Entra ID 进行身份验证，因此无需在代码中存储任何凭据。

用户分配的托管标识使Azure资源无需在代码中存储凭据即可向云服务进行身份验证。将这种类型的托管标识创建为具有其自己的生命周期的独立Azure资源。单个资源（如 VM）可以使用多个用户分配的托管标识。此外，多个 VM 可以共享单个用户分配的托管标识。

尽管可以在单个 VM 上配置用户分配的托管标识和系统分配的托管标识，但我们建议使用一个或另一个。

先决条件

本文假设您拥有一个 Azure 订阅，并且该订阅具有创建存储帐户和分配 Azure RBAC 角色的权限。若要分配角色，需要在所需范围内具有角色分配写入权限（Microsoft.Authorization/roleAssignments/write）。

需要使用托管标识进行身份验证的客户端不应加入任何域。

在存储帐户上配置托管标识的访问属性

若要对托管标识进行身份验证，必须在包含要访问的Azure文件共享的存储帐户上启用 SMBOAuth 属性。建议为此创建新的存储帐户。仅当现有存储帐户未配置任何其他标识源时，才能使用。

PowerShell
Azure CLI

若要使用 Azure PowerShell 在存储帐户上启用 SMBOAuth 属性，请先准备 PowerShell 环境。

以管理员身份打开 PowerShell 并运行以下命令以设置 PowerShell 执行策略：

Set-ExecutionPolicy Unrestricted -Scope CurrentUser

确保具有最新的 PowerShellGet 模块：

Install-Module PowerShellGet -Force -AllowClobber

安装 Az 模块（如果尚未安装）：

Install-Module -Name Az -Repository PSGallery -Force 
Import-Module Az

登录到Azure：

Connect-AzAccount -Environment AzureChinaCloud

通过指定您的订阅 ID（推荐），选择您的订阅：

Set-AzContext -SubscriptionId "<subscription-ID>"

还可以通过指定订阅名称来选择订阅：

Set-AzContext -Subscription "<subscription-name>"

创建存储帐户

若要创建新的启用了 SMBOAuth 存储帐户，请以管理员身份运行以下 PowerShell 命令。将 <resource-group>、<storage-account-name> 和 <region> 替换为你自己的值。如果需要，可以指定其他 SkuName 值。

New-AzStorageAccount -ResourceGroupName <resource-group> -Name <storage-account-name> -SkuName Standard_LRS -Location <region> -EnableSmbOAuth $true

若要在现有存储帐户上启用 SMBOAuth ，请运行以下 PowerShell 命令。将 <resource-group> 和 <storage-account-name> 替换为自定义值。

Set-AzStorageAccount -ResourceGroupName <resource-group> -Name <storage-account-name> -EnableSmbOAuth $true

如果错误表明策略不允许资源，则可能在订阅上设置了一个不允许 Set-AzStorageAccount的策略。若要解决此问题，请使用以下命令重试：

Set-AzStorageAccount -ResourceGroupName <resource-group> -Name <storage-account-name> -EnableSmbOAuth $true -AllowBlobPublicAccess $false

接下来，在存储帐户上创建 SMB 文件共享。将 <resource-group>、<storage-account-name> 和 <file-share-name> 替换为你自己的值。

$storageAccount = Get-AzStorageAccount -ResourceGroupName <resource-group> -Name <storage-account-name>
New-AzStorageShare -Name <file-share-name> -Context $storageAccount.Context

现在，你已准备好一个存储帐户和文件共享，以便进行 SMB OAuth 身份验证。在Azure门户中验证是否已创建存储帐户和文件共享。

若要使用 Azure CLI 在存储帐户上启用 SMBOAuth 属性，请首先登录到Azure：

az login

通过指定您的订阅 ID 来选择您的订阅：

az account set --subscription "<subscription-ID>"

创建存储帐户

若要创建新的启用了 SMBOAuth 存储帐户，请运行以下命令。将 <resource-group>、<storage-account-name> 和 <region> 替换为你自己的值。

az storage account create --resource-group <resource-group> --name <storage-account-name> --location <region> --sku Standard_LRS --enable-smb-oauth true

若要在现有存储帐户上启用 SMBOAuth，请运行以下命令。将 <resource-group> 和 <storage-account-name> 替换为自定义值。

az storage account update --resource-group <resource-group> --name <storage-account-name> --enable-smb-oauth true

接下来，在存储帐户上创建 SMB 文件共享。将 <storage-account-name> 和 <file-share-name> 替换为自定义值。

az storage share create --account-name <storage-account-name> --name <file-share-name>

现在，你已准备好一个存储帐户和文件共享，以便进行 SMB OAuth 身份验证。在Azure门户中验证是否已创建存储帐户和文件共享。

配置托管标识

可以在 Windows 或 Linux 中使用托管标识。选择本文开头的操作系统，并按照说明进行操作。

此处所述的启用步骤适用于Azure VM。如果要在非Azure Windows计算机上（本地或其他云）上启用托管标识，则必须将其载入Azure Arc并分配托管标识。还可以使用应用程序标识而不是在 VM 或Windows设备上使用托管标识进行身份验证。

在 Azure VM 上启用托管身份

托管标识可以是系统分配的，也可以是用户分配的。如果 VM 同时具有系统分配的托管标识和用户分配的托管标识，Azure默认为系统分配的标识。为了获得最佳结果，只需分配一个。

启用系统分配的托管标识

按照以下步骤在Azure中运行的Windows VM 上启用系统分配的托管标识：

登录到Azure门户并创建Windows VM。 VM 必须针对服务器版本或任何Windows客户端版本运行Windows Server 2019或更高版本。请参阅在 Azure 门户中创建Windows虚拟机。
可以在“ 管理 ”选项卡上创建 VM 期间启用系统分配的托管标识。

创建新 VM 时，如何在 Azure 门户中启用系统分配的托管标识的截图。

启用用户分配的托管标识

登录到 Azure 门户并按照步骤创建用户分配的托管标识。
转到刚刚创建的用户分配的托管标识并复制 客户端 ID 值。稍后需要用到此值。

将内置的 RBAC 角色分配给托管身份或应用身份

启用托管标识后，通过 Azure RBAC 授予所有必要的权限。若要分配角色，请在所需范围内以具有角色分配写入权限的用户身份登录。

按照以下步骤分配内置 Azure RBAC 角色Storage 文件数据 SMB MI 管理员。此角色为Azure Files中的文件和目录上的托管标识提供管理员级访问权限。

请转到包含文件共享的存储帐户，然后通过托管身份进行装载。在服务菜单上，选择Access Control （IAM）。
在“授予对此资源的访问权限”下选择“添加角色分配”。
在“ 角色 ”选项卡上的 “作业功能角色”下，搜索并选择 “存储文件数据 SMB MI 管理员”。然后选择“ 下一步”。
在“成员”选项卡上的“分配访问权限到”下，选择 VM 或 Azure Arc 标识的托管标识。对于应用程序标识，请选择 “用户”、“组”或服务主体。
在 “成员”下，选择“ + 选择成员”。
对于 Azure VM 或 Azure Arc 标识，请选择您的 VM 或 Windows 设备的托管标识。对于应用程序标识，请搜索并选择应用程序标识。选择选择。
请确认托管标识或应用程序标识是否列出在成员下。选择“下一步”。
选择 “查看 + 分配 ”，将角色分配添加到存储帐户。

将用户分配的托管标识添加到 VM

如果创建了用户分配的托管标识，请按照以下步骤将其添加到 VM：

转到虚拟机 (VM)。在服务菜单上的 “安全性”下，选择“ 标识”。
选择“ 用户分配 ”选项卡，然后选择“ 添加用户分配的托管标识”。选择创建的托管标识，然后选择“ 添加”。

若要在 Azure 中运行的 Linux VM 上配置托管标识，请执行以下步骤。 VM 必须运行Azure Linux 3.0、Ubuntu 22.04、Ubuntu 24.04、RHEL 9.6+ 或 SLES 15 SP6+。

在 Azure VM 上启用托管身份

启用系统分配的托管标识

登录到Azure门户。
可以在 vm 创建期间在 Management 选项卡上启用系统分配的托管标识。请参阅在 Azure 门户中创建 Linux 虚拟机。

创建新 VM 时，如何在 Azure 门户中启用系统分配的托管标识的截图。

启用用户分配的托管标识

登录到 Azure 门户，并按照步骤创建用户分配的托管标识。
转到刚刚创建的用户分配的托管标识并复制 客户端 ID 值。稍后需要用到此值。

将内置 RBAC 角色分配给托管标识

请转到包含文件共享的存储帐户，然后通过托管身份进行装载。在服务菜单上，选择Access Control （IAM）。
在“授予对此资源的访问权限”下选择“添加角色分配”。
在“ 角色 ”选项卡上的 “作业功能角色”下，搜索并选择 “存储文件数据 SMB MI 管理员”。然后选择“ 下一步”。
在“成员”选项卡上的“将访问权限分配给”部分下，选择“托管标识”。
在 “成员”下，选择“ + 选择成员”。此时会显示 “选择托管标识 ”窗格。
在 “托管标识”下，选择托管标识，然后选择 “选择”。
验证托管身份是否列在《成员》下。选择“下一步”。
选择 “查看 + 分配 ”，将角色分配添加到存储帐户。

将用户分配的托管标识添加到 VM

如果创建了用户分配的托管标识，请按照以下步骤将其添加到 VM：

转到虚拟机 (VM)。在服务菜单上的 “安全性”下，选择“ 标识”。
选择“ 用户分配 ”选项卡，然后选择“ 添加用户分配的托管标识”。选择创建的托管标识，然后选择“ 添加”。

准备客户端以使用托管标识进行身份验证

对于 Windows 和 Linux 客户端，准备系统以使用托管标识身份验证装载文件共享的步骤有所不同。客户端不应加入域。

若要准备客户端 VM 或Windows设备以使用托管标识进行身份验证，请执行以下步骤：

以管理员身份登录到分配了托管标识的 VM 或设备，并打开 PowerShell 窗口。需要 PowerShell 5.1+ 或 PowerShell 7+。
安装 Azure Files SMB 托管标识客户端 PowerShell 模块并将其导入：
```
Install-Module AzFilesSmbMIClient 
Import-Module AzFilesSmbMIClient 
```
运行以下命令来检查当前的 PowerShell 执行策略：
```
Get-ExecutionPolicy -List 
```
如果 CurrentUser 上的执行策略是 Restricted 或 Undefined，请将其更改为 RemoteSigned。如果执行策略为RemoteSigned、Default、AllSigned或BypassUnrestricted，则可以跳过此步骤。
```
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 
```

刷新身份验证凭据

在使用托管标识装载文件共享之前，请先刷新身份验证凭据并指定您的存储帐户端点。若要复制存储帐户 URI，请转到Azure门户中的存储帐户，然后从服务菜单中选择Settings>Endpoints。请务必复制整个 URI，包括尾部斜杠： https://<storage-account-name>.file.core.chinacloudapi.cn/

对于系统分配的托管标识，运行以下命令以获取 OAuth 令牌，将其插入 Kerberos 缓存中，并在令牌即将过期时自动刷新。可以选择省略 refresh。

AzFilesSmbMIClient.exe refresh --uri https://<storage-account-name>.file.core.chinacloudapi.cn/

对于用户分配的托管标识，需要指定客户端 ID。用托管标识的客户端 ID 替换 <client-id>。

AzFilesSmbMIClient.exe refresh --uri https://<storage-account-name>.file.core.chinacloudapi.cn/ --clientId <client-id>

小窍门

若要查看完整的使用情况信息和示例，请运行可执行文件而不带任何参数： AzFilesSmbMIClient.exe

若要准备 Linux VM 以使用托管标识进行身份验证，请执行以下步骤。

下载并安装身份验证包

包位置和安装步骤因 Linux 分发版而异。

Azure Linux 3.0

运行以下命令，在 Azure Linux 3.0 上安装 azfilesauth：

tdnf update 
tdnf install azfilesauth

RHEL 9.6+

运行以下命令以在 azfilesauth RHEL 9.6+ 上安装：

curl -sSL -O https://packages.microsoft.com/config/$(source /etc/os-release && echo "$ID/${VERSION_ID%%.*}")/packages-microsoft-prod.rpm
sudo rpm -i packages-microsoft-prod.rpm
rm packages-microsoft-prod.rpm
dnf update
dnf install -y azfilesauth

有时，RHEL 可能会阻止内核调用对凭据缓存文件的访问。如果发生故障，请参阅 /var/log/messages 了解潜在原因。

默认情况下，RHEL 使用持久性凭据或 KCM 缓存。可以切换到基于文件的缓存用于 azfilesauth:

  sudo tee /etc/krb5.conf.d/00-azfilesauth.conf > /dev/null <<EOF
  [libdefaults]
    default_ccache_name = FILE:/tmp/krb5cc_%{uid}
  EOF

SLES 15 SP6+

运行以下命令以在 SLES 15 SP6+ 上安装azfilesauth：

curl -sSL -O https://packages.microsoft.com/config/sles/15/packages-microsoft-prod.rpm
sudo rpm -i packages-microsoft-prod.rpm
rm packages-microsoft-prod.rpm
sudo zypper refresh
sudo zypper install -y azfilesauth

SLES 15 SP6+ 默认使用持久性凭据或 KCM 缓存。可以切换到基于文件的缓存用于 azfilesauth:

  sudo tee /etc/krb5.conf.d/00-azfilesauth.conf > /dev/null <<EOF
  [libdefaults]
    default_ccache_name = FILE:/tmp/krb5cc_%{uid}
  EOF

Ubuntu 22.04

运行以下命令以在 azfilesauth Ubuntu 22.04 上安装：

curl -sSL -O https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
# the above steps update the sources.list
sudo apt-get update
sudo apt-get install -y azfilesauth

Ubuntu 24.04

运行以下命令以在 azfilesauth Ubuntu 24.04 上安装：

curl -sSL -O https://packages.microsoft.com/config/ubuntu/24.04/packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
# the above steps update the sources.list
sudo apt-get update
sudo apt-get install -y azfilesauth

配置身份验证

有两个选项可用于在 Linux 上配置身份验证：

使用 VM 托管标识：如果 VM 分配了托管标识，请选择此选项。
直接提供 OAuth 令牌：如果你自己管理 OAuth 令牌，请选择此选项。

选项 1：使用虚拟机托管的身份标识

可以使用系统分配的托管标识或用户分配的托管标识来配置身份验证。

如果 VM 具有用户分配的托管标识，请运行以下命令，从Azure实例元数据服务（IMDS）获取令牌并自动存储该令牌。请将 <storage-account-name> 替换为你的存储帐户名称。将 <client-id> 替换为你的托管标识的客户端 ID。如果没有客户端 ID，请进入 Azure 门户中的托管身份，复制该客户端 ID。

sudo azfilesauthmanager set https://<storage-account-name>.file.core.chinacloudapi.cn --imds-client-id <client-id>

如果 VM 具有系统分配的托管标识，请使用 --system 标志，并且不提供客户端 ID：

sudo azfilesauthmanager set https://<storage-account-name>.file.core.chinacloudapi.cn --system

验证票证是否已正确创建：

sudo azfilesauthmanager list

选项 2：直接提供 OAuth 令牌

如果你自己管理令牌，请直接提供 OAuth 令牌。 aud 令牌的（受众）值必须为https://storage.azure.com（且不能包含尾随正斜杠），而不是https://storage.azure.com/，以便装载文件共享。

运行以下命令。将 <storage-account-name> 和 <access-token> 替换为自定义值。

# Insert the token into your credential cache
sudo azfilesauthmanager set https://<storage-account-name>.file.core.chinacloudapi.cn <access-token> 
# Verify the ticket is properly stored
sudo azfilesauthmanager list

现在可以在 Windows 或 Linux 上装载文件共享，而无需使用存储帐户密钥。

在Windows客户端上，可以通过在Windows文件资源管理器中输入以下路径，使用 UNC 路径直接访问Azure文件共享。将 <storage-account-name> 替换为storage帐户名，并将 <file-share-name> 替换为文件共享名称。

\\<storage-account-name>.file.core.chinacloudapi.cn\<file-share-name>

有关详细信息，请参阅在 Windows 上挂载 SMB Azure 文件共享。

运行以下命令，使用建议的装载选项装载文件共享。将 <storage-account-name> 替换为storage帐户名，并将 <file-share-name> 替换为文件共享名称。您可以在以下配置文件中找到您的凭据 ID：cat /etc/azfilesauth/config.yaml 对于用户分配的托管标识，请使用 username=<client-id> 挂载选项包括托管标识的客户端 ID。对于系统分配的托管标识，请省略装载选项 username=<client-id>。

sudo mount -t cifs //<storage-account-name>.file.core.chinacloudapi.cn/<file-share-name> /mnt/smb -o sec=krb5,cruid=<credential-id>,username=<client-id>,dir_mode=0755,file_mode=0755,serverino,nosharesock,mfsymlinks,actimeo=30

验证装载是否成功：

ls -la /mnt/smb

有关详细信息，请参阅在 Linux 客户端上装载 SMB Azure文件共享。

刷新凭据

若要防止访问中断，应定期刷新凭据。刷新服务会根据需要自动检测和续订凭据。

首次装载文件共享后，启动刷新服务：

sudo systemctl start azfilesrefresh

为了确保服务每次启动时自动运行：

sudo systemctl enable --now azfilesrefresh

自动凭据刷新需要分配给 VM 的托管标识。如果直接提供 OAuth 令牌，则必须使用 azfilesauthmanager set 配置身份验证中所述的命令手动刷新凭据，或者通过共享库 API 以编程方式刷新凭据。

Troubleshooting

Windows和 Linux 客户端的故障排除步骤有所不同。

如果在Windows上装载文件共享时遇到问题，请按照以下步骤启用详细日志记录并收集诊断信息：

在 Windows 客户端上，使用注册表编辑器将 Data 级别的 详细程度 设置为 0x00000004 (4) Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Azure\Storage\Files\SmbAuth。
请再次尝试装载共享并重现该错误。
现在应该有一个名为 AzFilesSmbMILog.log 的文件。将日志文件发送到 Azure Files 团队以获取帮助。

如果在 Linux 上装载文件共享时遇到问题，请按照 sMB 诊断步骤操作。

客户端库安装和集成选项

以下信息适用于需要将托管标识集成到其应用程序中的开发人员。

对于需要将托管标识集成到其Windows应用程序的开发人员，可以使用多种实现方法。选择的方法取决于应用程序体系结构和要求。

托管程序集集成：NuGet软件包

对于.NET应用程序，Microsoft.Azure。AzFilesSmbMI NuGet 包包含一个托管程序集（Microsoft.Azure.AzFilesSmbMI.dll），提供对 SMB OAuth 身份验证功能的直接访问。将此方法用于 C# 和其他基于.NET的应用程序。

若要安装程序集，请使用 Install-Package Microsoft.Azure.AzFilesSmbMI -version 1.2.3168.94。

本机 DLL 集成

对于需要直接 API 访问的本机应用程序，AzFilesSmbMIClient 可用作 native DLL。此选项特别适用于需要较低级别的集成的 C/C++ 应用程序或系统。请参阅 Windows 实现和 API 参考（本机头文件）。

本机 API 方法

本地 DLL 导出以下核心方法以进行凭据管理：

extern "C" AZFILESSMBMI_API HRESULT SmbSetCredential( 
    _In_  PCWSTR pwszFileEndpointUri, 
    _In_  PCWSTR pwszOauthToken, 
    _In_  PCWSTR pwszClientID, 
    _Out_ PDWORD pdwCredentialExpiresInSeconds 
); 
extern "C" AZFILESSMBMI_API HRESULT SmbRefreshCredential( 
    _In_ PCWSTR pwszFileEndpointUri, 
    _In_ PCWSTR pwszClientID 
); 
extern "C" AZFILESSMBMI_API HRESULT SmbClearCredential( 
    _In_ PCWSTR pwszFileEndpointUri 
);

Linux 开发人员可以使用随包自动安装的 azfilesauth 共享库。可以针对 C/C++ 应用程序中的库进行链接，以便进行直接 API 访问。

请务必包含 public 标头。

有关详细信息，请参阅 AzFilesAuthenticator 项目。

共享库 API 方法

共享库导出以下用于凭据管理的核心方法：

#ifdef __cplusplus
extern "C" {
#endif

int extern_smb_set_credential_oauth_token(char* file_endpoint_uri,
                                                char* auth_token,
                                                unsigned int* credential_expires_in_seconds);

int extern_smb_clear_credential(char* file_endpoint_uri);

int extern_smb_list_credential(bool is_json);

const char* extern_smb_version();

#ifdef __cplusplus
}
#endif

API 说明

下表列出了 API 命令及其用法。返回的值遵循标准 C 约定（成功为零，错误为非零）。

命令	说明
`extern_smb_set_credential_oauth_token()`	为特定存储端点设置 OAuth 令牌凭据。
`extern_smb_clear_credential()`	删除存储端点的已存储凭据。
`extern_smb_list_credential()`	列出所有存储的凭据。
`extern_smb_version()`	返回库的版本 `azfilesauth` 字符串。

Last updated on 2026-04-10

使用 Microsoft Entra ID 的托管标识访问 SMB Azure 文件共享（预览版）

为何使用托管标识进行身份验证？

系统分配的托管标识和用户分配的托管标识

先决条件

在存储帐户上配置托管标识的访问属性

创建存储帐户

配置托管标识

在 Azure VM 上启用托管身份

启用系统分配的托管标识

启用用户分配的托管标识

将内置的 RBAC 角色分配给托管身份或应用身份

将用户分配的托管标识添加到 VM

在 Azure VM 上启用托管身份

启用系统分配的托管标识

启用用户分配的托管标识

将内置 RBAC 角色分配给托管标识

将用户分配的托管标识添加到 VM

准备客户端以使用托管标识进行身份验证

刷新身份验证凭据

下载并安装身份验证包

Azure Linux 3.0

RHEL 9.6+

SLES 15 SP6+

Ubuntu 22.04

Ubuntu 24.04

配置身份验证

选项 1：使用虚拟机托管的身份标识

选项 2：直接提供 OAuth 令牌

挂载文件共享

刷新凭据

Troubleshooting

客户端库安装和集成选项

托管程序集集成：NuGet软件包

本机 DLL 集成

本机 API 方法

共享库 API 方法

API 说明

相关内容

其他资源