Azure Files CSI driver adds workload identity for AKS SMB mounts

What actually changed today?

The Azure Files CSI driver in AKS can now authenticate to SMB shares using workload identity, and it’s GA. Before this, SMB mounts had two options: a cluster-wide managed identity, or — let’s be honest about what most teams did — the storage account key stuffed into a Kubernetes Secret. Now a pod can present its own federated Entra identity to Azure Files and mount the share as itself.

NFS mounts already had this. SMB was the holdout. That gap is closed.

Workload identity vs managed identity — what’s the difference, in plain terms?

Think of a managed identity as the building’s master key. Every pod on the node can borrow it, so the blast radius is “the whole cluster.” A workload identity is more like a personal badge the front desk issues after checking your ID against a list of people allowed in that specific room.

Mechanically: your AKS cluster runs an OIDC issuer. Each pod’s Kubernetes ServiceAccount gets a short-lived signed token. Entra trusts that issuer through a federated identity credential — a rule that says “a token from this cluster, for this namespace and this service account, may act as this managed identity.” No secret is stored in the cluster. Nothing to rotate, nothing to leak in a kubectl get secret.

Why does this matter more on a multi-tenant cluster?

Because “the whole cluster can read the share” stops being acceptable the moment two teams share nodes. With a node-level managed identity, tenant A’s compromised pod can reach tenant B’s file share if the identity was granted access. Workload identity scopes access per ServiceAccount, so team A’s badge simply doesn’t open team B’s room. Least privilege that actually holds up to a threat model, not a slide.

What do I need before I start?

• OIDC issuer and workload identity enabled on the cluster.
• A user-assigned managed identity for the workload, granted access to the storage account (RBAC or share-level).
• A recent AKS version and Azure Files CSI driver — check az aks show for the driver and confirm your fleet is current rather than trusting a version number I could get wrong.

How do I turn it on for an existing cluster?

1
2
3
4
5
6
7
8
9
10

# Enable OIDC + workload identity (idempotent on an existing cluster)
az aks update \
  --name my-aks --resource-group my-rg \
  --enable-oidc-issuer --enable-workload-identity
​
OIDC=$(az aks show -n my-aks -g my-rg \
  --query oidcIssuerProfile.issuerUrl -o tsv)
​
az identity create -n files-wi -g my-rg
CLIENT_ID=$(az identity show -n files-wi -g my-rg --query clientId -o tsv)

Federate the identity to the exact ServiceAccount that will mount the share:

1
2
3
4
5

az identity federated-credential create \
  --name files-fed --identity-name files-wi -g my-rg \
  --issuer "$OIDC" \
  --subject "system:serviceaccount:team-a:files-sa" \
  --audience api://AzureADTokenExchange

Then point the StorageClass at workload identity instead of a key. Note the client ID lives on the class, not in a secret:

1
2
3
4
5
6
7
8
9
10
11
12

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: azurefile-smb-wi
provisioner: file.csi.azure.com
parameters:
  protocol: smb
  clientID: "REPLACE_WITH_CLIENT_ID"
  resourceGroup: my-rg
  storageAccount: myfilesacct
reclaimPolicy: Retain
volumeBindingMode: Immediate

The pod just needs the ServiceAccount and the azure.workload.identity/use: "true" label. The CSI driver does the token exchange at mount time.

So this is a pure win, right?

No — it’s a better trade, not a free one. You’ve swapped one secret for a graph of RBAC: a managed identity per workload, a federated credential per ServiceAccount, and storage-account role assignments to keep tidy. Get the subject string wrong by a namespace and the mount fails with an auth error that tells you almost nothing. Budget for that operationally, and codify the identity plumbing in Bicep or Terraform so nobody hand-crafts subjects in the portal at 2am.

But the thing you delete is the thing that gets you breached. A federated token can’t be copied out of an incident. A storage account key already has been, somewhere, in some cluster you inherited. Trade made.

What should I do this week?

Grep your StorageClasses and Secrets for azurestorageaccountkey. Every hit is a pod holding the master key. Pick the noisiest multi-tenant cluster, migrate one namespace to a federated identity, and confirm the mount survives a pod restart. Then start revoking keys — that’s the part that actually moves your risk.