Mutating Admission Webhook

Azure AD Workload Identity uses a mutating admission webhook to project a signed service account token to your workload’s volume and inject the following properties to pods with a service account that is configured to use the webhook:

Environment variableDescription
AZURE_AUTHORITY_HOSTThe Azure Active Directory (AAD) endpoint.
AZURE_CLIENT_IDThe application/client ID of the Azure AD application or user-assigned managed identity.
AZURE_TENANT_IDThe tenant ID of the Azure subscription.
AZURE_FEDERATED_TOKEN_FILEThe path of the projected service account token file.
azure-identity-tokenThe projected service account volume.
Volume mountDescription
/var/run/secrets/azure/tokens/azure-identity-tokenThe path of the projected service account token file.

The webhook allows pods to use a service account token projected to a well-known volume path to exchange for an Azure AD access token by leveraging the above properties with the Azure Identity SDKs or the Microsoft Authentication Library (MSAL).


Obtain your Azure tenant ID by running the following command:

export AZURE_TENANT_ID="$(az account show -s <AzureSubscriptionID> --query tenantId -otsv)"

The tenant ID above will be the default tenant ID that the webhook uses when configuring the AZURE_TENANT_ID environment variable in the pod. In the case of a multi-tenant cluster, you can override the tenant ID by adding the azure.workload.identity/tenant-id annotation to your service account.

You can install the mutating admission webhook with one of the following methods:

helm repo add azure-workload-identity
helm repo update
helm install workload-identity-webhook azure-workload-identity/workload-identity-webhook \
   --namespace azure-workload-identity-system \
   --create-namespace \
   --set azureTenantID="${AZURE_TENANT_ID}"
namespace/azure-workload-identity-system created
NAME: workload-identity-webhook
LAST DEPLOYED: Wed Aug  4 10:49:20 2021
NAMESPACE: azure-workload-identity-system
STATUS: deployed

Deployment YAML

Install envsubst

The deployment YAML contains the environment variables we defined above and we rely on the envsubst binary to substitute them for their respective values before deploying. See the envsubst‘s installation guide on how to install it.

Install the webhook using the deployment YAML via kubectl apply -f and envsubst:

curl -sL | envsubst | kubectl apply -f -
namespace/azure-workload-identity-system created
serviceaccount/azure-wi-webhook-admin created created created created created
configmap/azure-wi-webhook-config created
secret/azure-wi-webhook-server-cert created
service/azure-wi-webhook-webhook-service created
deployment.apps/azure-wi-webhook-controller-manager created created