.NET を使用してコンテナーまたは BLOB 用のユーザー委任 SAS を作成する (プレビュー)Create a user delegation SAS for a container or blob with .NET (preview)

Shared Access Signature (SAS) を使用すると、ストレージ アカウント内のコンテナーと BLOB への制限付きアクセスを許可できます。A shared access signature (SAS) enables you to grant limited access to containers and blobs in your storage account. SAS を作成するときに、クライアントがアクセスできる Azure Storage リソース、それらのリソースに対するアクセス許可、SAS の有効期間などの制約を指定します。When you create a SAS, you specify its constraints, including which Azure Storage resources a client is allowed to access, what permissions they have on those resources, and how long the SAS is valid.

すべての SAS はキーによって署名されます。Every SAS is signed with a key. 次の 2 つの方法のいずれかで SAS に署名できます。You can sign a SAS in one of two ways:

  • Azure Active Directory (Azure AD) の資格情報を使用して作成されたキーを使用する。With a key created using Azure Active Directory (Azure AD) credentials. Azure AD の資格情報を使用して署名された SAS は、ユーザー委任 SAS です。A SAS signed with Azure AD credentials is a user delegation SAS.
  • ストレージ アカウント キーを使用する。With the storage account key. サービス SASアカウント SAS は、どちらもストレージ アカウント キーを使用して署名されます。Both a service SAS and an account SAS are signed with the storage account key.

この記事では、.NET 用 Azure Storage クライアント ライブラリを使用するコンテナーまたは BLOB 用のユーザー委任 SAS を Azure Active Directory (Azure AD) 資格情報を使用して作成する方法について説明します。This article shows how to use Azure Active Directory (Azure AD) credentials to create a user delegation SAS for a container or blob with the Azure Storage client library for .NET.

ユーザー委任 SAS について (プレビュー)About the user delegation SAS (preview)

コンテナーまたは BLOB にアクセスするための SAS トークンは、Azure AD 資格情報またはアカウント キーのいずれかを使用してセキュリティ保護することができます。A SAS token for access to a container or blob may be secured by using either Azure AD credentials or an account key. Azure AD 資格情報でセキュリティ保護された SAS は、ユーザーの代わりに、SAS に署名するために使用される OAuth 2.0 トークンが要求されるため、ユーザー委任 SAS と呼ばれます。A SAS secured with Azure AD credentials is called a user delegation SAS, because the OAuth 2.0 token used to sign the SAS is requested on behalf of the user.

セキュリティのベスト プラクティスとして、より簡単に侵害できるアカウント キーを使用するのではなく、可能な限り Azure AD 資格情報を使用することをお勧めします。Microsoft recommends that you use Azure AD credentials when possible as a security best practice, rather than using the account key, which can be more easily compromised. アプリケーション設計で Shared Access Signature が必要な場合は、セキュリティを強化するために、Azure AD 資格情報を使用してユーザー委任 SAS を作成してください。When your application design requires shared access signatures, use Azure AD credentials to create a user delegation SAS for superior security. ユーザー委任 SAS の詳細については、「ユーザー委任 SAS を作成する」を参照してください。For more information about the user delegation SAS, see Create a user delegation SAS.

注意

このユーザー委任 SAS プレビューは、非運用環境でのみの使用を意図しています。The user delegation SAS preview is intended for non-production use only.

注意事項

有効な SAS を所有するすべてのクライアントは、その SAS で許可されているストレージ アカウントのデータにアクセスできます。Any client that possesses a valid SAS can access data in your storage account as permitted by that SAS. SAS を悪意のある、または意図しない用途から保護することが重要です。It's important to protect a SAS from malicious or unintended use. SAS の配布は慎重に行い、侵害された SAS を失効させるための計画を用意しておいてください。Use discretion in distributing a SAS, and have a plan in place for revoking a compromised SAS.

Shared Access Signature の詳細については、「Shared Access Signatures (SAS) を使用して Azure Storage リソースへの制限付きアクセスを許可する」を参照してください。For more information about shared access signatures, see Grant limited access to Azure Storage resources using shared access signatures (SAS).

プレビュー パッケージをインストールするInstall the preview packages

この記事の例では、BLOB ストレージ用の Azure Storage クライアント ライブラリの最新のプレビュー バージョンが使用されます。The examples in this article use the latest preview version of the Azure Storage client library for Blob storage. プレビュー パッケージをインストールするには、NuGet パッケージ マネージャー コンソールから次のコマンドを実行します。To install the preview package, run the following command from the NuGet package manager console:

Install-Package Azure.Storage.Blobs -IncludePrerelease

この記事の例では、Azure AD の資格情報で認証するために、.NET 用 Azure ID クライアント ライブラリの最新のプレビュー バージョンも使用されます。The examples in this article also use the latest preview version of the Azure Identity client library for .NET to authenticate with Azure AD credentials. Azure ID クライアント ライブラリによって、セキュリティ プリンシパルが認証されます。The Azure Identity client library authenticates a security principal. その後、認証されたセキュリティ プリンシパルによって、ユーザー委任 SAS を作成できます。The authenticated security principal can then create the user delegation SAS. Azure ID クライアント ライブラリの詳細については、「.NET 用 Azure ID クライアント ライブラリ」を参照してください。For more information about the Azure Identity client library, see Azure Identity client library for .NET.

Install-Package Azure.Identity -IncludePrerelease

サービス プリンシパルの作成Create a service principal

Azure ID クライアント ライブラリ経由で Azure AD の資格情報を使用して認証するには、コードの実行場所に応じて、サービス プリンシパルまたはマネージド ID をセキュリティ プリンシパルとして使用します。To authenticate with Azure AD credentials via the Azure Identity client library, use either a service principal or a managed identity as the security principal, depending on where your code is running. コードが開発環境で実行される場合は、テスト目的でサービス プリンシパルを使用します。If your code is running in a development environment, use a service principal for testing purposes. コードが Azure で実行される場合は、マネージド ID を使用します。If your code is running in Azure, use a managed identity. この記事では、開発環境からコードを実行することを前提として、サービス プリンシパルを使用してユーザー委任 SAS を作成する方法を示します。This article assumes that you are running code from the development environment, and shows how to use a service principal to create the user delegation SAS.

Azure CLI を使用してサービス プリンシパルを作成し、RBAC ロールを割り当てるには、az ad sp create-for-rbac コマンドを呼び出します。To create a service principal with Azure CLI and assign an RBAC role, call the az ad sp create-for-rbac command. 新しいサービス プリンシパルに割り当てる Azure Storage データ アクセス ロールを指定します。Provide an Azure Storage data access role to assign to the new service principal. ロールには、Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey アクションが含まれている必要があります。The role must include the Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey action. Azure Storage 用に提供されている組み込みロールの詳細については、「Azure リソースの組み込みロール」を参照してください。For more information about the built-in roles provided for Azure Storage, see Built-in roles for Azure resources.

さらに、ロール割り当て用のスコープを指定します。Additionally, provide the scope for the role assignment. サービス プリンシパルでは、ストレージ アカウント レベルで実行される操作であるユーザー委任キーが作成されるため、ロールの割り当てには、ストレージ アカウント、リソース グループ、またはサブスクリプションのレベルでスコープを設定する必要があります。The service principal will create the user delegation key, which is an operation performed at the level of the storage account, so the role assignment should be scoped at the level of the storage account, resource group, or subscription. ユーザー委任 SAS を作成するための RBAC アクセス許可の詳細については、「ユーザー委任 SAS を作成する (REST API)」の「RBAC によるアクセス許可の割り当て」セクションを参照してください。For more information about RBAC permissions for creating a user delegation SAS, see the Assign permissions with RBAC section in Create a user delegation SAS (REST API).

サービス プリンシパルにロールを割り当てるための十分なアクセス許可がない場合は、アカウント所有者または管理者にロールの割り当ての実行を依頼しなければならない可能性があります。If you do not have sufficient permissions to assign a role to the service principal, you may need to ask the account owner or administrator to perform the role assignment.

次の例では、Azure CLI を使用して新しいサービス プリンシパルを作成し、ストレージ BLOB データ閲覧者ロールをアカウント スコープで割り当てています。The following example uses the Azure CLI to create a new service principal and assign the Storage Blob Data Reader role to it with account scope

az ad sp create-for-rbac \
    --name <service-principal> \
    --role "Storage Blob Data Reader" \
    --scopes /subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>

az ad sp create-for-rbac コマンドによって、サービス プリンシパルのプロパティの一覧が JSON 形式で返されます。The az ad sp create-for-rbac command returns a list of service principal properties in JSON format. これらの値をコピーして、次の手順で必要な環境変数を作成するために使用できるようにします。Copy these values so that you can use them to create the necessary environment variables in the next step.

{
    "appId": "generated-app-ID",
    "displayName": "service-principal-name",
    "name": "http://service-principal-uri",
    "password": "generated-password",
    "tenant": "tenant-ID"
}

重要

RBAC ロールの割り当ての反映には数分かかることがあります。RBAC role assignments may take a few minutes to propagate.

環境変数の設定Set environment variables

Azure ID クライアント ライブラリでは、実行時に 3 つの環境変数から値を読み取って、サービス プリンシパルが認証されます。The Azure Identity client library reads values from three environment variables at runtime to authenticate the service principal. 次の表で、各環境変数に設定する値について説明します。The following table describes the value to set for each environment variable.

環境変数Environment variable Value
AZURE_CLIENT_ID サービス プリンシパル用のアプリ IDThe app ID for the service principal
AZURE_TENANT_ID サービス プリンシパルの Azure AD テナント IDThe service principal's Azure AD tenant ID
AZURE_CLIENT_SECRET サービス プリンシパル用に生成されたパスワードThe password generated for the service principal

重要

環境変数を設定したら、コンソール ウィンドウを閉じて再度開きます。After you set the environment variables, close and re-open your console window. Visual Studio または他の開発環境を使用している場合は、新しい環境変数を登録するために開発環境の再起動が必要である可能性があります。If you are using Visual Studio or another development environment, you may need to restart the development environment in order for it to register the new environment variables.

using ディレクティブを追加するAdd using directives

Azure ID と Azure Storage クライアント ライブラリのプレビューバージョンを使用するために、次の using ディレクティブをコードに追加します。Add the following using directives to your code to use the preview versions of the Azure Identity and Azure Storage client libraries.

using System;
using System.IO;
using System.Threading.Tasks;
using Azure.Identity;
using Azure.Storage;
using Azure.Storage.Sas;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;

サービス プリンシパルを認証するAuthenticate the service principal

サービス プリンシパルを認証するには、DefaultAzureCredential クラスのインスタンスを作成します。To authenticate the service principal, create an instance the DefaultAzureCredential class. DefaultAzureCredential コンストラクター によって、先ほど作成した環境変数が読み取られます。The DefaultAzureCredential constructor reads the environment variables that you created previously.

次のコード スニペットでは、認証された資格情報を取得し、それを使用して BLOB ストレージ用のサービス クライアントを作成する方法が示されています。The following code snippet shows how to get the authenticated credential and use it to create a service client for Blob storage

string blobEndpoint = string.Format("https://{0}.blob.core.windows.net", accountName);

BlobServiceClient blobClient = new BlobServiceClient(new Uri(blobEndpoint),
                                                     new DefaultAzureCredential());

ユーザー委任キーを取得するGet the user delegation key

すべての SAS はキーによって署名されます。Every SAS is signed with a key. ユーザー委任 SAS を作成するには、まず、SAS に署名するために使用されるユーザー委任キーを要求する必要があります。To create a user delegation SAS, you must first request a user delegation key, which is then used to sign the SAS. ユーザー委任キーは、サービス SAS またはアカウント SAS に署名するために使用されるアカウント キーに似ていますが、Azure AD の資格情報に依存している点が異なります。The user delegation key is analogous to the account key used to sign a service SAS or an account SAS, except that it relies on your Azure AD credentials. クライアントで OAuth 2.0 トークンを使用してユーザー委任キーが要求されると、ユーザーに代わって Azure Storage によってユーザー委任キーが返されます。When a client requests a user delegation key using an OAuth 2.0 token, Azure Storage returns the user delegation key on behalf of the user.

ユーザー委任キーを取得したら、そのキーを使用して、キーの有効期間にわたって、任意の数のユーザー委任共有アクセス署名を作成できます。Once you have the user delegation key, you can use that key to create any number of user delegation shared access signatures, over the lifetime of the key. ユーザー委任キーは、それを取得するために使用された OAuth 2.0 トークンに依存しないため、キーが有効である限り、トークンを更新する必要はありません。The user delegation key is independent of the OAuth 2.0 token used to acquire it, so the token does not need to be renewed so long as the key is still valid. キーの有効期間として、最大 7 日間を指定できます。You can specify that the key is valid for a period of up to 7 days.

ユーザー委任キーを要求するには、次のいずれかの方法を使用します。Use one of the following methods to request the user delegation key:

次のコード スニペットでは、ユーザー委任キーが取得され、そのプロパティが書き出されます。The following code snippet gets the user delegation key and writes out its properties:

UserDelegationKey key = await blobClient.GetUserDelegationKeyAsync(DateTimeOffset.UtcNow,
                                                                   DateTimeOffset.UtcNow.AddDays(7));

Console.WriteLine("User delegation key properties:");
Console.WriteLine("Key signed start: {0}", key.SignedStart);
Console.WriteLine("Key signed expiry: {0}", key.SignedExpiry);
Console.WriteLine("Key signed object ID: {0}", key.SignedOid);
Console.WriteLine("Key signed tenant ID: {0}", key.SignedTid);
Console.WriteLine("Key signed service: {0}", key.SignedService);
Console.WriteLine("Key signed version: {0}", key.SignedVersion);

SAS トークンを作成するCreate the SAS token

次のコード スニペットで、新しいBlobSasBuilder を作成し、ユーザー委任 SAS のパラメーターを指定する方法を示します。The following code snippet shows create a new BlobSasBuilder and provide the parameters for the user delegation SAS. その後、スニペットでは ToSasQueryParameters を呼び出して、SAS トークン文字列が取得されます。The snippet then calls the ToSasQueryParameters to get the SAS token string. 最後に、このコードでは、リソース アドレスと SAS トークンを含む完全な URI がビルドされます。Finally, the code builds the complete URI, including the resource address and SAS token.

BlobSasBuilder builder = new BlobSasBuilder()
{
    ContainerName = containerName,
    BlobName = blobName,
    Permissions = "r",
    Resource = "b",
    StartTime = DateTimeOffset.UtcNow,
    ExpiryTime = DateTimeOffset.UtcNow.AddMinutes(5)
};

string sasToken = sasBuilder.ToSasQueryParameters(key, accountName).ToString();

UriBuilder fullUri = new UriBuilder()
{
    Scheme = "https",
    Host = string.Format("{0}.blob.core.windows.net", accountName),
    Path = string.Format("{0}/{1}", containerName, blobName),
    Query = sasToken
};

例:ユーザー委任 SAS を取得するExample: Get a user delegation SAS

次の例は、セキュリティ プリンシパルを認証し、ユーザー委任 SAS を作成するための完全なコードを示しています。The following example method shows the complete code for authenticating the security principal and creating the user delegation SAS:

async static Task<Uri> GetUserDelegationSasBlob(string accountName, string containerName, string blobName)
{
    // Construct the blob endpoint from the account name.
    string blobEndpoint = string.Format("https://{0}.blob.core.windows.net", accountName);

    // Create a new Blob service client with Azure AD credentials.  
    BlobServiceClient blobClient = new BlobServiceClient(new Uri(blobEndpoint), 
                                                            new DefaultAzureCredential());

    // Get a user delegation key for the Blob service that's valid for seven days.
    // Use the key to generate any number of shared access signatures over the lifetime of the key.
    UserDelegationKey key = await blobClient.GetUserDelegationKeyAsync(DateTimeOffset.UtcNow,
                                                                       DateTimeOffset.UtcNow.AddDays(7));

    // Read the key's properties.
    Console.WriteLine("User delegation key properties:");
    Console.WriteLine("Key signed start: {0}", key.SignedStart);
    Console.WriteLine("Key signed expiry: {0}", key.SignedExpiry);
    Console.WriteLine("Key signed object ID: {0}", key.SignedOid);
    Console.WriteLine("Key signed tenant ID: {0}", key.SignedTid);
    Console.WriteLine("Key signed service: {0}", key.SignedService);
    Console.WriteLine("Key signed version: {0}", key.SignedVersion);

    // Create a SAS token that's valid a short interval.
    BlobSasBuilder sasBuilder = new BlobSasBuilder()
    {
        ContainerName = containerName,
        BlobName = blobName,
        Permissions = "r",
        Resource = "b",
        StartTime = DateTimeOffset.UtcNow,
        ExpiryTime = DateTimeOffset.UtcNow.AddMinutes(5)
    };

    // Use the key to get the SAS token.
    string sasToken = sasBuilder.ToSasQueryParameters(key, accountName).ToString();

    // Construct the full URI, including the SAS token.
    UriBuilder fullUri = new UriBuilder()
    {
        Scheme = "https",
        Host = string.Format("{0}.blob.core.windows.net", accountName),
        Path = string.Format("{0}/{1}", containerName, blobName),
        Query = sasToken
    };

    Console.WriteLine("User delegation SAS URI: {0}", fullUri);
    return fullUri.Uri;
}

例:ユーザー委任 SAS を使用して BLOB を読み取るExample: Read a blob with a user delegation SAS

次の例では、前の例で作成されたユーザー委任 SAS を、シミュレートされたクライアント アプリケーションからテストします。The following example tests the user delegation SAS created in the previous example from a simulated client application. SAS が有効であれば、クライアント アプリケーションで BLOB の内容を読み取ることができます。If the SAS is valid, the client application is able to read the contents of the blob. SAS が無効な場合 (たとえば、有効期限が切れている場合)、Azure Storage によってエラー コード 403 (禁止) が返されます。If the SAS is invalid, for example if it has expired, Azure Storage returns error code 403 (Forbidden).

private static async Task ReadBlobWithSasAsync(Uri sasUri)
{
    // Try performing blob operations using the SAS provided.

    // Create a blob client object for blob operations.
    BlobClient blobClient = new BlobClient(sasUri, null);

    // Download and read the contents of the blob.
    try
    {
        // Download blob contents to a stream and read the stream.
        BlobDownloadInfo blobDownloadInfo = await blobClient.DownloadAsync();
        using (StreamReader reader = new StreamReader(blobDownloadInfo.Content, true))
        {
            string line;
            while ((line = reader.ReadLine()) != null)
            {
                Console.WriteLine(line);
            }
        }

        Console.WriteLine();
        Console.WriteLine("Read operation succeeded for SAS {0}", sasUri);
        Console.WriteLine();
    }
    catch (StorageRequestFailedException e)
    {
        // Check for a 403 (Forbidden) error. If the SAS is invalid, 
        // Azure Storage returns this error.
        if (e.Status == 403)
        {
            Console.WriteLine("Read operation failed for SAS {0}", sasUri);
            Console.WriteLine("Additional error information: " + e.Message);
            Console.WriteLine();
        }
        else
        {
            Console.WriteLine(e.Message);
            Console.ReadLine();
            throw;
        }
    }
}

.NET で開発するためのリソースResources for development with .NET

次のリンクからは、.NET 用の Azure Storage クライアントライブラリを使用する開発者にとって役立つリソースが提供されます。The links below provide useful resources for developers using the Azure Storage client library for .NET.

Azure Storage 共通 APIAzure Storage common APIs

BLOB ストレージ APIBlob storage APIs

.NET ツール.NET tools

関連項目See also