Use Microsoft Entra Workload ID with Azure Kubernetes Service (AKS)

Workloads deployed on an Azure Kubernetes Services (AKS) cluster require Microsoft Entra application credentials or managed identities to access Microsoft Entra protected resources, such as Azure Key Vault and Microsoft Graph. Microsoft Entra Workload ID integrates with the capabilities native to Kubernetes to federate with external identity providers.

Microsoft Entra Workload ID uses Service Account Token Volume Projection (that is, a service account), to enable pods to use a Kubernetes identity. A Kubernetes token is issued and OIDC federation enables Kubernetes applications to access Azure resources securely with Microsoft Entra ID, based on annotated service accounts.

Microsoft Entra Workload ID works especially well with the Azure Identity client libraries or the Microsoft Authentication Library (MSAL) collection, together with application registration. Your workload can use any of these libraries to seamlessly authenticate and access Azure cloud resources.

This article helps you to understand Microsoft Entra Workload ID, and reviews the options available to plan your project strategy and potential migration from Microsoft Entra pod-managed identity.

Dependencies

• AKS supports Microsoft Entra Workload ID on version 1.22 and higher.
• The Azure CLI version 2.47.0 or later. Run az --version to find the version, and run az upgrade to upgrade the version. If you need to install or upgrade, see Install Azure CLI.

Azure Identity client libraries

In the Azure Identity client libraries, choose one of the following approaches:

• Use DefaultAzureCredential, which attempts to use the WorkloadIdentityCredential.
• Create a ChainedTokenCredential instance that includes WorkloadIdentityCredential.
• Use WorkloadIdentityCredential directly.

The following table provides the minimum package version required for each language ecosystem's client library.

In the following code samples, DefaultAzureCredential is used. This credential type uses the environment variables injected by the Azure Workload Identity mutating webhook to authenticate with Azure Key Vault.

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

string keyVaultUrl = Environment.GetEnvironmentVariable("KEYVAULT_URL");
string secretName = Environment.GetEnvironmentVariable("SECRET_NAME");

var client = new SecretClient(
    new Uri(keyVaultUrl),
    new DefaultAzureCredential());

KeyVaultSecret secret = await client.GetSecretAsync(secretName);

#include <cstdlib>
#include <azure/identity.hpp>
#include <azure/keyvault/secrets/secret_client.hpp>

using namespace Azure::Identity;
using namespace Azure::Security::KeyVault::Secrets;

int main()
{
  const char* keyVaultUrl = std::getenv("KEYVAULT_URL");
  const char* secretName = std::getenv("SECRET_NAME");
  auto credential = std::make_shared<DefaultAzureCredential>();

  SecretClient client(keyVaultUrl, credential);
  Secret secret = client.GetSecret(secretName).Value;

  return 0;
}

package main

import (
	"context"
	"os"

	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azsecrets"
    "k8s.io/klog/v2"
)

func main() {
	keyVaultUrl := os.Getenv("KEYVAULT_URL")
	secretName := os.Getenv("SECRET_NAME")

	credential, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		klog.Fatal(err)
	}

	client, err := azsecrets.NewClient(keyVaultUrl, credential, nil)
	if err != nil {
		klog.Fatal(err)
	}

	secret, err := client.GetSecret(context.Background(), secretName, "", nil)
	if err != nil {
		klog.ErrorS(err, "failed to get secret", "keyvault", keyVaultUrl, "secretName", secretName)
		os.Exit(1)
	}
}

import java.util.Map;

import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;
import com.azure.security.keyvault.secrets.models.KeyVaultSecret;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.identity.DefaultAzureCredential;

public class App {
    public static void main(String[] args) {
        Map<String, String> env = System.getenv();
        String keyVaultUrl = env.get("KEYVAULT_URL");
        String secretName = env.get("SECRET_NAME");

        SecretClient client = new SecretClientBuilder()
                .vaultUrl(keyVaultUrl)
                .credential(new DefaultAzureCredentialBuilder().build())
                .buildClient();
        KeyVaultSecret secret = client.getSecret(secretName);
    }
}

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const main = async () => {
    const keyVaultUrl = process.env["KEYVAULT_URL"];
    const secretName = process.env["SECRET_NAME"];

    const credential = new DefaultAzureCredential();
    const client = new SecretClient(keyVaultUrl, credential);

    const secret = await client.getSecret(secretName);
}

main().catch((error) => {
    console.error("An error occurred:", error);
    process.exit(1);
});

import os

from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential

def main():
    keyvault_url = os.getenv('KEYVAULT_URL', '')
    secret_name = os.getenv('SECRET_NAME', '')

    client = SecretClient(vault_url=keyvault_url, credential=DefaultAzureCredential())
    secret = client.get_secret(secret_name)

if __name__ == '__main__':
    main()

Azure Authentication Library (MSAL)

The following client libraries are the minimum version required.

Limitations

• You can have a maximum of 20 federated identity credentials per managed identity.
• It takes a few seconds for the federated identity credential to be propagated after being initially added.
• The virtual nodes add on, based on the open source project Virtual Kubelet, isn't supported.
• Creation of federated identity credentials is not supported on user-assigned managed identities in these regions.

How it works

In this security model, the AKS cluster acts as the token issuer. Microsoft Entra ID uses OpenID Connect to discover public signing keys and verify the authenticity of the service account token before exchanging it for a Microsoft Entra token. Your workload can exchange a service account token projected to its volume for a Microsoft Entra token using the Azure Identity client library or the Microsoft Authentication Library (MSAL).

The following table describes the required OIDC issuer endpoints for Microsoft Entra Workload ID:

The following diagram summarizes the authentication sequence using OpenID Connect.

Webhook Certificate Auto Rotation

Similar to other webhook addons, the certificate is rotated by cluster certificate auto rotation operation.

Service account labels and annotations

Microsoft Entra Workload ID supports the following mappings related to a service account:

• One-to-one, where a service account references a Microsoft Entra object.
• Many-to-one, where multiple service accounts reference the same Microsoft Entra object.
• One-to-many, where a service account references multiple Microsoft Entra objects by changing the client ID annotation. For more information, see How to federate multiple identities with a Kubernetes service account.

If you've used Microsoft Entra pod-managed identity, think of a service account as an Azure security principal, except that a service account is part of the core Kubernetes API, rather than a Custom Resource Definition (CRD). The following sections describe a list of available labels and annotations that can be used to configure the behavior when exchanging the service account token for a Microsoft Entra access token.

Service account annotations

All annotations are optional. If the annotation isn't specified, the default value will be used.

Pod labels

Pod annotations

All annotations are optional. If the annotation isn't specified, the default value will be used.

¹ Takes precedence if the service account is also annotated.

How to migrate to Entra Workload ID

On a cluster that is already running a pod-managed identity, you can configure it to use workload identity one of two ways. The first option allows you to use the same configuration that you've implemented for pod-managed identity. You can annotate the service account within the namespace with the identity to enable Entra Workload ID and inject the annotations into the pods.

The second option is to rewrite your application to use the latest version of the Azure Identity client library.

To help streamline and ease the migration process, we've developed a migration sidecar that converts the IMDS transactions your application makes over to OpenID Connect (OIDC). The migration sidecar isn't intended to be a long-term solution, but a way to get up and running quickly on workload identity. Running the migration sidecar within your application proxies the application IMDS transactions over to OIDC. The alternative approach is to upgrade to a supported version of the Azure Identity client library, which supports OIDC authentication.

The following table summarizes our migration or deployment recommendations for workload identity.

Next steps

• To learn how to set up your pod to authenticate using a workload identity as a migration option, see Modernize application authentication with workload identity.
• See Deploy and configure an AKS cluster with workload identity, which helps you deploy an Azure Kubernetes Service cluster and configure a sample application to use a workload identity.