REST を介した Azure Files OAuth を使用して、Microsoft Entra ID で Azure ファイル共有にアクセスする。

✔️ 適用対象: Microsoft.Storage リソース プロバイダーで作成されたクラシック ファイル共有

✖️ 適用されません: Microsoft.FileShares リソース プロバイダーで作成されたファイル共有 (プレビュー)

REST Azure Files OAuth を使用すると、ユーザーとアプリケーションは、OAuth 認証プロトコルを使用してAzure ファイル共有への管理者レベルの読み取りおよび書き込みアクセスを取得できます。 このアクセス方法では、REST API ベースのアクセスに Entra ID を使用します。 ユーザー、グループ、Azure ポータルなどのファースト パーティのサービス、REST インターフェイスを使用するサード パーティのサービスとアプリケーションで、Microsoft Entra アカウントで OAuth 認証と承認を使用して、Azure Filesのデータにアクセスできるようになりました。 REST API を呼び出す PowerShell コマンドレットとAzure CLI コマンドは、OAuth を使用してAzure Filesにアクセスすることもできます。 追加の特権を使用する意図を示すには、明示的なヘッダーを使用して REST API を呼び出す必要があります。 この要件は、Azure PowerShellおよびAzure CLIアクセスにも適用されます。

制限事項

Microsoft Entra IDを使用したファイル データ操作の承認は、REST API バージョン 2022-11-02 以降でのみサポートされます。

Azure Files FileService リソースと FileShare リソースを管理する Azure Files REST データ プレーン API の OAuth over REST サポートは、REST API バージョン 2024-11-04 以降で使用できます。

Azure Storageについては、「バージョン管理」を参照してください。

顧客のユース ケース

REST API インターフェイスを介したAzure Filesを使用した OAuth 認証と承認は、次のシナリオでお客様に役立ちます。

アプリケーション開発とサービス統合

OAuth 認証と承認により、開発者は、Microsoft Entra IDのユーザー ID またはアプリケーション ID を使用して、Azure Storage REST API にアクセスするアプリケーションを構築できます。

顧客とパートナーは、ファースト パーティおよびサード パーティのサービスを有効にして、顧客のストレージ アカウントに対して必要なアクセスを安全かつ透過的に構成することもできます。

Azure ポータル、PowerShell、CLI、AzCopy、Storage Explorerなどの DevOps ツールでは、ユーザーの ID を使用してデータを管理できるため、ストレージ アクセス キーを管理または配布する必要がなくなります。

管理されたアイデンティティー

バックアップ、復元、または監査の目的でファイル共有データへのアクセスを必要とするアプリケーションとマネージド ID をお持ちのお客様は、OAuth の認証と承認の恩恵を受けることができます。 各 ID に対してファイル レベルおよびディレクトリ レベルのアクセス許可を適用すると、複雑さが増し、特定のワークロードと互換性がない可能性があります。 たとえば、ファイル固有のアクセス許可に関係なく、すべてのファイルに対する読み取り専用アクセス権Azureファイル共有にアクセスするバックアップ ソリューション サービスを承認することが必要な場合があります。

ストレージ アカウント キーの置換

Microsoft Entra IDは、共有キー アクセスよりも優れたセキュリティと使いやすさを提供します。 OAuth 認証と承認を用いて、読み取り/書き込み権限を持って Azure ファイル共有にアクセスすることで、ストレージ アカウント キーの利用を置き換えます。 この方法では、特定のユーザー アクセスの監査と追跡も向上します。

データ操作の特権アクセスとアクセス許可

AZURE FILES OAuth over REST 機能を使用するには、ユーザー、グループ、またはサービス プリンシパルに割り当てる追加のアクセス許可を RBAC ロールに含めます。 この機能には、次の 2 つの新しいデータ アクションが導入されています。

Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action

Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action

OAuth を使用して REST API を呼び出すユーザー、グループ、またはサービス プリンシパルには、データ アクセスを許可するロールに readFileBackupSemantics または writeFileBackupSemantics アクションが割り当てられている必要があります。 これは、この機能を使用するための要件です。 特定のファイル サービス操作を呼び出すために必要なアクセス許可の詳細については、「データ操作を 呼び出すためのアクセス許可」を参照してください。

この機能には、これらのアクションを含む 2 つの組み込みロールが用意されています。

これらのロールは、 ストレージ ファイル データ SMB 共有閲覧者 ロールと ストレージ ファイル データ SMB 共有管理者特権共同作成者 組み込みロールに似ていますが、いくつかの違いがあります。

• 新しいロールには、OAuth アクセスに必要な追加のデータ アクションが含まれています。

• 割り当てられたユーザー、グループ、またはサービス プリンシパルが ストレージ ファイル データ特権閲覧者 または ストレージ ファイル データ特権共同作成者 のロールを持つ場合、ユーザー、グループ、またはサービス プリンシパルを使用して、OAuth で FilesREST データ API を呼び出すときにその権限を有します。

  • ストレージ ファイル データの特権リーダー: 設定されているファイル/ディレクトリ レベルの NTFS アクセス許可に関係なく、構成されているすべてのストレージ アカウントの共有内のすべてのデータに対するフル 読み取りアクセス。
  • ストレージ ファイル データの特権共同作成者: 完全な読み取り、書き込み、ACL の変更、設定されているファイル/ディレクトリ レベルの NTFS アクセス許可に関係なく、構成されているすべてのストレージ アカウントの共有内のすべてのデータに対するアクセス権を削除します。

• これらの特別なアクセス許可とロールを使用すると、システムはファイルまたはディレクトリ レベルのアクセス許可をバイパスし、ファイル共有データへのアクセスを許可します。

新しいロールとデータ アクションを使用することで、この機能はストレージ アカウント全体の特権を提供し、ストレージ アカウント内のすべてのファイル共有にあるファイルとフォルダーに対するすべてのアクセス許可を優先します。 ただし、新しいロールには、データ サービスにアクセスするためのアクセス許可のみが含まれます。 ファイル共有管理サービス (ファイル共有に対するアクション) にアクセスするためのアクセス許可は含まれません。 この機能を使用するには、アクセス許可があることを確認します。

• ストレージ アカウント
• ファイル共有管理サービス
• データ サービス (ファイル共有内のデータ)

多くの 組み込みロールは 、管理サービスへのアクセスを提供します。 適切なアクセス許可を持つ カスタム ロールを作成 することもできます。 ロールベースのアクセス制御の詳細については、「Azure RBACを参照してください。 組み込みのロールの定義方法の詳細については、ロール定義に関するページを参照してください。

ファイル共有リソースの種類の場合、対応する RBAC スコープはコントロール プレーン (管理操作) で shares を使用しますが、データ プレーン内の fileshares (データ操作) を使用します。 RBAC スコープまたはデータ アクション文字列に shares を含むファイル共有リソース ID を使用しようとすると、機能しません。 RBAC の割り当てのスコープで fileshares を使用する必要があります。次に例を示します。

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

アプリケーション コード内のファイル データへのアクセスを承認する

Azure ID クライアント ライブラリを使用すると、Azure SDK を介して Entra ID を使用して承認するための OAuth 2.0 アクセス トークンを取得するプロセスが簡略化されます。 .NET、Java、Python、JavaScript、Go 用のAzure Storage クライアント ライブラリの最新バージョンは、これらの言語ごとにAzure ID ライブラリと統合され、Azure Files サービスからの要求の承認のためのアクセス トークンを簡単かつ安全に取得できます。

Azure ID クライアント ライブラリの利点は、アプリケーションが開発環境またはAzureで実行されているかどうかにかかわらず、同じコードを使用してアクセス トークンを取得できる点です。 Azure ID クライアント ライブラリは、セキュリティ プリンシパルのアクセス トークンを返します。 コードがAzureで実行されている場合、セキュリティ プリンシパルには、Azure リソース、サービス プリンシパル、またはユーザーまたはグループのマネージド ID を指定できます。 開発環境では、クライアント ライブラリにより、ユーザーまたはサービス プリンシパルにテストのためのアクセス トークンが提供されます。

Azure ID クライアント ライブラリは、アクセス トークンをトークン資格情報にカプセル化します。 トークン資格情報を使用して、Azure Files サービスに対して承認された操作を実行するためのサービス クライアント オブジェクトを取得します。

次のコード例は、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を使用して、ファイル データへのアクセスを承認することもできます。

Install-Module Az.Storage -Repository PsGallery

こちらも参照ください

• Azure ポータルでファイル データへのアクセスを承認する方法を選択します