Use kubelogin to authenticate users in Azure Kubernetes Service (AKS)

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. For more information, see the kubelogin introduction and the kubectl introduction.

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

Kubelogin authentication in AKS limitations

  • Groups that are created in Microsoft Entra 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.
  • The service principal authentication method works only with managed Microsoft Entra, and not with the earlier version Azure Active Directory.
  • The service principal can be a member of a maximum of 200 Microsoft Entra groups. If you have more than 200 groups, consider using application roles.
  • 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 instead.
  • The Azure CLI authentication method works only with AKS managed Microsoft Entra.

How authentication works

Note

Keep in mind the following information about kubelogin authentication for AKS clusters integrated with Microsoft Entra:

  • Clusters running Kubernetes version 1.24 or later automatically use the kubelogin format.
  • Clusters running Kubernetes 1.24 or earlier require manual conversion. You can use the device code authentication method to convert the kubeconfig file to use the exec plugin format.

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. In each authentication method, the token isn't cached on the file system.

Device code authentication

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

Note

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, which uses an on-behalf-of (OBO) flow. When you run the convert-kubeconfig subcommand, kubelogin removes the spn: prefix from the audience claim.

Parameters for device code authentication

The following table outlines parameters that you can use with device code authentication:

Parameter Description
-l devicecode (optional) Specifies the kubelogin authentication method. This parameter is optional because device code is the default method.
--legacy Uses legacy behavior for earlier versions of Azure Active Directory clusters. If you're using the kubeconfig file in an earlier version Azure Active Directory cluster, kubelogin automatically adds the --legacy flag.
--token-cache-dir Overrides the default path of the token cache directory, which is ${HOME}/.kube/cache/kubelogin.

Azure CLI authentication

The Azure CLI (command: -l azurecli) 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 the Azure CLI already manages them.

Parameters for Azure CLI authentication

The following table outlines parameters that you can use with Azure CLI authentication:

Parameter Description
-l azurecli Specifies the kubelogin authentication method.
--azure-config-dir Specifies the Azure CLI configuration directory. The default directory is ${HOME}/.azure.

Sign in to Azure

Sign in to Azure using the az login command.

az login

Web browser interactive authentication

The web browser interactive (command: -l 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 using the verified credentials. This authentication method complies with Conditional Access policy.

You can use either a bearer token or a Proof-of-Possession (PoP) token with this authentication method.

Parameters for bearer token authentication

The following table outlines parameters that you can use with bearer token authentication:

Parameter Description
-l interactive Specifies the kubelogin authentication method.
--token-cache-dir Overrides the default path of the token cache directory, which is ${HOME}/.kube/cache/kubelogin.

Parameters for PoP token authentication

The following table outlines parameters that you can use with PoP token authentication:

Parameter Description
-l interactive Specifies the kubelogin authentication method.
--pop-enabled Enables PoP token authentication.
--pop-claims Specifies the PoP token claims in a key-value pair format. For example, u=/ARM/ID/OF/CLUSTER.

Service principal authentication

The service principal (command: -l spn) 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.

Parameters for service principal authentication

The following table outlines parameters that you can use with service principal authentication:

Parameter Description
-l spn Specifies the kubelogin authentication method.
--client-id The application ID (client-id) of the service principal.
--client-secret The client secret of the service principal.

Managed identity authentication

Use the managed identity (command: -l msi) authentication method for applications that connect to resources that support Microsoft Entra authentication. Examples include accessing Azure resources like an Azure virtual machine (VM), a virtual machine scale set, or Azure Cloud Shell.

You can use the default managed identity that's assigned to the resource or a specific user-assigned managed identity.

Parameters for managed identity authentication

The following table outlines parameters that you can use with managed identity authentication:

Parameter Description
-l msi Specifies the kubelogin authentication method.
--client-id The application ID (client-id) of the user-assigned managed identity. If you don't specify this parameter, the default managed identity is used.

Workload identity authentication

The workload identity (command: -l workloadidentity) 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:

Variable Description
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.partner.microsoftonline.cn/.

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.

Parameters for workload identity authentication

The following table outlines parameters that you can use with workload identity authentication:

Parameter Description
-l workloadidentity Specifies the kubelogin authentication method.

Export the kubeconfig file path

Before you run the convert-kubeconfig subcommand, export the kubeconfig file path to the KUBECONFIG environment variable. For example:

export KUBECONFIG=/path/to/kubeconfig

Convert the kubeconfig file

Run the convert-kubeconfig subcommand to convert the kubeconfig file to use the exec plugin for your chosen authentication method.

kubelogin convert-kubeconfig

kubelogin convert-kubeconfig -l azurecli

# Bearer token authentication
kubelogin convert-kubeconfig -l interactive

# Proof-of-Possession (PoP) token authentication
kubelogin convert-kubeconfig -l interactive --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"

  1. Run the convert-kubeconfig subcommand to convert the kubeconfig file to use the exec plugin.

    kubelogin convert-kubeconfig -l spn

  2. Set the environment variables for the client ID and client secret or client certificate. For example:

    export AZURE_CLIENT_ID=<service-principal-client-id>
export AZURE_CLIENT_SECRET=<service-principal-client-secret>

# Default managed identity authentication
kubelogin convert-kubeconfig -l msi

# Specific managed identity authentication
kubelogin convert-kubeconfig -l msi --client-id <managed-identity-client-id>

kubelogin convert-kubeconfig -l workloadidentity

Remove cached tokens

Remove cached tokens using the kubelogin remove-tokens command.

kubelogin remove-tokens

Get node information

Get node information using the kubectl get command.

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 (server-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 (client-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

  • Last updated on