AZURE_BLOB Provider

The AZURE_BLOB provider uses Microsoft Azure Blob Storage for storing files. Azure Blob Storage is ideal for cloud-native deployments and cluster configurations where multiple webPDF Server nodes need to share file storage.

Overview

• Provider Name: AZURE_BLOB
• Supports: File Storage only
• Configuration File: provider-azure-blob.json
• Use Case: Azure cloud deployments, cluster file storage, geo-redundant storage
• Protocol: Azure Storage REST API

Features

• ✓ Microsoft Azure native integration
• ✓ High-performance blob storage
• ✓ Cluster-ready with shared file access
• ✓ Multiple redundancy options (LRS, ZRS, GRS, RA-GRS)
• ✓ Integrated Azure security features
• ✓ Lifecycle management and tiering
• ✓ ETag-based local caching for improved performance
• ✓ Concurrent file access
• ✓ Automatic retry with exponential backoff
• ✓ Four authentication methods (Shared Key, SAS Token, Connection String, Managed Identity)
• ✓ Automatic container creation with cluster race condition handling
• ✗ Requires Azure Storage account
• ✗ Cloud-dependent (requires internet connectivity)

Prerequisites

• Azure Storage Account (General Purpose v2 or Blob Storage)
• Azure Storage Account connection string or access keys
• Container created or automatic container creation enabled
• Network connectivity to Azure (direct or via VPN/ExpressRoute)

Configuration

provider.json

{
  "fileStorage": {
    "name": "AZURE_BLOB",
    "checks": {
      "enabled": true,
      "interval": 10000
    }
  }
}

provider-azure-blob.json

Configuration file for Azure Blob Storage:

{
  "url": "https://webpdfstorageacct.blob.core.windows.net",
  "username": "webpdfstorageacct",
  "password": "storage-account-key-or-connection-string",
  "containerName": "webpdf-files",
  "authenticationType": "SHARED_KEY"
}

Configuration Attributes

Required Attributes

Attribute	Type	Description	Example
url	string	Azure Blob Storage endpoint URL	https://account.blob.core.windows.net
username	string	Storage account name	webpdfstorageacct
password	string	Storage account key, SAS token, or connection string (depends on authenticationType)	(see below)

Optional Attributes

Attribute	Type	Description	Default
containerName	string	Azure container name for file storage	Auto-generated
authenticationType	string	Authentication method: SHARED_KEY, SAS_TOKEN, CONNECTION_STRING, DEFAULT_AZURE_CREDENTIAL	SHARED_KEY

Authentication Methods

The Azure Blob provider supports four authentication types. The password field serves different purposes depending on the authentication method:

1. Shared Key Authentication (Default)

Uses storage account name and account key:

{
  "url": "https://webpdfstorageacct.blob.core.windows.net",
  "password": "base64-encoded-account-key",
  "authenticationType": "SHARED_KEY"
}

Implementation details:

• Supports both Azurite format (http://host:port/accountname) and Azure format (https://accountname.blob.core.windows.net)
• The URL must include the account name
• Account name is extracted from the URL

2. SAS Token Authentication

Uses Shared Access Signature tokens for time-limited access:

{
  "url": "https://webpdfstorageacct.blob.core.windows.net",
  "password": "?sv=2021-06-08&ss=b&srt=sco&sp=rwdlacx&se=...",
  "authenticationType": "SAS_TOKEN"
}

Note: The password field contains the SAS token when using this method and the URL must include the account name.

Minimum SAS for an existing container. webPDF checks that the container exists with the first page of the blob listing in the container, at startup, in the status checks, in the provider probe and in the validation in the Admin Portal. It requests neither the properties of the storage account nor the list of containers. A SAS that is restricted to the existing container (a service SAS) with the permissions r (read), w (write), d (delete) and l (list) is therefore sufficient for operation: read and ETag check, upload and overwrite, delete, and list. The permission l is required for every kind of access, also for an account SAS: without it the startup fails, because the existence of the container is checked with the listing. Creating a missing container needs the account key or an account SAS; with a SAS restricted to the container, create the container externally first. If the container does not exist and the access may not create it, the startup fails.

3. Connection String Authentication

Uses a complete Azure connection string:

{
  "password": "DefaultEndpointsProtocol=https;AccountName=webpdfstorageacct;AccountKey=...;EndpointSuffix=core.windows.net",
  "authenticationType": "CONNECTION_STRING"
}

Note: The password field contains the full connection string when using this method.

4. Default Azure Credential (Recommended for Production)

Uses Azure Managed Identity for passwordless authentication:

{
  "url": "https://webpdfstorageacct.blob.core.windows.net",
  "authenticationType": "DEFAULT_AZURE_CREDENTIAL"
}

Authentication chain:

• Managed Identity
• Environment Variables
• Azure CLI credentials
• Interactive browser login (development only)

Advantages:

• No credentials stored in configuration
• Automatic token rotation
• Enhanced security compliance

Container Naming

If containerName is not specified, or empty in the file, the name of the container is the namespace prefix (default webpdf). A configured name always takes precedence.

Example: with the prefix webpdf-prod, the container is webpdf-prod.

The derived name does not contain a version and is used by the server only; it is not written into the provider configuration. webPDF stores the blobs below the path of its namespace in the container, <prefix>/v<main>.<minor>-r<revision>/<sessionId>/<documentId>-<revision>, and reads, changes and deletes only there (see Namespace). Give every installation a prefix of its own and use lifecycle rules of the account only with a filter for the prefix.

tip

Azure container names must be lowercase and can contain only letters, numbers, and hyphens. The name must start with a letter or number.

Environment Variables

# Azure Blob file storage
WEBPDF_AZURE_BLOB_FILE_STORAGE_SETTINGS_URL=https://webpdfstorageacct.blob.core.windows.net
WEBPDF_AZURE_BLOB_FILE_STORAGE_SETTINGS_USERNAME=webpdfstorageacct
WEBPDF_AZURE_BLOB_FILE_STORAGE_SETTINGS_PASSWORD=account-key
WEBPDF_AZURE_BLOB_FILE_STORAGE_SETTINGS_CONTAINER_NAME=webpdf-files
WEBPDF_AZURE_BLOB_FILE_STORAGE_SETTINGS_AUTHENTICATION_TYPE=SHARED_KEY

AUTHENTICATION_TYPE accepts SHARED_KEY, SAS_TOKEN, CONNECTION_STRING and DEFAULT_AZURE_CREDENTIAL, regardless of case. In the provider JSON, authenticationType must be written exactly as listed.

Health Checks

Health checks verify connectivity to Azure Blob Storage:

{
  "fileStorage": {
    "name": "AZURE_BLOB",
    "checks": {
      "enabled": true,
      "interval": 15000
    }
  }
}

• enabled: Enable health checks (recommended: true)
• interval: Check interval in milliseconds (recommended: 10000 - 30000)

Health Check Implementation

The health check performs a lightweight connectivity test:

1. Container Listing Check - Validates network connectivity and authentication with the first page of the blob listing in the container (at most one entry); the properties of the storage account are not requested
2. Authentication Validation - Ensures credentials are valid
3. Service Availability - Confirms Azure Blob Storage service is accessible
4. Container Existence Check - Reports DOWN if the configured container does not exist

What is NOT checked:

• Write permissions (to minimize costs)
• Storage capacity

Health Status Results:

• UP - Connection established, authentication successful
• DOWN - Connection failed, authentication error, service unavailable, or container does not exist

Two Separate Status Checks

webPDF evaluates the storage status in two independent ways:

• Continuous status check of the storage client. The server checks the connection to the storage every 5 seconds, regardless of the checks setting. The result appears in the server log only. If the container does not exist, it reports DOWN with the reason Container '<name>' does not exist at '<endpoint>', and reports UP again once the container exists. If the storage does not answer at all (for example because it is paused or unreachable), the status changes to DOWN after 15 seconds with the reason Health check did not answer within 15 seconds; the status line keeps appearing in the server log during the outage. Requests are not affected by this limit: they keep waiting for the retries of the storage client.
• Readiness check of the provider. The checks section of provider.json (enabled, default false) controls whether the provider reports its status to the readiness endpoint (/health/ready). It is evaluated only when enabled is true, and it also reports DOWN if the container does not exist.

Security Considerations

Access Control

1. Managed Identity – Use Azure Managed Identity for passwordless authentication
2. SAS Tokens – Time-limited access with granular permissions
3. Account Keys – Rotate regularly (Azure supports two keys for zero-downtime rotation)
4. Private Endpoints – Use Azure Private Link for network isolation

Network Security

For Private Endpoints, simply use the private link URL in the url field:

{
  "url": "https://webpdfstorageacct.privatelink.blob.core.windows.net"
}

Encryption

• At Rest – Azure automatically encrypts data (256-bit AES)
• In Transit – Always use HTTPS endpoints
• Customer-Managed Keys – Optional integration with Azure Key Vault

warning

Never store Azure storage account keys directly in configuration files. Use environment variables, Azure Key Vault, or Managed Identity.

Azure Storage Tiers

Choose appropriate storage tier based on access patterns:

Tier	Use Case	Cost	Access Time
Hot	Frequent access	Higher storage, lower access	Immediate
Cool	Infrequent access (>30 days)	Lower storage, higher access	Immediate
Archive	Rare access (>180 days)	Lowest storage, highest access	Hours

note

webPDF typically uses Hot tier for active file storage. Consider lifecycle policies to move old files to Cool/Archive tiers.

Container Management

Automatic Container Creation

Azure Blob provider will attempt to create the container automatically if it doesn't exist.

An existing container is used as it is, whatever it holds; webPDF works only below the path of its namespace and never deletes the container. See Existing Buckets and Containers; give every installation a prefix of its own.

Implementation details:

• The provider checks for container existence during initialization
• If the container doesn't exist, it attempts to create it
• Handles race conditions in cluster environments (HTTP 409 Conflict)
• If another node creates the container simultaneously, the provider retrieves the existing container client

Missing Container at Runtime

During startup, webPDF creates a missing container (see above). While the server is running, it does not create a container that has disappeared. The container may be managed by the operator with its own settings such as encryption, access policies, or lifecycle rules, and an automatically created replacement would silently lack them.

If the container no longer exists while the server is running:

• Requests fail immediately, without retries, with FILE_STORAGE_STORE_CONTENT (-21003) when storing, FILE_STORAGE_RETRIEVE_CONTENT (-21001) when reading, or FILE_STORAGE_REMOVE_CONTENT (-21002) when removing content. The error description contains The container of the file storage does not exist.
• The server log contains an ERROR line with the container name, at most once per minute together with the number of further failures since the last report.
• The continuous status check reports DOWN (see Two Separate Status Checks).
• Documents that were stored in the lost container are gone. Reading them fails with -21001.

Create the container again with the configured name (for example with az storage container create). The nodes resume working without a restart.

Manual Container Creation

Using Azure CLI:

# Login to Azure
az login

# Create container
az storage container create \
  --name webpdf-files \
  --account-name webpdfstorageacct \
  --public-access off

Using Azure Portal:

1. Navigate to Storage Account
2. Select "Containers" under Data Storage
3. Click "+ Container"
4. Set name and private access level

Container Access Levels

• Private (recommended) – No anonymous access
• Blob – Anonymous read access to blobs
• Container – Anonymous read access to blobs and container

High Availability

Azure Blob Storage provides built-in redundancy:

Redundancy Options

1. LRS (Locally Redundant Storage) – 3 copies in single datacenter
2. ZRS (Zone Redundant Storage) – 3 copies across availability zones
3. GRS (Geo-Redundant Storage) – 6 copies across two regions
4. RA-GRS (Read-Access Geo-Redundant) – GRS + read access to secondary region

Recommended Configuration

For production webPDF clusters:

Storage Account Type: General Purpose v2
Performance: Standard
Replication: ZRS or GRS
Access Tier: Hot

Performance Tuning

Azure Storage Optimization

1. Use Premium Storage – For higher throughput requirements
2. Enable CDN – For geographically distributed users
3. Optimize Blob Size – Larger blobs have better throughput
4. Use Parallel Operations – Azure supports high concurrency

Built-in Retry Policy

The client implements exponential backoff for transient failures:

• Max Retries: 3 attempts
• Base Delay: 1 second
• Max Delay: 16 seconds
• Strategy: Exponential backoff

This configuration handles transient network issues and Azure throttling automatically.

File Caching

The implementation uses ETag-based caching:

1. Local Cache - Files are cached locally after download
2. ETag Validation - ETags are compared before re-downloading
3. Automatic Invalidation - Cache is updated when ETags don't match

Each node keeps up to 10,000 local copies in its temporary folder; a copy that has not been used for one hour is removed. The limit counts copies, not bytes, so with large documents plan the temporary storage of the node accordingly.

A copy that is being delivered stays readable until the delivery has finished, even if the cache removes it in the meantime; the file is deleted afterwards. A new version of a copy (after an update or a new download) replaces the file as a whole and never changes a file that is being read.

A download of a document that is overwritten continuously on another node is read again for up to 15 seconds. It returns a complete version that was loaded or confirmed after the read began, never a mixed one. Only if the document keeps changing for the whole 15 seconds, the read ends with FILE_STORAGE_RETRIEVE_CONTENT (-21001).

Before a cached copy is delivered, its ETag is compared with the blob in the container, so a document that another node has updated is delivered with its new content from that moment on.

In a cluster, deleting a document or a session removes its local copies on every node, not only on the node that processes the deletion: each node follows the deletion events with its own reader.

Environment variable	System property	Default	Description
WEBPDF_CLUSTER_EVENTS_LOCAL_CACHE_CLEANUP_ENABLED	-Dwebpdf.cluster.events.local.cache.cleanup.enabled	true	false switches the reader off; the local copies of deleted documents then remain until the cache removes them, at the latest after one hour without access.

Monitoring

Azure Monitor Integration

Monitor storage metrics:

• Requests – Success rate, latency
• Availability – Service availability percentage
• Capacity – Used storage capacity
• Egress/Ingress – Data transfer

Alerts

Configure Azure Monitor alerts for:

• High latency (>1000ms)
• Error rate >1%
• Capacity thresholds
• Unusual access patterns

Troubleshooting

Cannot Connect to Azure Storage

1. Verify storage account exists: az storage account show --name webpdfstorageacct
2. Check network connectivity to Azure
3. Verify account key or connection string
4. Check firewall rules in Storage Account settings

Common error messages:

• "Connection not possible" - Network connectivity issue or invalid endpoint
• "Authentication failed" - Invalid credentials or expired SAS token
• "No container name set" - Container name not configured
• "Unable to extract account name from URL" - Invalid URL format

Container Not Found

A missing container is reported by the health check (DOWN with the reason Container '<name>' does not exist at '<endpoint>') and by file operations, which fail without retries with error code -21003 or -21001 (see Missing Container at Runtime):

1. Verify container exists: az storage container list --account-name webpdfstorageacct
2. Check container name matches configuration (must be lowercase)
3. Verify access permissions
4. If the container was deleted while the server was running, create it again; a missing container is created automatically only at startup

Note: In cluster environments, if you see HTTP 409 errors during startup, this is normal and indicates another node is creating the container simultaneously.

Authentication Errors

Different authentication types have different troubleshooting steps:

Shared Key:

1. Verify account name is correct
2. Check account key hasn't been rotated
3. Validate URL format matches expected pattern

SAS Token:

1. Validate token hasn't expired
2. Check token permissions include required operations (r, w, d and l on the container)
3. Ensure token is properly formatted (starts with ?)

Connection String:

1. Verify complete connection string format
2. Check all required parameters are present
3. Validate endpoint suffix matches Azure region

Default Azure Credential:

1. Verify Managed Identity is assigned to resource
2. Check environment variables are set correctly
3. Ensure Azure CLI is authenticated (for development)
4. Review Azure Identity authentication chain order

Slow Upload/Download

1. Check network bandwidth to Azure
2. Review Azure Storage metrics
3. Consider Premium Storage tier
4. Enable Azure CDN for downloads
5. Check if geo-replication is causing latency

Examples

Basic Azure Blob Setup (Shared Key)

{
  "url": "https://webpdfstorageacct.blob.core.windows.net",
  "password": "AccountKey123...==",
  "containerName": "webpdf-files",
  "authenticationType": "SHARED_KEY"
}

With Connection String

{
  "password": "DefaultEndpointsProtocol=https;AccountName=webpdfstorageacct;AccountKey=...==;EndpointSuffix=core.windows.net",
  "containerName": "webpdf-prod-files",
  "authenticationType": "CONNECTION_STRING"
}

With Private Endpoint

{
  "url": "https://webpdfstorageacct.privatelink.blob.core.windows.net",
  "username": "webpdfstorageacct",
  "password": "AccountKey123...==",
  "containerName": "webpdf-files",
  "authenticationType": "SHARED_KEY"
}

With Managed Identity (Production Recommended)

{
  "url": "https://webpdfstorageacct.blob.core.windows.net",
  "containerName": "webpdf-prod-files",
  "authenticationType": "DEFAULT_AZURE_CREDENTIAL"
}

Note: Requires Azure Managed Identity to be assigned to the VM/App Service with appropriate Storage Blob Data permissions.

Azurite (Local Development)

{
  "url": "http://127.0.0.1:10000/devstoreaccount1",
  "password": "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==",
  "containerName": "webpdf-dev",
  "authenticationType": "SHARED_KEY"
}

Note: Uses Azurite emulator with default credentials for local development and testing. Start Azurite with --skipApiVersionCheck as long as it does not yet support the Azure Storage service version of the SDK bundled with webPDF. Otherwise Azurite rejects every request with InvalidHeaderValue ("The API version … is not supported by Azurite"), the storage health check reports DOWN and the server does not start.