Workload ID: config best practices

Setting up Workload ID involves configuration in both Azure and Kubernetes. Here are the six steps. 

First, check if the OIDC issuer feature is already enabled on your AKS cluster. This is a prerequisite, so don't skip it! 

There are two options: either during the creation of your cluster (with --enable-oidc-issuer) or afterwards via an update command: 

az aks update --resource-group <your-resource-group> --name <your-aks-cluster-name> --enable-oidc-issuer 

Next, retrieve your cluster's unique OIDC issuer URL. You'll need this in step 3. 

az aks show --resource-group <your-resource-group> --name <your-aks-cluster-name> --query "oidcIssuerProfile.issuerUrl" -o tsv 

Create a User-Assigned Managed Identity (UAMI) in Azure. This can be done in three possible ways: 

Be sure to also note the Client ID (also called Application ID) and Tenant ID of this new Managed Identity. 

P.S. As we mentioned in the first blog post, you can also opt for App Registration, but we generally recommend using a User Assigned Managed Identity. 

Once the federated credential is set up, we need to create a Service Account in our Kubernetes configuration (YAML file). 

Specifically, we need to add the azure.workload.identity/client-id annotation to the metadata, using the Client ID of the User-Assigned Managed Identity created in step 2. This links the Kubernetes Service Account to the Azure identity. 

apiVersion: v1 

kind: ServiceAccount 

metadata: 

  name: <your-service-account-name> # Must match step 3 

  namespace: <your-namespace> # Must match step 3 

  annotations: 

    azure.workload.identity/client-id: "<client-id-of-managed-identity>" 

    # Optional: azure.workload.identity/tenant-id: "<your-tenant-id>" 

In this step, you'll establish a trust relationship that makes everything work. Here's how: 

In the YAML file of your deployment or pod, two more things need to be configured. First, reference the Service Account created in the previous step via spec.serviceAccountName: <your-service-account-name>. 

Second, add the azure.workload.identity/use: "true" label to spec.template.metadata.labels (for a deployment) or metadata.labels (for a pod). This label activates the Workload ID webhook for this pod. 

apiVersion: apps/v1 

kind: Deployment 

metadata: 

  name: my-application 

  namespace: <your-namespace> 

spec: 

  # ... replicas, selector ... 

  template: 

    metadata: 

      labels: 

        # ... other labels ... 

        azure.workload.identity/use: "true" # <-- ESSENTIAL LABEL 

    spec: 

      serviceAccountName: <your-service-account-name> # <-- Link to SA 

      containers: 

      # ... container definition ... 

Last but not least, you still need to assign the necessary permissions in Azure. Grant the User-Assigned Managed Identity from step 2 the appropriate Azure RBAC roles on the resources your application needs to access. For example, you might choose 'Key Vault Secrets User', 'Storage Blob Data Reader', or another role you've configured. 

Here's a best practice to keep in mind: assign these roles to the specific resources your application uses, not just at the subscription level. 

The good news is that your application code often won't need any modifications to work with Workload ID. If you're using recent versions of the Azure Identity SDKs, they'll automatically detect that they're running within an AKS pod with a Workload ID configuration. They find the injected token and use it for authentication. 

Workload ID makes authentication much easier than older methods, but (as with any technology) there are a few points to pay extra attention to during implementation. 

Correctly setting the azure.workload.identity/client-id annotation on the Service Account and the azure.workload.identity/use: "true" label on the Pod template is absolutely crucial. If you forget these or configure them incorrectly, the token exchange simply won't work. So, always double-check these settings! 

If you modify the annotations on an existing Service Account (for instance, to link to a different Managed Identity), the pods using that Service Account will need to be restarted. Only then will they pick up the new configuration and be able to obtain the correct Entra ID tokens. 

Always follow the least privilege principle: give a workload only the permissions that are strictly necessary. Ideally, have a separate User-Assigned Managed Identity (with its associated Federated Credential and Service Account) for each application or component that requires unique permissions. This ensures a clear separation and minimizes the potential impact if an identity is ever compromised. 

Only bundle workloads under the same Managed Identity (a so-called many-to-one configuration) if they share the exact same set of Azure permissions. For example, consider multiple monitoring components that all need identical access to a Storage Account. 

The limit of a maximum of 20 federated credentials per User-Assigned Managed Identity encourages this granular approach. It almost forces you to consider splitting identities by workload or functional domain, which ultimately improves security. 

Workload ID is widely available in almost all Azure regions, including West Europe and North Europe. To be certain, check the official Microsoft documentation for the most up-to-date (and very short) list of exceptions, but it's unlikely you'll be restricted by this. 

As you've seen, configuring Workload ID requires attention to detail in both Azure and Kubernetes. But once it's in place, you'll reap the benefits of a significantly more secure, simpler, and modern way of authenticating. No more secret-related stress, better control, and a setup that fits perfectly into your GitOps workflow. 

So, as far as we're concerned, Workload ID is the definitive way to set up secure communication between AKS and Azure. That's why we've made it part of our AKS Baseline!