使用 Microsoft Entra ID 搭配 Azure 檔案儲存體 OAuth over REST 存取 Azure 檔案共用

發行項
03/21/2024

Azure 檔案儲存體 OAuth over REST 可將 Azure 檔案共用的管理員層級讀取和寫入存取權，授與透過 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 檔案儲存體 OAuth over REST 僅支援可使用檔案和目錄作業的 FileREST 資料 API。管理 FileService 和 FileShare 資源的 FilesREST 資料平面 API 不支援 OAuth。這些管理 API 的呼叫必須使用儲存體帳戶金鑰或 SAS 權杖，而且會因為延遲的原因透過資料平面遭到公開。建議使用支援 OAuth 的控制平面 API (儲存體資源提供者 - Microsoft.Storage)，進行與 FileService 和 FileShare 資源相關的所有管理活動。

僅 REST API 2022-11-02 版和更新版本支援使用 Microsoft Entra ID 授權檔案資料作業。請參閱 Azure 儲存體的版本設定。

客戶使用案例

OAuth 驗證和授權搭配 REST API 介面上的 Azure 檔案儲存體有助於下列案例中的客戶。

應用程式開發和服務整合

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

呼叫 REST API 搭配 OAuth 的使用者、群組或服務主體必須將 readFileBackupSemantics 或 writeFileBackupSemantics 動作指派給允許資料存取的角色。這是使用這個功能的必要條件。如需呼叫特定檔案儲存體服務作業所需的權限詳細資訊，請參閱呼叫資料作業的權限。

這個功能提供兩個新的內建角色，其中包含這些新動作。

Role	資料動作
儲存體檔案資料特殊權限讀者	`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 帳戶來存取資料。

若要在 Azure 入口網站使用您的 Microsoft Entra 帳戶存取檔案資料，您需要存取檔案資料的權限，而且您也需要權限來瀏覽 Azure 入口網站中的儲存體帳戶資源。 Azure 提供的內建角色會授與檔案資源的存取權，但不會授與儲存體帳戶資源的權限。基於這個理由，存取入口網站也需要指派 Azure Resource Manager (ARM) 角色 (例如讀者角色)，範圍設定在儲存體帳戶層級或更高層級。讀者角色授與最受限制的權限，但任何授與儲存體帳戶管理資源存取權的 ARM 角色都是可接受的。

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

Azure 提供 PowerShell 的延伸模組，可讓您使用 Microsoft Entra 認證登入並執行 PowerShell Cmdlet。當您使用 Microsoft Entra 認證登入 PowerShell，會傳回 OAuth 2.0 存取權杖。 PowerShell 會自動使用該權杖，授權對檔案儲存體執行的後續資料作業。針對支援的作業，您不需要再使用命令傳遞帳戶金鑰或 SAS 權杖。

您可以透過 Azure RBAC，將檔案資料的權限指派給 Microsoft Entra 安全性主體。

支援的作業

延伸模組僅支援檔案資料作業。您可以呼叫的作業取決於您用來登入 PowerShell 的 Microsoft Entra 安全性主體所獲得授與的權限。

只有在呼叫時搭配 -EnableFileBackupRequestIntent 參數，才能使用具有 OAuth 的儲存體內容。這是為了指定使用這個功能所提供額外權限的明確意圖。

具有 OAuth 的儲存體內容僅適用於檔案和目錄的作業，以及 Azure 檔案共用的取得/設定權限。若是儲存體帳戶和檔案共用的其他所有作業，您必須使用儲存體帳戶金鑰或 SAS 權杖。

必要條件

您需要資源群組及該資源群組內的儲存體帳戶。儲存體帳戶必須獲得指派為適當的角色，授與對檔案共用執行資料作業的明確權限。請確定您擁有存取管理服務和資料服務兩項的必要角色和權限。如需呼叫特定檔案儲存體服務作業所需的權限詳細資訊，請參閱呼叫資料作業的權限。

安裝 Az.Storage 模組

最新的 Az.Storage 模組提供此功能。請使用此指令安裝模組：

Install-Module Az.Storage -Repository PsGallery

授權存取檔案資料

若要授權存取檔案資料，請遵循下列步驟。

使用 Connect-AzAccount Cmdlet 登入您的 Azure 帳戶。
藉由呼叫 Get-AzStorageAccount Cmdlet(管理服務)，使用儲存體帳戶金鑰取得儲存體帳戶內容。將 <ResourceGroupName> 和 <StorageAccountName> 取代為您自己的值。
```
$ctxkey = (Get-AzStorageAccount -ResourceGroupName <ResourceGroupName> -Name <StorageAccountName>).Context
```
藉由呼叫 New-AzStorageShare 建立檔案共用。因為您使用步驟 2 的儲存體帳戶內容，因此會使用您的儲存體帳戶金鑰建立檔案共用。
```
$fileshareName = "sample-share"
New-AzStorageShare -Name $fileshareName -Context $ctxkey
```
取得使用 OAuth 的儲存體帳戶內容，該內容可用來執行檔案共用 (資料服務) 的資料作業。將 <StorageAccountName> 取代為您的儲存體帳戶名稱。
```
$ctx = New-AzStorageContext -StorageAccountName <StorageAccountName> -EnableFileBackupRequestIntent
```
若要取得具有 OAuth 的儲存體內容，您必須明確地將 -EnableFileBackupRequestIntent 參數傳遞至 New-AzStorageContext Cmdlet。如果您未傳遞意圖參數，則使用內容的後續檔案共用資料作業要求會失敗。
使用 New-AzStorageDirectory 和 Set-AzStorageFileContent Cmdlet 在檔案共用中建立測試目錄和檔案。記得指定本機來源檔案路徑。
```
$dir = New-AzStorageDirectory -ShareName $fileshareName -Path "dir1" -Context $ctx
$file = Set-AzStorageFileContent -ShareName $fileshareName -Path "test2" -Source "<local source file path>" -Context $ctx  
```
因為您使用步驟 4 的儲存體帳戶內容呼叫 Cmdlet，因此會使用 Microsoft Entra 認證建立檔案和目錄。

CLI 隨附的核心 Azure CLI 命令支援 Azure 檔案儲存體 OAuth over REST 介面，您可以用來驗證和授權使用 Microsoft Entra 認證的檔案資料作業。

支援的作業

命令僅支援檔案資料作業。您可以呼叫的作業取決於您用來登入 Azure CLI 的 Microsoft Entra 安全性主體所獲得授與的權限。

只有在呼叫 CLI 命令時搭配 --backup-intent 選項或 --enable-file-backup-request-intent 選項，才能使用 OAuth 驗證和授權。這是為了指定使用這個功能所提供額外權限的明確意圖。

az storage file、az storage directory 命令群組之下的所有命令以及 az storage share list-handle 與 az storage share close-handle 支援 OAuth 驗證和授權。若是儲存體帳戶和檔案共用的其他所有作業，您必須使用儲存體帳戶金鑰或 SAS 權杖。

必要條件

安裝和範例命令

如果您尚未這麼做，請安裝最新版的 Azure CLI。