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

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

  • 项目

Azure 文件存储 OAuth over REST 可使用 Microsoft Entra ID 进行基于 REST API 的访问，通过 OAuth 身份验证协议为用户和应用程序启用对 Azure 文件共享的管理员级读写访问。 用户、组、第一方服务（如 Azure 门户）以及使用 REST 接口的第三方服务和应用程序现在可以通过 Microsoft Entra 帐户使用 OAuth 身份验证和授权来访问 Azure 文件共享中的数据。 调用 REST API 的 PowerShell cmdlet 和 Azure CLI 命令也可以使用 OAuth 来访问 Azure 文件共享。

重要

必须使用显式标头调用 REST API，以指明你使用其他特权的意图。 对于 Azure PowerShell 和 Azure CLI 访问，情况也是如此。

限制

Azure 文件存储 OAuth over REST 仅支持那些支持文件和目录操作的 FileREST 数据 API。 管理 FileService 和 FileShare 资源的 FilesREST 数据平面 API 不支持 OAuth。 这些管理 API 是使用存储帐户密钥或 SAS 令牌调用的，并出于传统原因通过数据平面来公开。 建议使用控制平面 API（存储资源提供程序 - Microsoft.Storage），以支持对与 FileService 和 FileShare 资源相关的所有管理活动执行 OAuth。

只有 REST API 版本 2022-11-02 及更高版本支持针对 Microsoft Entra ID 授权文件数据操作。 请参阅 Azure 存储的版本控制。

客户用例

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

应用程序开发和服务集成

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

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

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

托管标识

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

存储帐户密钥替换

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

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

若要使用 Azure 文件存储 OAuth over REST 功能，需要将其他权限包含在分配给用户、组或服务主体的 RBAC 角色中。 此功能引入了两个新的数据操作：

Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action

Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action

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

此功能提供了两个新的内置角色，其中包括以下新操作。

角色 数据操作
存储文件数据特权读取者 Microsoft.Storage/storageAccounts/fileServices/fileShares/files/read
Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action
存储文件数据特权参与者 Microsoft.Storage/storageAccounts/fileServices/fileShares/files/read
Microsoft.Storage/storageAccounts/fileServices/fileShares/files/write
Microsoft.Storage/storageAccounts/fileServices/fileShares/files/delete
Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action
Microsoft.Storage/storageAccounts/fileServices/fileshares/files/modifypermissions/action

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

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

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

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

  • 有了这些特殊权限和角色，系统将绕过任何文件/目录级别权限，并允许访问文件共享数据。

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

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

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

重要

为路径 Microsoft.Storage/storageAccounts/fileServices/* 或更高范围定义的任何通配符用例都将自动继承通过此新数据操作授予的其他访问权限和权限。 为了防止意外或过度特权访问 Azure 文件存储，我们实施了额外检查，要求用户和应用程序直接指明其使用其他特权的意图。 此外，强烈建议客户查看其用户 RBAC 角色分配，并将任何通配符用法替换为显式权限，以确保适当的数据访问管理。

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

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

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

Azure 标识客户端库返回的访问令牌封装在令牌凭据中。 然后，可以使用该令牌凭据来获取服务客户端对象，以用于对 Azure 文件存储服务执行授权的操作。

下面是一些示例代码：

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 aadEndpoint = "";
            string accountUri = "";
            string connectionString = "";
            string shareName = "test-share";
            string directoryName = "testDirectory";
            string fileName = "testFile"; 

            ShareClient sharedKeyShareClient = new ShareClient(connectionString, shareName); 
            await sharedKeyShareClient.CreateIfNotExistsAsync(); 

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

            ShareClientOptions clientOptions = new ShareClientOptions(ShareClientOptions.ServiceVersion.V2023_05_03);

            // Set Allow Trailing Dot and Source Allow Trailing Dot.
            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();
            await sharedKeyShareClient.DeleteIfExistsAsync();
        }
    }
}

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

还可以使用 Azure 门户或 Azure PowerShell 授予对文件数据的访问权限。

Azure 门户可以使用 Microsoft Entra 帐户或存储帐户访问密钥来访问 Azure 存储帐户中的文件数据。 Azure 门户使用哪种授权方案取决于分配给你的 Azure 角色。

在你尝试访问文件数据时，Azure 门户首先会检查你是否分配有包含 Microsoft.Storage/storageAccounts/listkeys/action 的 Azure 角色。 如果你已分配有包含此操作的角色，则 Azure 门户将使用帐户密钥通过共享密钥授权来访问文件数据。 如果未分配有包含此操作的角色，则 Azure 门户会尝试使用你的 Microsoft Entra 帐户访问数据。

若要使用 Microsoft Entra 帐户通过 Azure 门户访问文件数据，需要拥有访问文件数据的权限，另外还需要拥有在 Azure 门户中浏览存储帐户资源的权限。 Azure 提供的内置角色授予对文件资源的访问权限，但不授予对存储帐户资源的权限。 出于此原因，访问门户还需要分配范围为存储帐户或更高级别的 Azure 资源管理器 (ARM) 角色，例如“读取者”角色。 “读取者”角色授予限制性最高的权限，但可接受授予存储帐户管理资源访问权限的任何 ARM 角色。

当你导航到容器时，Azure 门户会指示当前正在使用哪种授权方案。 有关在门户中访问数据的详细信息，请参阅选择如何在 Azure 门户中授权访问文件数据。

另请参阅