通过 REST 使用 Microsoft Entra ID 和 Azure 文件存储 OAuth 访问 Azure 文件共享

通过使用 Azure Files OAuth over REST，用户和应用程序可以通过 OAuth 身份验证协议获取对Azure文件共享的管理员级读取和写入访问权限。 此访问方法使用 Entra ID 进行基于 REST API 的访问。 用户、组、第一方服务（例如 Azure 门户）以及使用 REST 接口的第三方服务和应用程序现在可以通过 Microsoft Entra 帐户使用 OAuth 身份验证和授权来访问 Azure 文件中的数据。 调用 REST API 的 PowerShell cmdlet 和 Azure CLI 命令还可以使用 OAuth 访问 Azure 文件。 必须使用显式标头调用 REST API，以指明你使用其他特权的意图。 此要求也适用于 Azure PowerShell 和 Azure CLI 访问权限。

局限性

仅支持对 REST API 版本 2022-11-02 及更高版本使用 Microsoft Entra ID 授权文件数据操作。

REST API 版本 2024-11-04 及更高版本提供了对 Azure 文件存储 REST 数据平面 API 的 Azure 文件存储 OAuth over REST 支持，这些 API 用于管理 FileService 和 FileShare 资源。

请参阅 Azure 存储的版本控制。

客户用例

对于以下情况，通过 REST API 接口进行 Azure 文件存储 OAuth 身份验证和授权可使客户受益。

应用程序开发和服务集成

OAuth 身份验证和授权可让开发人员生成应用程序，以使用 Microsoft Entra ID 中的用户或应用程序标识来访问 Azure 存储 REST API。

客户和合作伙伴还可以启用第一方和第三方服务，安全、透明地配置对客户存储帐户的必要访问权限。

DevOps 工具（如 Azure 门户、PowerShell、CLI、AzCopy 和存储资源管理器）可以使用用户的标识来管理数据，而无需管理或分发存储访问密钥。

托管标识

具有应用程序和托管标识并需要访问文件共享数据以实现备份、还原或审核目的的客户可以从 OAuth 身份验证和授权中受益。 为每个标识强制实施文件级和目录级权限会增加复杂性，并且可能与某些工作负载不兼容。 例如，客户可能希望授权备份解决方案服务访问 Azure 文件共享，且对所有文件具有只读访问权限，而不考虑特定于文件的权限。

存储帐户密钥替换

与共享密钥访问相比，Microsoft Entra ID 提供了更高的安全性和易用性。 使用 OAuth 身份验证和授权替换存储帐户密钥访问，以访问具有读取全部/写入全部权限的 Azure 文件共享。 此方法还能更好地审核和跟踪特定用户访问。

数据操作的特权访问和访问权限

若要使用 Azure Files OAuth over REST 功能，请在分配给用户、组或服务主体的 RBAC 角色中包含额外的权限。 此功能引入了两个新的数据操作：

Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action

Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action

使用 OAuth 调用 REST API 的用户、组或服务主体必须在授予数据访问权限的角色中被分配 readFileBackupSemantics 或 writeFileBackupSemantics 操作。 这是使用此功能的一项要求。 若要详细了解有关调用特定文件服务操作所需的权限，请参见用于调用数据操作的权限。

此功能提供两个包含这些操作的内置角色。

这些角色类似于存储文件数据 SMB 共享读取者和存储文件数据 SMB 共享提升的参与者内置角色，但存在一些差异：

• 新角色包含 OAuth 访问所需的额外数据操作。

• 当分配了 存储文件数据特权读取者 或 存储文件数据特权参与者 角色的用户、组或服务主体使用 OAuth 调用 FilesREST 数据 API 时：

  • 存储文件数据特权读取者：对所有已配置存储帐户的共享中的所有数据具有完全读取访问权限，而不考虑设置的文件/目录级别 NTFS 权限。
  • 存储文件数据特权参与者：对所有已配置存储帐户的共享中的所有数据具有完全读取、写入、修改 ACL、删除访问权限，而不考虑设置的文件/目录级别 NTFS 权限。

• 通过使用这些特殊权限和角色，系统将绕过任何文件或目录级权限，并授予对文件共享数据的访问权限。

通过使用新的角色和数据操作，此功能提供存储帐户范围的特权，覆盖存储帐户中所有文件共享下文件和文件夹的所有权限。 但是，新角色仅包含访问数据服务的权限。 它们不包含任何访问文件共享管理服务的权限（文件共享操作）。 若要使用此功能，请确保你有权访问：

• 存储帐户
• 文件共享管理服务
• 数据服务（文件共享中的数据）

许多 内置角色 提供对管理服务的访问权限。 也可以使用相应的权限创建自定义角色。 若要详细了解基于角色的访问控制，请参阅 Azure RBAC。 有关如何定义内置角色的详细信息，请参阅了解角色定义。

对于文件共享资源类型，相应的 RBAC 范围在控制平面（管理操作）中使用 shares，但在数据平面（数据操作）中使用 fileshares。 如果尝试使用包含shares的文件共享资源 ID 在 RBAC 作用域或数据操作字符串中，它不起作用。 必须在 RBAC 分配范围内使用 fileshares，例如：

• /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Storage/storageAccounts/<storage-account-name>/fileServices/default/fileshares/<share-name>

授予对应用程序代码中文件数据的访问权限

Azure 标识客户端库简化了通过 Azure SDK 获取 OAuth 2.0 访问令牌以使用 Entra ID 进行授权的过程。 适用于 .NET、Java、Python、JavaScript 和 Go 的 Azure 存储客户端库的最新版本与每种语言的 Azure 标识库集成，以提供一种简单且安全的方法来获取访问令牌以授权来自 Azure 文件服务的请求。

Azure 标识客户端库的优点在于，它使你可以使用相同的代码来获取访问令牌，无论你的应用程序是在开发环境中运行还是在 Azure 中运行。 Azure 标识客户端库返回安全主体的访问令牌。 当代码在Azure中运行时，安全主体可以是Azure资源、服务主体或用户或组的托管标识。 在开发环境中，客户端库为用户主体或服务主体提供用于测试的访问令牌。

Azure 标识客户端库将访问令牌封装在令牌凭据中。 使用令牌凭据获取服务客户端对象，以便对 Azure 文件服务执行授权操作。

下面的代码示例演示如何使用 Entra ID 授权客户端对象，并在目录和文件级别执行作。 此示例假定已存在文件共享。

using Azure.Core;
using Azure.Identity;
using Azure.Storage.Files.Shares;
using Azure.Storage.Files.Shares.Models;

namespace FilesOAuthSample
{
    internal class Program
    {
        static async Task Main(string[] args)
        {
            string tenantId = "";
            string appId = "";
            string appSecret = "";
            string entraEndpoint = "";
            string accountUri = "https://<storage-account-name>.file.core.chinacloudapi.cn/";
            string shareName = "test-share";
            string directoryName = "test-directory";
            string fileName = "test-file";  

            TokenCredential tokenCredential = new ClientSecretCredential(
                tenantId,
                appId,
                appSecret,
                new TokenCredentialOptions()
                {
                    AuthorityHost = new Uri(entraEndpoint)
                });

            // Set client options
            ShareClientOptions clientOptions = new ShareClientOptions();
            clientOptions.AllowTrailingDot = true;
            clientOptions.AllowSourceTrailingDot = true;

            // x-ms-file-intent=backup will automatically be applied to all APIs
            // where it is required in derived clients
            clientOptions.ShareTokenIntent = ShareTokenIntent.Backup;

            ShareServiceClient shareServiceClient = new ShareServiceClient(
                new Uri(accountUri),
                tokenCredential,
                clientOptions);

            ShareClient shareClient = shareServiceClient.GetShareClient(shareName);
            ShareDirectoryClient directoryClient = shareClient.GetDirectoryClient(directoryName);
            await directoryClient.CreateAsync();

            ShareFileClient fileClient = directoryClient.GetFileClient(fileName);
            await fileClient.CreateAsync(maxSize: 1024);
            await fileClient.GetPropertiesAsync();
        }
    }
}

使用 FileREST 数据平面 API 授予访问权限

还可以使用 Azure 门户、Azure PowerShell 或 Azure CLI 授权访问文件数据。

Install-Module Az.Storage -Repository PsGallery

另请参阅

• 选择如何在 Azure 门户中授予对文件数据的访问权限