Storage Account

Introduction

An Azure storage account serves as a centralized container for all your data objects, including blobs, files, queues, and tables. It provides a unique, globally accessible namespace reachable via HTTP or HTTPS. For more information, see Overview of storage accounts.

LocalStack for Azure provides a local environment for building and testing applications that make use of blobs, files, queues, and tables. For more information, see:

The supported APIs are available on our API Coverage section, which provides information on the extent of Storage Account’s integration with LocalStack.

Getting started

This guide is designed for users new to Azure Storage Accounts and assumes basic knowledge of the Azure CLI and our lstk az proxy.

Launch LocalStack using your preferred method. For more information, see Introduction to LocalStack for Azure. Once the container is running, enable Azure CLI interception by running:

lstk az start-interception

This command points the az CLI away from the public Azure management REST API and toward the LocalStack for Azure emulator API. To revert this configuration, run:

lstk az stop-interception

This reconfigures the az CLI to send commands to the official Azure management REST API.

Create a resource group

Create a resource group for your storage account resources:

az group create \
  --name rg-storage-demo \
  --location westeurope

{
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-storage-demo",
  "location": "westeurope",
  "managedBy": null,
  "name": "rg-storage-demo",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": null,
  "type": "Microsoft.Resources/resourceGroups"
}

Create a storage account

Create a storage account with the StorageV2 kind and Standard_LRS SKU:

az storage account create \
  --name stordoc86acct \
  --resource-group rg-storage-demo \
  --location westeurope \
  --sku Standard_LRS \
  --kind StorageV2

{
  ...
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-storage-demo/providers/Microsoft.Storage/storageAccounts/stordoc86acct",
  ...
  "kind": "StorageV2",
  "location": "westeurope",
  "name": "stordoc86acct",
  ...
  "primaryEndpoints": {
    "blob": "https://stordoc86acct.blob.core.azure.localhost.localstack.cloud:4566",
    "queue": "https://stordoc86acct.queue.core.azure.localhost.localstack.cloud:4566",
    "table": "https://stordoc86acct.table.core.azure.localhost.localstack.cloud:4566",
    ...
  },
  "provisioningState": "Succeeded",
  ...
}

Authentication

There are three ways to authenticate storage commands against the emulator:

Storage account key

Retrieve the account key and pass it with --account-name and --account-key:

ACCOUNT_KEY=$(az storage account keys list \
  --account-name stordoc86acct \
  --resource-group rg-storage-demo \
  --query "[0].value" \
  --output tsv)

az storage container list \
  --account-name stordoc86acct \
  --account-key "$ACCOUNT_KEY"

Use --auth-mode login to authenticate with the current session credentials:

az storage container list \
  --account-name stordoc86acct \
  --auth-mode login

Connection string

Bundle the account name and key into a single value:

CONNECTION_STRING=$(az storage account show-connection-string \
  --name stordoc86acct \
  --resource-group rg-storage-demo \
  --query connectionString -o tsv)

az storage container list \
  --connection-string "$CONNECTION_STRING"

The remaining examples in this guide use connection strings for brevity.

Manage account keys and connection string

List the storage account access keys:

az storage account keys list \
  --account-name stordoc86acct \
  --resource-group rg-storage-demo

[
  {
    "keyName": "key1",
    "permissions": "FULL",
    "value": "MWFjYTgyZjgtYzU0My00NjE0LThmZDctNzlkODg5ZjU4ZTE5",
    "..."
  },
  {
    "keyName": "key2",
    "permissions": "FULL",
    "value": "NzliNzVhN2EtYTcwZC00ZTg4LWJkMTQtYjg4MWNlMDJjZDcx",
    "..."
  }
]

Regenerate the primary key:

az storage account keys renew \
  --account-name stordoc86acct \
  --resource-group rg-storage-demo \
  --key key1

Fetch a connection string for data-plane operations:

az storage account show-connection-string \
  --name stordoc86acct \
  --resource-group rg-storage-demo

{
  "connectionString": "DefaultEndpointsProtocol=https;EndpointSuffix=core.azure.localhost.localstack.cloud:4566;AccountName=stordoc86acct;AccountKey=YWQ5Y2Q2NDYtZTJmOC00ZjU3LWFmOTEtNzk5MjAxNzE1OWQx;BlobEndpoint=https://stordoc86acct.blob.core.azure.localhost.localstack.cloud:4566;FileEndpoint=https://stordoc86acct.file.core.azure.localhost.localstack.cloud:4566;QueueEndpoint=https://stordoc86acct.queue.core.azure.localhost.localstack.cloud:4566;TableEndpoint=https://stordoc86acct.table.core.azure.localhost.localstack.cloud:4566"
}

Data plane authentication

The emulator validates data-plane requests to Blob, Queue, and Table Storage as Azure does:

Shared Key and SharedKeyLite: The signature is checked against key1 and key2. A bad signature returns AuthenticationFailed (403).
SAS tokens: Account, service, stored access policy, and user delegation SAS tokens are checked for signature, validity window, source IP, protocol, service, resource type, and permission.
Bearer tokens: The emulator checks only that a token is present.
Anonymous requests: These return NoAuthenticationInformation (401), unless the account allows public access and the request reads a public container or blob.

Generate an account SAS and use it to list containers:

SAS=$(az storage account generate-sas \
  --account-name stordoc86acct \
  --account-key "$ACCOUNT_KEY" \
  --services b \
  --resource-types sco \
  --permissions rl \
  --expiry 2030-01-01T00:00Z \
  --output tsv)

az storage container list \
  --account-name stordoc86acct \
  --sas-token "$SAS"

A SAS that lacks a permission is refused. A token with a wrong signature fails with an authentication error:

ERROR:
Authentication failure. This may be caused by either invalid account key, connection string or sas token value provided for your storage account.

To refuse key-based requests, set allowSharedKeyAccess to false:

az storage account update \
  --name stordoc86acct \
  --resource-group rg-storage-demo \
  --allow-shared-key-access false

az storage container list \
  --connection-string "$CONNECTION_STRING"

ERROR: Key based authentication is not permitted on this storage account.
ErrorCode:KeyBasedAuthenticationNotPermitted

The management API also supports listAccountSas, listServiceSas, and revokeUserDelegationKeys.

Features

The Storage Account emulator supports the following features:

Control plane REST API: Storage account CRUD (create, read, update, delete, list), account key management, and name availability checks via Azure Resource Manager.
Multiple authentication modes: Storage account key, login credentials, and connection strings.
Storage account management: Create, update, delete, and list storage accounts. Supports StorageV2, BlobStorage, and Storage account kinds with configurable SKU, access tier, and TLS version.
Scoped lookups: Get and list operations respect the subscription and resource group in the request.
Account properties: Documented account properties are stored and returned. A partial update (PATCH) keeps the fields you omit, and create and update requests are validated as Azure does.
Account key management: List and regenerate storage account keys (key1/key2). Regenerating a key returns the keys.
Connection string generation: Retrieve ready-to-use connection strings containing all service endpoints (Blob, Queue, Table, File).
SAS management: Generate account and service SAS tokens through the management API, and revoke user delegation keys.
Data plane authentication: Shared Key, SharedKeyLite, and SAS requests are validated, and the allowSharedKeyAccess and allowBlobPublicAccess settings are enforced.
Blob range restore validation: restoreBlobRanges validates the request, such as the restore time and the blob ranges, as Azure does.
Encryption scopes: Create, update, get, and list encryption scopes.
Account policies: Create or update, get, and delete the lifecycle management policy, and create or update, get, list, and delete blob inventory policies and object replication policies.
Local users: Create or update, get, list, and delete local users, list their keys, and regenerate their passwords.
Account migrations: Start a customer-initiated migration and get its status, run an account failover, and upgrade an account to a hierarchical namespace or abort that upgrade.
Validation: Requests for these sub-resources are validated, and return the same error codes, as Azure does.

Limitations

Data Lake and static website endpoints: The dfs and web primary endpoints point at the emulator, but the emulator doesn’t serve Data Lake or static website requests.
Account policies are not executed: Lifecycle management, blob inventory, and object replication policies are stored and returned, but the emulator never runs them. Blobs are not tiered or deleted, no inventory reports are generated, and no objects are replicated.
No SFTP endpoint for local users: Local users are stored and their keys and passwords are managed, but the emulator does not serve SFTP.
Migrations complete instantly: Account migrations, failovers, and the hierarchical namespace upgrade complete immediately, without moving data.
Header validation: Unsupported request headers or parameters are silently accepted instead of being rejected.
API version enforcement: The emulator does not validate the x-ms-version header; all API versions are accepted.
Blob range restore does not restore data: A valid restoreBlobRanges request returns a restore with status Failed, because the emulator keeps no blob history. If a container has an immutability policy, the failure reason says so.
Bearer tokens are not inspected: Data-plane requests with a bearer token succeed whenever a token is present, unless you enable RBAC enforcement.
User delegation SAS is not re-authorized: The emulator doesn’t re-check the RBAC of the principal that requested the user delegation key when the SAS is used, and doesn’t bind a user-bound SAS (sduoid) to the caller’s token.
SAS source IP restrictions: The emulator sees the Docker or loopback address, not your public address, so a SAS restricted to your public IP is refused.
Anonymous requests without x-ms-version: When an account disallows public access, Azure answers an anonymous request that has no x-ms-version header with 409 PublicAccessNotPermitted. The emulator answers 401.

Samples

The following samples demonstrate how to use Storage Accounts with LocalStack for Azure:

API Coverage

51 of 81 operations implemented

Operation ▲	Implemented ▼

Page 1 of 0

Was this page helpful?