1

Azure Blob Storage Authentication

Chris Lu edited this page 2026-07-27 14:24:19 -07:00

Table of Contents

• Storage account key
• Entra ID
• Workload identity on Kubernetes
• Managed identity on a VM
• Troubleshooting
• Limitations

SeaweedFS reaches Azure Blob Storage from two places, and both authenticate the same way:

• the backup sink, [sink.azure] in replication.toml, used by weed filer.backup — see Async Backup
• remote storage, remote.configure -type=azure — see Configure Remote Storage

There are two ways to authenticate: a storage account key, or Entra ID.

Storage account key

The original method. Give the account name and one of its access keys:

[sink.azure]
enabled = true
account_name = "myaccount"
account_key = "base64key=="
container = "mycontainer"
directory = "/"

> remote.configure -name=cloud3 -type=azure -azure.account_name=myaccount -azure.account_key=base64key==

Remote storage also reads AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_ACCESS_KEY from the environment when the configuration leaves them out. The sink does not; it only reads replication.toml.

Account keys are account-wide and grant full control, so they have to be distributed to every process that backs up, and rotated everywhere at once. Entra ID avoids that.

Entra ID

Leave account_key empty and SeaweedFS authenticates through the Azure identity chain instead, granting access by RBAC role rather than by key. The chain tries, in order: credentials in the environment, a workload identity, a managed identity, then a developer login such as az login.

[sink.azure]
enabled = true
account_name = "myaccount"
account_key = ""
container = "mycontainer"
directory = "/"

> remote.configure -name=cloud3 -type=azure -azure.account_name=myaccount

The identity needs a data-plane role on the container or the account. Storage Blob Data Contributor covers the backup sink and read-write remote storage; Storage Blob Data Reader is enough for a read-only mount. Owner and Contributor are control-plane roles and do not by themselves grant access to blob data.

Workload identity on Kubernetes

This is the usual setup for a fleet: no secret is mounted anywhere, and nothing has to be rotated. Label the pod for the Azure workload identity webhook and the webhook projects AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_AUTHORITY_HOST and a federated token file into the container. SeaweedFS picks them up on its own, so account_name stays the only Azure setting.

spec:
  serviceAccountName: seaweedfs
  template:
    metadata:
      labels:
        azure.workload.identity/use: "true"

The service account carries the identity:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: seaweedfs
  annotations:
    azure.workload.identity/client-id: 11111111-1111-1111-1111-111111111111

The federated credential on the Entra application has to trust that service account, and the managed identity needs the storage role above. This works the same on Azure Arc-enabled clusters as it does on AKS.

Managed identity on a VM

On a VM or a VM scale set with a system-assigned identity, an empty account_key is again all that is needed. When the host carries more than one user-assigned identity, name the one to use:

account_key = ""
client_id = "11111111-1111-1111-1111-111111111111"

> remote.configure -name=cloud3 -type=azure -azure.account_name=myaccount -azure.client_id=11111111-1111-1111-1111-111111111111

client_id also pins the identity for workload identity, where it overrides the client id the webhook projected. Setting it tells remote storage that Entra ID is intended, so AZURE_STORAGE_ACCESS_KEY in the environment is then ignored rather than quietly taking the request back to shared key auth.

Troubleshooting

A missing role shows up as AuthorizationPermissionMismatch or 403 on the first blob operation, not at startup. Check that the role is assigned to the identity that actually authenticated, and that it is a Storage Blob Data role.

no tenant ID specified or no client ID specified means workload identity was selected but the environment is incomplete — usually the pod is missing the azure.workload.identity/use label, so the webhook never projected anything.

ManagedIdentityCredential authentication failed on a host with no managed identity means the chain reached the end without finding one. Either assign an identity to the host, or go back to an account key.

Entra ID logs a line when it is selected. The glog flags are global, so they go before the subcommand: weed -v=1 filer.backup.

Limitations

The blob service url is https://<account_name>.blob.core.windows.net/, so Azure Government, Azure China and private endpoints are not reachable yet.

Introduction

• Quick Start with weed mini
• Simplest S3 Bucket and User Setup
• Components
• Blob Store Architecture
• Getting Started
• Production Setup
• A typical step‐by‐step example
• Benchmarks
• FAQ
• Applications

API

• Master Server API
• Volume Server API
• Filer Server API
• Client Libraries
• SeaweedFS Java Client

Configuration

• Replication
• Store file with a Time To Live
• Failover Master Server
• Erasure coding for warm storage
• EC Bitrot Detection
• Server Startup via Systemd
• Environment Variables

Filer

• Filer Setup
• Directories and Files
• File Operations Quick Reference
• Data Structure for Large Files
• Filer Data Encryption
• Filer Commands and Operations
• Filer JWT Use
• TUS Resumable Uploads

Filer Stores

• Filer Cassandra Setup
• Filer Redis Setup
• Super Large Directories
• Path-Specific Filer Store
• Choosing a Filer Store
• Customize Filer Store

Management

• Admin UI
• Admin UI OIDC
• Worker
• Plugin Worker Scheduling

Advanced Filer Configurations

• Migrate to Filer Store
• Add New Filer Store
• Filer Store Replication
• Filer Active Active cross cluster continuous synchronization
• Filer as a Key-Large-Value Store
• Path Specific Configuration
• Filer Change Data Capture
• Filer Operation Serialization

FUSE Mount

• Mount on Windows
• FIO benchmark
• fstab and systemd mount
• POSIX Compliance
• Distributed POSIX Locks
• P2P reading in weed mount
• Mount over the Internet

WebDAV

SFTP Server

Cloud Drive

• Cloud Drive Benefits
• Cloud Drive Architecture
• Configure Remote Storage
• Azure Blob Storage Authentication
• Mount Remote Storage
• Cache Remote Storage
• Cloud Drive Quick Setup
• Gateway to Remote Object Storage

AWS S3 API

• Amazon S3 API
• Supported APIs vs Minio
• S3 Lifecycle
  • S3 Lifecycle Recipes
  • S3 Lifecycle Operator Guide
  • S3 Lifecycle Monitoring
  • S3 Lifecycle Troubleshooting
  • S3 Lifecycle Architecture
• S3 Lifecycle vs Volume TTL
• S3 Conditional Operations
• S3 CORS
• S3 Object Lock and Retention
• S3 Object Versioning
• S3 RenameObject
• S3 API Benchmark
• S3 API FAQ
• S3 Bucket Quota
• S3 Rate Limiting
• S3 API Audit log
• S3 Nginx Proxy
• Docker Compose for S3

S3 Table Bucket

• S3 Table Bucket
• S3 Table Bucket Commands
• S3 Tables Security
• SeaweedFS Iceberg Catalog
• Iceberg REST Catalog API
• Iceberg Table Maintenance
• SeaweedFS Lance Catalog
• Lance Maintenance Worker

Iceberg Integrations

• Spark Iceberg Integration
• Trino Iceberg Integration
• Dremio Iceberg Integration
• DuckDB Iceberg Integration
• Doris Iceberg Integration
• RisingWave Iceberg Integration
• Lakekeeper Iceberg Integration

Lance Integrations

• LanceDB Integration
• Spark Lance Integration
• DuckDB Lance Integration

S3 Authentication & IAM

• S3 Configuration - Start Here
• S3 Credentials (-s3.config)
• OIDC Integration (-s3.iam.config)
• Kubernetes ServiceAccount Authentication (IRSA-style)
• S3 Policy Variables
• S3 Policy Conditions
• S3 Bucket Policies
• Amazon IAM API
• AWS IAM CLI
• weed shell - Shell IAM Commands

Server-Side Encryption

• Server-Side Encryption
• Server-Side Encryption SSE-KMS
• Server-Side Encryption SSE-C

S3 Client Tools

• AWS CLI with SeaweedFS
• s3cmd with SeaweedFS
• rclone with SeaweedFS
• restic with SeaweedFS
• nodejs with Seaweed S3

Machine Learning

• TensorFlow with SeaweedFS
• Distributing AI Model Files for Multi-GPU Loading

HDFS

• Hadoop Compatible File System
• run Spark on SeaweedFS
• run HBase on SeaweedFS
• Run Trino on SeaweedFS
• Hadoop Benchmark
• HDFS via S3 connector

Replication and Backup

• Async Replication to another Filer [Deprecated]
• Async Backup
• Async Filer Metadata Backup
• Async Replication to Cloud [Deprecated]
• Kubernetes Backups and Recovery with K8up

Metadata Change Events

• Filer Metadata Events
• Filer Notification Webhook

Messaging

• Structured Data Lake with SMQ and SQL
• Seaweed Message Queue
• SQL Queries on Message Queue
• SQL Quick Reference
• PostgreSQL-compatible Server weed db
• Pub-Sub to SMQ to SQL
• Kafka to Kafka Gateway to SMQ to SQL

Use Cases

• Use Cases
• Actual Users

Operations

• System Metrics
• weed shell
• Data Backup
• Deployment to Kubernetes and Minikube
• Helm Chart Recipes
• Deployment with seaweed-up
  • seaweed-up Command Reference
  • Cluster Plan Workflow
  • Cluster Plan Inventory Reference
  • Cluster Plan Day 2 Operations

Rust Volume Server

• Rust Volume Server

Advanced

• Large File Handling
• Optimization
• Optimization for Many Small Buckets
• Volume Management
• Tiered Storage
• Cloud Tier
• Cloud Monitoring
• Load Command Line Options from a file
• SRV Service Discovery
• Volume Files Structure

Security

• Security Overview
• Security Configuration
• Cryptography and FIPS Compliance
• Run Blob Storage on Public Internet

Misc Use Case Examples

• UrBackup with SeaweedFS
• Docker Image Registry with SeaweedFS
• SeaweedFS in Docker Swarm
• Words from SeaweedFS Users
• Independent Benchmarks
• Hardware