共用方式為

透過 REST 使用 Microsoft Entra ID 和 Azure 檔案服務 OAuth 存取 Azure 檔案共用

透過 REST 的 Azure 檔案共用 OAuth，使用 OAuth 驗證通訊協定，並以 Microsoft Entra ID 啟用以 REST API 為基礎的存取，提供使用者和應用程式系統管理員層級的讀取及寫入存取權。 使用者、群組、第一方服務，例如 Azure 入口網站，以及使用 REST 介面的第三方服務和應用程式，現在可以使用 OAuth 驗證和授權搭配 Microsoft Entra 帳戶來存取 Azure 檔案共用中的數據。 呼叫 REST API 的 PowerShell Cmdlet 和 Azure CLI 命令也可以使用 OAuth 來存取 Azure 檔案共用。 您必須使用明確的標頭呼叫 REST API，以指出您的意圖使用其他許可權。 這也適用於 Azure PowerShell 和 Azure CLI 存取。

這很重要

本文說明如何針對特定 客戶使用案例啟用 Azure 檔案共用的系統管理層級存取。 如果您要尋找使用者身分識別型驗證的更一般文章，請參閱 適用於SMB存取的 Azure 檔案記憶體身分識別型驗證概觀。

適用對象

管理模型 計費模型 媒體分層 冗餘性 中小企業 (SMB) 網路檔案系統 (NFS)
Microsoft 儲存服務 已佈建的 v2 HDD （標準） 本地 (LRS) 是的 否
Microsoft 儲存服務 已佈建的 v2 HDD （標準） 區域 (ZRS) 是的 否
Microsoft 儲存服務 已佈建的 v2 HDD （標準） 異地 (GRS) 是的 否
Microsoft 儲存服務 已佈建的 v2 HDD （標準） GeoZone （GZRS） 是的 否
Microsoft 儲存服務 已佈建的 v1 SSD （進階版） 本地 (LRS) 是的 是的
Microsoft 儲存服務 已佈建的 v1 SSD （進階版） 區域 (ZRS) 是的 是的
Microsoft 儲存服務 隨用隨付 HDD （標準） 本地 (LRS) 是的 否
Microsoft 儲存服務 隨用隨付 HDD （標準） 區域 (ZRS) 是的 否
Microsoft 儲存服務 隨用隨付 HDD （標準） 異地 (GRS) 是的 否
Microsoft 儲存服務 隨用隨付 HDD （標準） GeoZone （GZRS） 是的 否

局限性

只有 REST API 2022-11-02 版和更新版本才支援使用 Microsoft Entra 識別符的檔案資料作業。

適用於管理 FileService 和 FileShare 資源的 Azure Files REST 資料面 API 的 OAuth over REST 支援，適用於 2024-11-04 版及更高版本的 REST API。

請參閱 Azure 記憶體的版本設定。

客戶使用案例

透過 REST API 介面使用 Azure 檔案服務的 OAuth 驗證和授權，可讓客戶在下列案例中受益。

應用程式開發和服務整合

OAuth 驗證和授權可讓開發人員建置應用程式，以使用來自 Microsoft Entra 識別碼的使用者或應用程式身分識別來存取 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。 如需內建角色定義方式的詳細資訊，請參閱了解角色定義。

請注意，對於檔案共享資源類型，對應的 RBAC 範圍會在控制平面（管理作業）中使用 shares，在數據平面（數據作業）中使用 fileshares。 如果您嘗試使用包含在 RBAC 範圍或資料動作字串中的檔案共用資源識別碼 shares ，它將無法運作。 您必須在 RBAC 指派的範圍內使用 fileshares ，例如：

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

這很重要

針對路徑 Microsoft.Storage/storageAccounts/fileServices/* 或更高範圍定義的任何通配符使用案例，都會自動繼承透過這個新數據動作授與的其他存取權和許可權。 為了防止意外或過度授權存取 Azure 檔案，我們已實施額外檢查，要求使用者和應用程式明確表示其意願使用額外許可權。 此外，強烈建議客戶檢閱其使用者 RBAC 角色指派，並將任何通配符使用方式取代為明確許可權，以確保適當的數據存取管理。

授權存取應用程式程式代碼中的檔案數據

Azure Identity 用戶端程式庫透過 Microsoft Entra ID 的 Azure SDK，簡化了取得 OAuth 2.0 存取權杖進行授權的過程。 適用於 .NET、Java、Python、JavaScript 和 Go 的 Azure 記憶體用戶端連結庫最新版本會與這些語言的 Azure 身分識別連結庫整合，以提供簡單且安全的方法來取得 Azure 檔案服務要求授權的存取令牌。

Azure 身分識別用戶端連結庫的優點是，不論您的應用程式是在開發環境或 Azure 中執行，它都可讓您使用相同的程式代碼來取得存取令牌。 Azure 身分識別客戶端連結庫會傳回安全性主體的存取令牌。 當您的程式代碼在 Azure 中執行時，安全性主體可能是 Azure 資源的受控識別、服務主體或使用者或群組。 在開發環境中，客戶端連結庫會為用戶或服務主體提供存取令牌以供測試之用。

Azure 身分識別客戶端連結庫傳回的存取令牌會封裝在令牌認證中。 然後，您可以使用令牌認證來取得服務客戶端物件，以針對 Azure 檔案服務執行授權作業。

下列程式代碼範例示範如何使用 Microsoft 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.windows.net/";
            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 來授權檔案數據的存取權。

Azure 入口網站可以使用您的Microsoft Entra 帳戶或記憶體帳戶存取金鑰來存取 Azure 記憶體帳戶中的檔案數據。 Azure 入口網站所使用的授權配置取決於指派給您的 Azure 角色。

當您嘗試存取檔案資料時，Azure 入口網站會先檢查您是否已使用 Microsoft.Storage/storageAccounts/listkeys/action指派 Azure 角色。 如果您已獲指派此動作的角色，則 Azure 入口網站會使用帳戶密鑰，透過共用金鑰授權存取檔案資料。 如果您尚未獲指派此動作的角色，則 Azure 入口網站會嘗試使用您的 Microsoft Entra 帳戶來存取數據。

若要使用您的 Microsoft Entra 帳戶從 Azure 入口網站存取檔案數據，您需要存取檔案數據的許可權，而且也需要許可權，才能在 Azure 入口網站中瀏覽記憶體帳戶資源。 Azure 提供的內建角色會授與檔案資源的存取權，但不會將許可權授與記憶體帳戶資源。 基於這個理由，入口網站的存取權也需要指派 Azure Resource Manager （ARM） 角色，例如 讀取者 角色，範圍限定為記憶體帳戶的層級或更高層級。 讀取 者 角色會授與最嚴格的許可權，但可接受授與記憶體帳戶管理資源存取權的任何 ARM 角色。

Azure 入口網站會指出當您流覽至容器時，正在使用哪個授權配置。 如需入口網站中數據存取的詳細資訊，請參閱 選擇如何授權存取 Azure 入口網站中的檔案數據。

另請參閱

  • Last updated on