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

适用于： ✔️ SMB Azure 文件共享

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

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

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

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

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

优点包括：

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

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

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

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

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

可以在 Windows VM 上配置用户分配的托管标识和系统分配的托管标识。

先决条件

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

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

准备 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>"

在存储帐户上配置托管身份访问属性

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

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

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 门户中验证是否已创建存储帐户和文件共享。

配置托管标识

可以将托管标识与 Windows 或 Linux 配合使用。选择相应的选项卡，然后按照操作系统的说明进行操作。

Windows操作系统
Linux

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

在 Azure VM 上启用托管标识

按照以下步骤在 Azure VM 上启用托管标识。

登录到 Azure 门户并创建 Windows VM。 VM 必须针对服务器版本或任何Windows客户端版本运行Windows Server 2019或更高版本。请参阅在 Azure 门户中创建 Windows 虚拟机。
在 VM 上启用托管标识。它可以是系统分配的，也可以是用户分配的。如果 VM 同时分配了系统标识和用户分配的标识，则 Azure 默认为系统分配。为了获得最佳结果，只需分配一个。可以在“ 管理 ”选项卡上创建 VM 期间启用系统分配的托管标识。

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

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

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

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

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

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

Windows操作系统
Linux

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

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

刷新身份验证凭据

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

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

此命令获取 OAuth 令牌并将其插入 Kerberos 缓存中。当令牌即将过期时，它会自动刷新。可以选择省略refresh。

如果Windows VM 同时配置了用户分配的托管标识和系统分配的托管标识，请使用以下命令指定用户分配的托管标识。将 <client-id> 替换为托管标识的客户端 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

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

tdnf update 
tdnf install azfilesauth

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 具有用户分配的托管标识，请运行以下命令。请务必将<client-id>替换为托管标识的客户端 ID。如果您没有客户端 ID，请访问托管标识并复制客户端 ID。

# Get a token from the Azure Instance Metadata Service (IMDS) and store it automatically
sudo azfilesauthmanager set https://<storage_account>.file.core.chinacloudapi.cn --imds-client-id <client-id>
# Verify the ticket was created properly
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操作系统
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

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

验证装载是否成功：

ls -la /mnt/smb

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

刷新凭据

首次装载文件共享后，启动刷新服务以使凭据保持最新状态。只有在 VM 被分配了用户分配的托管标识时，才能刷新凭据。如果直接提供 OAuth 令牌，则刷新不起作用。

sudo systemctl start azfilesauth

应定期刷新凭据，以避免访问中断。可以使用配置azfilesauthmanager set中所述的命令手动刷新凭据，也可以使用共享库 API 自动刷新凭据。

Troubleshooting

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

Windows操作系统
Linux

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

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

客户端库安装和集成选项

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

Windows操作系统
Linux

对于需要将托管标识集成到其 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 可用作本机 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 访问。

请务必包含公共标头。

有关详细信息，请参阅 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 约定（0 表示成功，非零表示错误）。

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

另请参阅

Last updated on 2026-03-11

通过