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

通过使用 Azure 文件存储 OAuth over REST，用户和应用程序可以通过 OAuth 身份验证协议获取对Azure文件共享的管理员级读取和写入访问权限。 此访问方法使用 Microsoft Entra ID 进行基于 REST API 的访问。

用户、组、Microsoft 服务（例如Azure门户）以及使用 REST 接口的合作伙伴服务和应用程序现在可以通过 Microsoft Entra 帐户使用 OAuth 身份验证和授权来访问Azure 文件存储中的数据。 调用 REST API 的Azure PowerShell cmdlet 和Azure CLI命令也可以使用 OAuth 访问Azure 文件存储。

必须使用显式标头来调用 REST API，以指示你打算使用其他权限。 此要求也适用于Azure PowerShell和Azure CLI访问。

本文介绍如何为特定的 customer 用例启用对Azure文件共享的管理员级访问权限。 有关用户基于标识的身份验证的更一般的文章，请参阅基于标识的 Azure 文件存储 身份验证概述。

局限性

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

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

请参阅 Versioning for Azure 存储。

客户用例

通过 REST API 接口使用 Azure 文件存储 进行 OAuth 身份验证和授权可以在以下方案中使客户受益。

应用程序开发和服务集成

OAuth 身份验证和授权使开发人员能够生成使用用户或应用程序标识从Microsoft Entra ID访问 Azure 存储 REST API 的应用程序。

客户和合作伙伴还可以使Microsoft和合作伙伴服务能够安全地透明地配置对客户存储帐户的必要访问。

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

托管标识

具有应用程序和托管标识并需要访问文件共享数据以实现备份、还原或审核目的的客户可以从 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 操作。 此分配是使用此功能的要求。 有关调用特定Azure 文件存储服务操作所需的权限的详细信息，请参阅调用数据操作。

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

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

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

• 当用户、组或服务主体被分配为存储文件数据特权读取者或存储文件数据特权贡献者角色，并使用OAuth来调用FileREST数据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 Identity 客户端库简化了通过 Azure SDK 使用 Entra ID 获取 OAuth 2.0 访问令牌以进行授权的过程。 适用于 .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 门户中的文件数据