你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

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

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

托管标识是 Azure 自动管理的 Microsoft 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

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

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

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

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

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

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

若要创建新的启用了 SMBOAuth 的存储帐户，请以管理员身份运行以下 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 必须针对服务器 SKU 或任何 Windows 客户端 SKU 运行 Windows Server 2019 或更高版本。请参阅在 Azure 门户中创建 Windows 虚拟机。
在 VM 上启用托管标识。它可以是系统分配的，也可以是用户分配的。如果 VM 同时分配了系统标识和用户分配的标识，则 Azure 默认为系统分配。为了获得最佳结果，只需分配一个。可以在“ 管理 ”选项卡上创建 VM 期间启用系统分配的托管标识。

将内置 RBAC 角色分配给托管标识或应用程序标识

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

按照以下步骤分配内置的 Azure RBAC 角色存储文件数据 SMB MI 管理员，该管理员允许对 Azure 文件中文件和目录的托管标识进行管理员级访问。

导航到包含您想要使用托管身份装载的文件共享的存储帐户。从服务菜单中选择 “访问控制”（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 门户中的存储帐户，然后从服务菜单中选择 “设置>终结点 ”。请务必复制整个 URI，包括尾部斜杠： https://<storage-account-name>.file.core.windows.net/

AzFilesSMBMIClient.exe refresh --uri https://<storage-account-name>.file.core.windows.net/

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

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

AzFilesSmbMIClient.exe refresh --uri https://<storage-account-name>.file.core.windows.net/ --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 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 azfilesauth

配置身份验证

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

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

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

如果 VM 具有用户分配的托管标识，请运行以下命令。请务必将<client-id>替换为托管标识的客户端 ID。如果没有客户端标识，请导航到托管身份并复制客户端标识。

# Get a token from the Azure Instance Metadata Service (IMDS) and store it automatically
sudo azfilesauthmanager set https://<storage_account>.file.core.windows.net --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.windows.net <access-token> 
# Verify the ticket is properly stored
sudo azfilesauthmanager list

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

Windows操作系统
Linux

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

\\<storage-account-name>.file.core.windows.net\<file-share-name>

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

运行以下命令，使用建议的装载选项装载文件共享。请务必将 <storage-account-name> 替换为您的存储账户名称，并将 <file-share-name> 替换为您的文件共享名称。可以在以下配置文件中找到凭据 ID： cat /etc/azfilesauth/config.yaml

sudo mount -t cifs //<storage-account-name>.file.core.windows.net/<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 2025-12-11