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

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 that is 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.

ユーザー委任 SAS により、ストレージ アカウント キーで署名された SAS のセキュリティが向上します。A user delegation SAS offers superior security to a SAS that is signed with the storage account key. Microsoft では、ユーザー委任 SAS を可能な限り使用することを推奨しています。Microsoft recommends using a user delegation SAS when possible. 詳細については、「Shared Access Signatures (SAS) でデータの制限付きアクセスを付与する」を参照してください。For more information, see Grant limited access to data with shared access signatures (SAS).

この記事では、Azure Active Directory (Azure AD) 資格情報を使用して バージョン 12 の .NET 用 Azure Storage クライアント ライブラリを使用するコンテナーまたは BLOB のユーザー委任 SAS を作成する方法について説明します。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 version 12.

ユーザー委任 SAS についてAbout the user delegation SAS

コンテナーまたは 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 を所有するすべてのクライアントは、その 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).

データにアクセスするための Azure ロールを割り当るAssign Azure roles for access to data

Azure AD セキュリティ プリンシパルが Blob データにアクセスしようとする場合、そのセキュリティ プリンシパルはリソースへのアクセス許可を保持している必要があります。When an Azure AD security principal attempts to access blob data, that security principal must have permissions to the resource. セキュリティ プリンシパルが Azure 内のマネージド ID であるか、開発環境でコードを実行している Azure AD ユーザー アカウントであるかにかかわらず、Azure Storage での BLOB データへのアクセスを許可する Azure ロールをセキュリティ プリンシパルに割り当てる必要があります。Whether the security principal is a managed identity in Azure or an Azure AD user account running code in the development environment, the security principal must be assigned an Azure role that grants access to blob data in Azure Storage. Azure RBAC 経由でのアクセス許可の割り当てについては、Azure Active Directory を使用した Azure BLOB とキューへのアクセスの承認に関する記事の「アクセス権に Azure ロールを割り当てる」というタイトルのセクションを参照してください。For information about assigning permissions via Azure RBAC, see the section titled Assign Azure roles for access rights in Authorize access to Azure blobs and queues using Azure Active Directory.

クライアント ライブラリ パッケージをインストールするInstall client library packages

注意

ここに示す例では、Azure Storage クライアント ライブラリバージョン 12 を使用します。The examples shown here use the Azure Storage client library version 12. バージョン 12 クライアント ライブラリは、Azure SDK に含まれています。The version 12 client library is part of the Azure SDK. Azure SDK の詳細については、GitHub で Azure SDK リポジトリを参照してください。For more information about the Azure SDK, see the Azure SDK repository on GitHub.

BLOB ストレージ パッケージをインストールするには、NuGet パッケージ マネージャー コンソールから次のコマンドを実行します。To install the Blob storage package, run the following command from the NuGet package manager console:

Install-Package Azure.Storage.Blobs

ここに示す例では、Azure AD の資格情報で認証するために、.NET 用 Azure ID クライアント ライブラリの最新バージョンも使用されます。The examples shown here also use the latest version of the Azure Identity client library for .NET to authenticate with Azure AD credentials. パッケージをインストールするには、NuGet パッケージ マネージャー コンソールから次のコマンドを実行します。To install the package, run the following command from the NuGet package manager console:

Install-Package Azure.Identity

Azure Storage から Azure ID クライアント ライブラリを使用して認証する方法の詳細については、Azure Active Directory と Azure リソースのマネージ ID を使用した BLOB およびキューへのアクセスの認証に関するページの「Azure ID ライブラリを使用した認証」を参照してください。To learn more about how to authenticate with the Azure Identity client library from Azure Storage, see the section titled Authenticate with the Azure Identity library in Authorize access to blobs and queues with Azure Active Directory and managed identities for Azure Resources.

認証済みのトークン資格情報を取得するGet an authenticated token credential

Azure Storage への要求を承認するためにコード上で使用できるトークン資格情報を取得するには、DefaultAzureCredential クラスのインスタンスを作成します。To get a token credential that your code can use to authorize requests to Azure Storage, create an instance of the DefaultAzureCredential class.

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

// 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 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:

// Get a user delegation key for the Blob service that's valid for seven days.
// You can 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.SignedStartsOn);
Console.WriteLine("Key signed expiry: {0}", key.SignedExpiresOn);
Console.WriteLine("Key signed object ID: {0}", key.SignedObjectId);
Console.WriteLine("Key signed tenant ID: {0}", key.SignedTenantId);
Console.WriteLine("Key signed service: {0}", key.SignedService);
Console.WriteLine("Key signed version: {0}", key.SignedVersion);

BLOB 用のユーザー委任 SAS を取得するGet a user delegation SAS for a blob

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

async static Task<Uri> GetUserDelegationSasBlob(BlobClient blobClient)
{
    BlobServiceClient blobServiceClient =
        blobClient.GetParentBlobContainerClient().GetParentBlobServiceClient();

    // Get a user delegation key for the Blob service that's valid for 7 days.
    // You can use the key to generate any number of shared access signatures 
    // over the lifetime of the key.
    Azure.Storage.Blobs.Models.UserDelegationKey userDelegationKey =
        await blobServiceClient.GetUserDelegationKeyAsync(DateTimeOffset.UtcNow,
                                                          DateTimeOffset.UtcNow.AddDays(7));

    // Create a SAS token that's also valid for 7 days.
    BlobSasBuilder sasBuilder = new BlobSasBuilder()
    {
        BlobContainerName = blobClient.BlobContainerName,
        BlobName = blobClient.Name,
        Resource = "b",
        StartsOn = DateTimeOffset.UtcNow,
        ExpiresOn = DateTimeOffset.UtcNow.AddDays(7)
    };

    // Specify read and write permissions for the SAS.
    sasBuilder.SetPermissions(BlobSasPermissions.Read |
                              BlobSasPermissions.Write);

    // Add the SAS token to the blob URI.
    BlobUriBuilder blobUriBuilder = new BlobUriBuilder(blobClient.Uri)
    {
        // Specify the user delegation key.
        Sas = sasBuilder.ToSasQueryParameters(userDelegationKey, 
                                              blobServiceClient.AccountName)
    };

    Console.WriteLine("Blob user delegation SAS URI: {0}", blobUriBuilder);
    Console.WriteLine();
    return blobUriBuilder.ToUri();
}

次の例では、前の例で作成されたユーザー委任 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).

static async Task ReadBlobWithSasAsync(Uri sasUri)
{
    // Try performing a read operation using the blob 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
    {
        Console.WriteLine("Blob contents:");

        // 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 (RequestFailedException 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;
        }
    }
}

コンテナー用のユーザー委任 SAS を取得するGet a user delegation SAS for a container

次のコード例は、コンテナー用のユーザー委任 SAS を生成する方法を示しています。The following code example shows how to generate a user delegation SAS for a container:

async static Task<Uri> GetUserDelegationSasContainer(BlobContainerClient blobContainerClient)
{
    BlobServiceClient blobServiceClient = blobContainerClient.GetParentBlobServiceClient();

    // Get a user delegation key for the Blob service that's valid for seven days.
    // You can use the key to generate any number of shared access signatures 
    // over the lifetime of the key.
    Azure.Storage.Blobs.Models.UserDelegationKey userDelegationKey =
        await blobServiceClient.GetUserDelegationKeyAsync(DateTimeOffset.UtcNow,
                                                          DateTimeOffset.UtcNow.AddDays(7));

    // Create a SAS token that's also valid for seven days.
    BlobSasBuilder sasBuilder = new BlobSasBuilder()
    {
        BlobContainerName = blobContainerClient.Name,
        Resource = "c",
        StartsOn = DateTimeOffset.UtcNow,
        ExpiresOn = DateTimeOffset.UtcNow.AddDays(7)
    };

    // Specify racwl permissions for the SAS.
    sasBuilder.SetPermissions(
        BlobContainerSasPermissions.Read |
        BlobContainerSasPermissions.Add |
        BlobContainerSasPermissions.Create |
        BlobContainerSasPermissions.Write |
        BlobContainerSasPermissions.List
        );

    // Add the SAS token to the container URI.
    BlobUriBuilder blobUriBuilder = new BlobUriBuilder(blobContainerClient.Uri)
    {
        // Specify the user delegation key.
        Sas = sasBuilder.ToSasQueryParameters(userDelegationKey,
                                              blobServiceClient.AccountName)
    };

    Console.WriteLine("Container user delegation SAS URI: {0}", blobUriBuilder);
    Console.WriteLine();
    return blobUriBuilder.ToUri();
}

次の例では、前の例で作成されたユーザー委任 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 ListBlobsWithSasAsync(Uri sasUri)
{
    // Try performing a listing operation using the container SAS provided.

    // Create a container client object for blob operations.
    BlobContainerClient blobContainerClient = new BlobContainerClient(sasUri, null);

    // List blobs in the container.
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = blobContainerClient.GetBlobsAsync().AsPages();

        // Enumerate the blobs returned for each page.
        await foreach (Azure.Page<BlobItem> blobPage in resultSegment)
        {
            foreach (BlobItem blobItem in blobPage.Values)
            {
                Console.WriteLine("Blob name: {0}", blobItem.Name);
            }
            Console.WriteLine();
        }

        Console.WriteLine();
        Console.WriteLine("Blob listing operation succeeded for SAS {0}", sasUri);
    }
    catch (RequestFailedException e)
    {
        // Check for a 403 (Forbidden) error. If the SAS is invalid, 
        // Azure Storage returns this error.
        if (e.Status == 403)
        {
            Console.WriteLine("Blob listing 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