feat: add SAS token authentication for Azure Blob Storage (#148)

Author: hasethuraman

cpp/azure/azcache_provider/azcache_provider_loader.cc

@@ -204,7 +204,7 @@ CacheLibHandle::~CacheLibHandle()
     // Note: we intentionally do NOT call dlclose() here.
     lib_handle = nullptr;
 
-    LOG(DEBUG) << "AzCacheProvider: released cache provider handle";
+    LOG(INFO) << "AzCacheProvider: released cache provider handle";
 }
 
 // --- AzCacheProviderLoader implementation ---
@@ -297,6 +297,7 @@ AzCacheProviderLoader::AzCacheProviderLoader(const CacheProviderConfig& config)
     {
         _enabled = true;
     }
+    LOG(INFO) << "AzCacheProvider: cache provider is " << (_enabled ? "enabled" : "disabled");
 }
 
 AzCacheProviderLoader::~AzCacheProviderLoader()

cpp/azure/azure.h

@@ -11,10 +11,13 @@
 // 2. Authentication methods (checked in this order):
 //    a. Connection string (Azurite testing only, requires AZURITE_TESTING build):
 //       - Set AZURE_STORAGE_CONNECTION_STRING environment variable
-//    b. Storage account key:
+//    b. SAS token:
+//       - Set AZURE_STORAGE_ACCOUNT_NAME and AZURE_STORAGE_SAS_TOKEN environment variables
+//       - Token is appended as query string to the service URL
+//    c. Storage account key:
 //       - Set AZURE_STORAGE_ACCOUNT_NAME and AZURE_STORAGE_ACCOUNT_KEY environment variables
 //       - Uses StorageSharedKeyCredential
-//    c. DefaultAzureCredential:
+//    d. DefaultAzureCredential (Recommended):
 //       - Set AZURE_STORAGE_ACCOUNT_NAME environment variable
 //       - DefaultAzureCredential tries multiple authentication methods in order:
 //         * Environment variables (AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET) for service principal
@@ -29,8 +32,10 @@
 //
 // Example usage:
 // key-based: AZURE_STORAGE_ACCOUNT_NAME="account" AZURE_STORAGE_ACCOUNT_KEY="key" <streamer app> az://container/path
+// sas-token: AZURE_STORAGE_ACCOUNT_NAME="account" AZURE_STORAGE_SAS_TOKEN="sv=2021-08-06&ss=b&..." <streamer app> az://container/path
 // managed:   AZURE_STORAGE_ACCOUNT_NAME="account" <streamer app> az://container/path
 // azurite:   AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=http;..." <streamer app> az://container/path
+// sovereign: AZURE_STORAGE_ACCOUNT_NAME="account" AZURE_STORAGE_ENDPOINT_SUFFIX="blob.core.chinacloudapi.cn" <streamer app> az://container/path
 // programmatic: Pass credentials in ObjectClientConfig_t.initial_params
 
 namespace runai::llm::streamer::impl::azure

cpp/azure/client/client.cc

@@ -35,11 +35,14 @@ AzureClient::AzureClient(const common::backend_api::ObjectClientConfig_t& config
     // ClientConfiguration reads environment variables
     _account_name = _client_config.account_name;
     _account_key = _client_config.account_key;
+    _sas_token = _client_config.sas_token;
+    _endpoint_suffix = _client_config.endpoint_suffix;
 #ifdef AZURITE_TESTING
     _connection_string = _client_config.connection_string;
 #endif
 
     // Parse configuration parameters from API (overrides environment)
+    // Empty values are treated as unset to avoid overriding env vars with no-ops
     auto ptr = config.initial_params;
     if (ptr)
     {
@@ -48,6 +51,11 @@ AzureClient::AzureClient(const common::backend_api::ObjectClientConfig_t& config
             const char* key = ptr->key;
             const char* value = ptr->value;
 
+            if (!value || strlen(value) == 0)
+            {
+                continue;
+            }
+
             if (strcmp(key, "account_name") == 0)
             {
                 _account_name = std::string(value);
@@ -56,6 +64,14 @@ AzureClient::AzureClient(const common::backend_api::ObjectClientConfig_t& config
             {
                 _account_key = std::string(value);
             }
+            else if (strcmp(key, "sas_token") == 0)
+            {
+                _sas_token = std::string(value);
+            }
+            else if (strcmp(key, "endpoint_suffix") == 0)
+            {
+                _endpoint_suffix = std::string(value);
+            }
 #ifdef AZURITE_TESTING
             else if (strcmp(key, "connection_string") == 0)
             {
@@ -94,17 +110,27 @@ AzureClient::AzureClient(const common::backend_api::ObjectClientConfig_t& config
         } else
 #endif
         if (_account_name.has_value()) {
-            if (_account_key.has_value()) {
+            if (_sas_token.has_value()) {
+                // Use SAS token authentication (no credential object needed)
+                // The token is appended as query string to the service URL
+                std::string token = _sas_token.value();
+                if (!token.empty() && token[0] == '?') {
+                    token = token.substr(1);
+                }
+                std::string url = "https://" + _account_name.value() + "." + _endpoint_suffix + "?" + token;
+                _blob_service_client = std::make_shared<BlobServiceClient>(url, options);
+                LOG(DEBUG) << "Azure client initialized with SAS token for account: " << _account_name.value();
+            } else if (_account_key.has_value()) {
                 // Use StorageSharedKeyCredential (account name + account key)
-                std::string url = "https://" + _account_name.value() + ".blob.core.windows.net";
+                std::string url = "https://" + _account_name.value() + "." + _endpoint_suffix;
                 auto credential = std::make_shared<Azure::Storage::StorageSharedKeyCredential>(
                     _account_name.value(), _account_key.value());
                 _blob_service_client = std::make_shared<BlobServiceClient>(url, credential, options);
                 LOG(DEBUG) << "Azure client initialized with StorageSharedKeyCredential for account: " << _account_name.value();
             } else {
                 // Use DefaultAzureCredential (managed identity, Azure CLI, environment variables, etc.)
                 // Reference: https://learn.microsoft.com/en-us/azure/developer/cpp/sdk/authentication
-                std::string url = "https://" + _account_name.value() + ".blob.core.windows.net";
+                std::string url = "https://" + _account_name.value() + "." + _endpoint_suffix;
                 // Share a single DefaultAzureCredential across all clients in the process to better
                 // utilize token caching and reduce chances of overwhelming authentication sources
                 // (e.g., IMDS) which can result in fatal throttling errors.
@@ -145,6 +171,8 @@ bool AzureClient::verify_credentials(const common::backend_api::ObjectClientConf
     ClientConfiguration temp_config;
     std::optional<std::string> temp_account_name = temp_config.account_name;
     std::optional<std::string> temp_account_key = temp_config.account_key;
+    std::optional<std::string> temp_sas_token = temp_config.sas_token;
+    std::string temp_endpoint_suffix = temp_config.endpoint_suffix;
 #ifdef AZURITE_TESTING
     std::optional<std::string> temp_connection_string = temp_config.connection_string;
 #endif
@@ -155,6 +183,8 @@ bool AzureClient::verify_credentials(const common::backend_api::ObjectClientConf
         for (size_t i = 0; i < config.num_initial_params; ++i, ++ptr) {
             if (strcmp(ptr->key, "account_name") == 0) temp_account_name = std::string(ptr->value);
             else if (strcmp(ptr->key, "account_key") == 0) temp_account_key = std::string(ptr->value);
+            else if (strcmp(ptr->key, "sas_token") == 0) temp_sas_token = std::string(ptr->value);
+            else if (strcmp(ptr->key, "endpoint_suffix") == 0) temp_endpoint_suffix = std::string(ptr->value);
 #ifdef AZURITE_TESTING
             else if (strcmp(ptr->key, "connection_string") == 0) temp_connection_string = std::string(ptr->value);
 #endif
@@ -166,7 +196,7 @@ bool AzureClient::verify_credentials(const common::backend_api::ObjectClientConf
         return (_connection_string == temp_connection_string);
     }
 #endif
-    return (_account_name == temp_account_name) && (_account_key == temp_account_key);
+    return (_account_name == temp_account_name) && (_account_key == temp_account_key) && (_sas_token == temp_sas_token) && (_endpoint_suffix == temp_endpoint_suffix);
 }
 
 common::backend_api::Response AzureClient::async_read_response()

cpp/azure/client/client.h

@@ -47,6 +47,8 @@ struct AzureClient : common::IClient
     // Azure credentials
     std::optional<std::string> _account_name;
     std::optional<std::string> _account_key;
+    std::optional<std::string> _sas_token;
+    std::string _endpoint_suffix;
 #ifdef AZURITE_TESTING
     std::optional<std::string> _connection_string;
 #endif

cpp/azure/client_configuration/client_configuration.cc

@@ -28,6 +28,20 @@ ClientConfiguration::ClientConfiguration()
         account_key = acct_key;
     }
 
+    // SAS token for Shared Access Signature authentication
+    const auto sas = utils::getenv<std::string>("AZURE_STORAGE_SAS_TOKEN", "");
+    if (!sas.empty()) {
+        LOG(DEBUG) << "Using AZURE_STORAGE_SAS_TOKEN for authentication";
+        sas_token = sas;
+    }
+
+    // Endpoint suffix for sovereign clouds (default: blob.core.windows.net)
+    const auto suffix = utils::getenv<std::string>("AZURE_STORAGE_ENDPOINT_SUFFIX", "");
+    if (!suffix.empty()) {
+        LOG(DEBUG) << "Using custom endpoint suffix: " << suffix;
+        endpoint_suffix = suffix;
+    }
+
     // Account name configuration from environment variable
     // Authentication uses DefaultAzureCredential which supports:
     // - Environment variables (AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET)

cpp/azure/client_configuration/client_configuration.h

@@ -11,6 +11,8 @@ struct ClientConfiguration
     // Azure client configuration options
     std::optional<std::string> account_name;
     std::optional<std::string> account_key;
+    std::optional<std::string> sas_token;
+    std::string endpoint_suffix = "blob.core.windows.net";
 #ifdef AZURITE_TESTING
     // Connection string is only available for Azurite/local testing
     std::optional<std::string> connection_string;

docs/src/env-vars.md

@@ -114,7 +114,7 @@ String
 
 ### AZURE_STORAGE_ACCOUNT_NAME
 
-Azure Storage account name. Used with DefaultAzureCredential for authentication.
+Azure Storage account name. Required for all Azure Blob Storage authentication methods.
 
 #### Values accepted
 
@@ -124,6 +124,32 @@ String
 
 None
 
+### AZURE_STORAGE_SAS_TOKEN
+
+Shared Access Signature (SAS) token for Azure Blob Storage authentication. Used with AZURE_STORAGE_ACCOUNT_NAME.
+
+The value should be the query string portion of the SAS URI (with or without leading `?`), e.g. `sv=2021-08-06&ss=b&srt=co&sp=rl&se=...&sig=...`
+
+#### Values accepted
+
+String
+
+#### Default value
+
+None
+
+### AZURE_STORAGE_ENDPOINT_SUFFIX
+
+Azure Blob Storage endpoint suffix. Override for sovereign clouds (China, US Government) or Azure Stack.
+
+#### Values accepted
+
+String (e.g. `blob.core.chinacloudapi.cn`, `blob.core.usgovcloudapi.net`)
+
+#### Default value
+
+`blob.core.windows.net`
+
 ### RUNAI_STREAMER_EXPERIMENTAL_AZURE_CACHE_ENABLED
 
 > **Experimental** — This feature is under active development and may change in future releases.

docs/src/usage.md

@@ -159,7 +159,11 @@ file_path = "az://my-container/my/file/path.safetensors"
 
 ##### Azure Authentication
 
-The streamer uses Azure's DefaultAzureCredential for authentication, which provides a seamless authentication experience across development and production environments.
+The streamer supports multiple authentication methods for Azure Blob Storage, checked in this order:
+
+1. **SAS token** (`AZURE_STORAGE_SAS_TOKEN`)
+2. **Storage account key** (`AZURE_STORAGE_ACCOUNT_KEY`)
+3. **DefaultAzureCredential** (Recommended) — managed identity, Azure CLI, service principal, etc.
 
 ###### Default Azure Credential (Recommended)
 
@@ -198,6 +202,17 @@ export AZURE_STORAGE_ACCOUNT_NAME="myaccount"
 # No additional configuration needed - managed identity is detected automatically
 ```
 
+###### SAS Token
+
+To authenticate using a Shared Access Signature:
+
+```bash
+export AZURE_STORAGE_ACCOUNT_NAME="myaccount"
+export AZURE_STORAGE_SAS_TOKEN="sv=2021-08-06&ss=b&srt=co&sp=rl&se=2026-01-01T00:00:00Z&sig=..."
+```
+
+> **Note:** The SAS token value should be the query string portion of the SAS URI without the leading `?`.
+
 ##### Azure Blob Cache Provider (Experimental)
 
 > **Experimental** — This feature is under active development and may change in future releases.

py/runai_model_streamer_azure/runai_model_streamer_azure/credentials/credentials.py

@@ -11,26 +11,32 @@ class AzureCredentials:
 
     Authentication methods (checked in this order):
     1. Connection string: Set AZURE_STORAGE_CONNECTION_STRING
-    2. Storage account key: Set AZURE_STORAGE_ACCOUNT_NAME and AZURE_STORAGE_ACCOUNT_KEY
-    3. DefaultAzureCredential: Set AZURE_STORAGE_ACCOUNT_NAME (uses Managed Identity, Azure CLI, etc.)
+    2. SAS token: Set AZURE_STORAGE_ACCOUNT_NAME and AZURE_STORAGE_SAS_TOKEN
+    3. Storage account key: Set AZURE_STORAGE_ACCOUNT_NAME and AZURE_STORAGE_ACCOUNT_KEY
+    4. DefaultAzureCredential: Set AZURE_STORAGE_ACCOUNT_NAME (uses Managed Identity, Azure CLI, etc.)
 
     If values are not provided explicitly, they are loaded from environment variables:
     - AZURE_STORAGE_CONNECTION_STRING
     - AZURE_STORAGE_ACCOUNT_NAME
     - AZURE_STORAGE_ACCOUNT_KEY
+    - AZURE_STORAGE_SAS_TOKEN
     """
 
     def __init__(
         self,
         account_name: Optional[str] = None,
         account_key: Optional[str] = None,
+        sas_token: Optional[str] = None,
         connection_string: Optional[str] = None,
+        endpoint_suffix: Optional[str] = None,
         credential: Optional[DefaultAzureCredential] = None
     ):
         self.connection_string = connection_string or os.environ.get("AZURE_STORAGE_CONNECTION_STRING")
         self.account_name = account_name or os.environ.get("AZURE_STORAGE_ACCOUNT_NAME")
         self.account_key = account_key or os.environ.get("AZURE_STORAGE_ACCOUNT_KEY")
-        if credential is None and not self.connection_string and not self.account_key:
+        self.sas_token = sas_token or os.environ.get("AZURE_STORAGE_SAS_TOKEN")
+        self.endpoint_suffix = endpoint_suffix or os.environ.get("AZURE_STORAGE_ENDPOINT_SUFFIX", "blob.core.windows.net")
+        if credential is None and not self.connection_string and not self.account_key and not self.sas_token:
             credential = DefaultAzureCredential()
         self.credential = credential
         self._validate()

py/runai_model_streamer_azure/runai_model_streamer_azure/files/files.py

@@ -20,8 +20,9 @@ def _create_client(credentials: Optional[AzureCredentials] = None) -> BlobServic
 
     Authentication priority:
     1. Connection string (AZURE_STORAGE_CONNECTION_STRING) - for local testing with Azurite
-    2. Storage account key (AZURE_STORAGE_ACCOUNT_NAME + AZURE_STORAGE_ACCOUNT_KEY)
-    3. DefaultAzureCredential with account URL - for production
+    2. SAS token (AZURE_STORAGE_ACCOUNT_NAME + AZURE_STORAGE_SAS_TOKEN)
+    3. Storage account key (AZURE_STORAGE_ACCOUNT_NAME + AZURE_STORAGE_ACCOUNT_KEY)
+    4. DefaultAzureCredential with account URL - for production
 
     Args:
         credentials: Optional AzureCredentials object
@@ -39,17 +40,27 @@ def _create_client(credentials: Optional[AzureCredentials] = None) -> BlobServic
             user_agent=_USER_AGENT
         )
 
+    # Use account name + SAS token if available
+    if credentials.sas_token and credentials.account_name:
+        token = credentials.sas_token.lstrip("?")
+        account_url = f"https://{credentials.account_name}.{credentials.endpoint_suffix}"
+        return BlobServiceClient(
+            account_url=account_url,
+            credential=token,
+            user_agent=_USER_AGENT
+        )
+
     # Use account name + account key if available (StorageSharedKeyCredential)
     if credentials.account_key and credentials.account_name:
-        account_url = f"https://{credentials.account_name}.blob.core.windows.net"
+        account_url = f"https://{credentials.account_name}.{credentials.endpoint_suffix}"
         return BlobServiceClient(
             account_url=account_url,
             credential=credentials.account_key,
             user_agent=_USER_AGENT
         )
 
     # Use account name + DefaultAzureCredential (for production)
-    account_url = f"https://{credentials.account_name}.blob.core.windows.net"
+    account_url = f"https://{credentials.account_name}.{credentials.endpoint_suffix}"
     return BlobServiceClient(
         account_url=account_url,
         credential=credentials.credential,