Edit

Use kubelogin to authenticate users in Azure Kubernetes Service

  • Article

The kubelogin plugin in Azure is a client-go credential plugin that implements Microsoft Entra authentication. The kubelogin plugin offers features that aren't available in the kubectl command-line tool.

Azure Kubernetes Service (AKS) clusters that are integrated with Microsoft Entra ID and running Kubernetes version 1.24 or later automatically use the kubelogin format.

This article provides an overview and examples of how to use kubelogin for all supported Microsoft Entra authentication methods in AKS.

Limitations

  • You can include a maximum of 200 groups in a Microsoft Entra JSON Web Token (JWT) claim. If you have more than 200 groups, consider using application roles.
  • Groups that are created in Microsoft Entra ID are included only by their ObjectID value, and not by their display name. The sAMAccountName command is available only for groups that are synchronized from on-premises Windows Server Active Directory.
  • In AKS, the service principal authentication method works only with managed Microsoft Entra ID, and not with the earlier version Azure Active Directory.
  • The device code authentication method doesn't work when a Microsoft Entra Conditional Access policy is set on a Microsoft Entra tenant. In that scenario, use web browser interactive authentication.

How authentication works

For most interactions with kubelogin, you use the convert-kubeconfig subcommand. The subcommand uses the kubeconfig file that's specified in --kubeconfig or in the KUBECONFIG environment variable to convert the final kubeconfig file to exec format based on the specified authentication method.

The authentication methods that kubelogin implements are Microsoft Entra OAuth 2.0 token grant flows. The following parameter flags are common to use in kubelogin subcommands. In general, these flags are ready to use when you get the kubeconfig file from AKS.

  • --tenant-id: The Microsoft Entra tenant ID.
  • --client-id: The application ID of the public client application. This client app is used only in the device code, web browser interactive, and OAuth 2.0 Resource Owner Password Credentials (ROPC) (workflow identity) sign-in methods.
  • --server-id: The application ID of the web app or resource server. The token is issued to this resource.

Note

In each authentication method, the token is not cached on the file system.

Authentication methods

The next sections describe supported authentication methods and how to use them:

  • Device code
  • Azure CLI
  • Web browser interactive
  • Service principal
  • Managed identity
  • Workload identity

Device code

Device code is the default authentication method for the convert-kubeconfig subcommand. The -l devicecode parameter is optional. This authentication method prompts the device code for the user to sign in from a browser session.

Before the kubelogin and exec plugins were introduced, the Azure authentication method in kubectl supported only the device code flow. It used an earlier version of a library that produces a token that has the audience claim with an spn: prefix. It isn't compatible with AKS managed Microsoft Entra ID, which uses an on-behalf-of (OBO) flow. When you run the convert-kubeconfig subcommand, kubelogin removes the spn: prefix from the audience claim.

If your requirements include using functionality from earlier versions, add the --legacy argument. If you're using the kubeconfig file in an earlier version Azure Active Directory cluster, kubelogin automatically adds the --legacy flag.

In this sign-in method, the access token and the refresh token are cached in the ${HOME}/.kube/cache/kubelogin directory. To override this path, include the --token-cache-dir parameter.

If your AKS Microsoft Entra integrated cluster uses Kubernetes 1.24 or earlier, you must manually convert the kubeconfig file format by running the following commands:

export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig

Run this kubectl command to get node information:

kubectl get nodes

To clean up cached tokens, run the following command:

kubelogin remove-tokens

Note

The device code sign-in method doesn't work when a Conditional Access policy is configured on a Microsoft Entra tenant. In this scenario, use the web browser interactive method.

Azure CLI

The Azure CLI authentication method uses the signed-in context that the Azure CLI establishes to get the access token. The token is issued in the same Microsoft Entra tenant as az login. kubelogin doesn't write tokens to the token cache file because they are already managed by the Azure CLI.

Note

This authentication method works only with AKS managed Microsoft Entra ID.

The following example shows how to use the Azure CLI method to authenticate:

az login

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l azurecli

Run this kubectl command to get node information:

kubectl get nodes

If the Azure CLI config directory is outside the ${HOME} directory, use the --azure-config-dir parameter with the convert-kubeconfig subcommand. The command generates the kubeconfig file with the environment variable configured. You can get the same configuration by setting the AZURE_CONFIG_DIR environment variable to this directory when you run a kubectl command.

Web browser interactive

The web browser interactive method of authentication automatically opens a web browser to sign in the user. After the user is authenticated, the browser redirects to the local web server by using the verified credentials. This authentication method complies with Conditional Access policy.

When you authenticate by using this method, the access token is cached in the ${HOME}/.kube/cache/kubelogin directory. You can override this path by using the --token-cache-dir parameter.

Bearer token

The following example shows how to use a bearer token with the web browser interactive flow:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l interactive

Run this kubectl command to get node information:

kubectl get nodes

Proof-of-Possession token

The following example shows how to use a Proof-of-Possession (PoP) token with the web browser interactive flow:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l interactive --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"

Run this kubectl command to get node information:

kubectl get nodes

Service principal

This authentication method uses a service principal to sign in the user. You can provide the credential by setting an environment variable or by using the credential in a command-line argument. The supported credentials that you can use are a password or a Personal Information Exchange (PFX) client certificate.

Before you use this method, consider the following limitations:

  • This method works only with managed Microsoft Entra ID.
  • The service principal can be a member of a maximum of 200 Microsoft Entra groups.

Environment variables

The following example shows how to set up a client secret by using environment variables:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<Service Principal Name (SPN) client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_SECRET=<SPN secret>

Run this kubectl command to get node information:

kubectl get nodes

Then run this command:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AZURE_CLIENT_ID=<SPN client ID>
export AZURE_CLIENT_SECRET=<SPN secret>

Run this kubectl command to get node information:

kubectl get nodes

Command-line argument

The following example shows how to set up a client secret in a command-line argument:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn --client-id <SPN client ID> --client-secret <SPN client secret>

Run this kubectl command to get node information:

kubectl get nodes

Warning

The command-line argument method stores the secret in the kubeconfig file.

Client certificate

The following example shows how to set up a client secret by using a client certificate:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<SPN client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE=/path/to/cert.pfx
export AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE_PASSWORD=<PFX password>

Run this kubectl command to get node information:

kubectl get nodes

Then run this command:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AZURE_CLIENT_ID=<SPN client ID>
export AZURE_CLIENT_CERTIFICATE_PATH=/path/to/cert.pfx
export AZURE_CLIENT_CERTIFICATE_PASSWORD=<PFX password>

Run this kubectl command to get node information:

kubectl get nodes

PoP token and environment variables

The following example shows how to set up a PoP token that uses a client secret that it gets from environment variables:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<SPN client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_SECRET=<SPN secret>

Run this kubectl command to get node information:

kubectl get nodes

Managed identity

Use the managed identity authentication method for applications that connect to resources that support Microsoft Entra authentication. Examples include accessing Azure resources like an Azure virtual machine, a virtual machine scale set, or Azure Cloud Shell.

Default managed identity

The following example shows how to use the default managed identity:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l msi

Run this kubectl command to get node information:

kubectl get nodes

Specific identity

The following example shows how to use a managed identity with a specific identity:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l msi --client-id <msi-client-id>

Run this kubectl command to get node information:

kubectl get nodes

Workload identity

The workload identity authentication method uses identity credentials that are federated with Microsoft Entra to authenticate access to AKS clusters. The method uses Microsoft Entra integrated authentication. It works by setting the following environment variables:

  • AZURE_CLIENT_ID: The Microsoft Entra application ID that is federated with the workload identity.
  • AZURE_TENANT_ID: The Microsoft Entra tenant ID.
  • AZURE_FEDERATED_TOKEN_FILE: The file that contains a signed assertion of the workload identity, like a Kubernetes projected service account (JWT) token.
  • AZURE_AUTHORITY_HOST: The base URL of a Microsoft Entra authority. For example, https://login.microsoftonline.com/.

You can use a workload identity to access Kubernetes clusters from CI/CD systems like GitHub or ArgoCD without storing service principal credentials in the external systems. To configure OpenID Connect (OIDC) federation from GitHub, see the OIDC federation example.

The following example shows how to use a workload identity:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l workloadidentity

Run this kubectl command to get node information:

kubectl get nodes

How to use kubelogin with AKS

AKS uses a pair of first-party Microsoft Entra applications. These application IDs are the same in all environments.

The AKS Microsoft Entra server application ID that the server side uses is 6dae42f8-4368-4678-94ff-3960e28e3630. The access token that accesses AKS clusters must be issued for this application. In most kubelogin authentication methods, you must use --server-id with kubelogin get-token.

The AKS Microsoft Entra client application ID that kubelogin uses to perform public client authentication on behalf of the user is 80faf920-1908-4b52-b5ef-a8e7bedfc67a. The client application ID is used in device code and web browser interactive authentication methods.

Related content