Introduction

kubelogin is a client-go credential (exec) plugin implementing azure authentication. This plugin provides features that are not available in kubectl. It is supported on kubectl v1.11+

Features

• interactive device code login
• interactive web browser login
• non-interactive service principal login
• non-interactive user principal login using Resource owner login flow
• non-interactive managed service identity login
• non-interactive Azure CLI token login (AKS only)
• non-interactive Azure Developer CLI token login (AKS only)
• non-interactive workload identity login

Installation

Download from Release

Copy the latest Releases to shell’s search path.

Homebrew

# install
brew install Azure/kubelogin/kubelogin

# upgrade
brew update
brew upgrade Azure/kubelogin/kubelogin

Linux

Using asdf

asdf and the asdf-kubelogin plugin are not maintained by Microsoft.

# install
asdf plugin add kubelogin
asdf install kubelogin latest
asdf global kubelogin latest

# upgrade
asdf update
asdf plugin update kubelogin
asdf install kubelogin latest
asdf global kubelogin latest

Using azure cli

There is another option to install Kubectl and Kubectl login. Documentation on this is here: https://learn.microsoft.com/en-us/cli/azure/aks?view=azure-cli-latest#az-aks-install-cli()

# install (May require using the command ‘sudo’)
az aks install-cli

Windows

Using winget

From Powershell:

winget install --id=Kubernetes.kubectl  -e
winget install --id=Microsoft.Azure.Kubelogin  -e

Using scoop

This package is not maintained by Microsoft.

From Powershell:

scoop install kubectl azure-kubelogin

Using chocolatey

This package is not maintained by Microsoft.

From Powershell:

choco install kubernetes-cli azure-kubelogin

Using azure cli

From Powershell:

az aks install-cli
$targetDir="$env:USERPROFILE\.azure-kubelogin"
$oldPath = [System.Environment]::GetEnvironmentVariable("Path","User")
$oldPathArray=($oldPath) -split ";"
if(-Not($oldPathArray -Contains "$targetDir")) {
    write-host "Permanently adding $targetDir to User Path"
    $newPath = "$oldPath;$targetDir" -replace ";+", ";"
    [System.Environment]::SetEnvironmentVariable("Path",$newPath,"User")
    $env:Path = [System.Environment]::GetEnvironmentVariable("Path","User"),[System.Environment]::GetEnvironmentVariable("Path","Machine") -join ";"
}

Quick Start

After kubelogin is installed, do the following on Azure AD enabled AKS clusters

Using Azure CLI login mode

az login

# by default, this command merges the kubeconfig into ${HOME}/.kube/config
az aks get-credentials -g ${RESOURCE_GROUP_NAME} -n ${AKS_NAME}


# kubelogin by default will use the kubeconfig from ${KUBECONFIG}. Specify --kubeconfig to override
# this converts to use azurecli login mode
kubelogin convert-kubeconfig -l azurecli

# voila!
kubectl get nodes

Concepts

This section documents the key concepts that will be used throughout the kubelogin command-line.

Exec Plugin

Exec plugin is one of Kubernetes authentication strategies which allows kubectl to execute an external command to receive user credentials to send to api-server. Since Kubernetes 1.26, the default azure auth plugin is removed from client-go and kubectl.

To interact with an Azure AD enabled Kubernetes cluster, Exec plugin using kubelogin will be required.

A kubeconfig using exec plugin will look somewhat like:

kind: Config
preferences: {}
users:
  - name: user-name
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        command: kubelogin
        args:
          - get-token
          - --environment
          - AzurePublicCloud
          - --server-id
          - <AAD server app ID>
          - --client-id
          - <AAD client app ID>
          - --tenant-id
          - <AAD tenant ID>

When using kubelogin in Exec plugin, the kubeconfig tells kubectl to execute kubelogin get-token subcommand to perform various Azure AD login modes to get the access token.

Login Modes

Most of the interaction with kubelogin is around convert-kubeconfig subcommand which uses the input kubeconfig specified in --kubeconfig or KUBECONFIG environment variable to convert to the final kubeconfig in exec format based on specified login mode.

In this section, the login modes will be explained in details.

How Login Works

The login modes that kubelogin implements are AAD OAuth 2.0 token grant flows. Throughout kubelogin subcommands, you will see below common flags. In general, these flags are already setup when you get the kubeconfig from AKS.

• --tenant-id: Azure AD tenant ID
• --client-id: the application ID of the public client application. This client app is only used in device code, web browser interactive, and ropc login modes.
• --server-id: the application ID of the web app, or resource server. The token should be issued to this resource.

References

• https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/auth-oauth2
• https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow
• https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow
• https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth-ropc
• https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc

Device Code

This is the default login mode in convert-kubeconfig subcommand. So -l devicecode is optional. This login will prompt the device code for user to login on a browser.

Before kubelogin and Exec plugin were introduced, the azure authentication mode in kubectl supports device code flow only. It uses an old library that produces the token with audience claim that has spn: prefix which is not compatible with AKS Managed AAD using On-Behalf-Of mode (Issue86410). So when running convert-kubeconfig subcommand, kubelogin will remove the spn: prefix in audience claim. If it’s desired to keep the old behavior, add --legacy.

If you are using kubeconfig from AKS Legacy AAD (AADv1) clusters, kubelogin will automatically add --legacy flag.

In this login mode, the access token and refresh token will be cached at ${HOME}/.kube/cache/kubelogin directory. This path can be overriden by --token-cache-dir.

Usage Examples

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig

kubectl get nodes

# clean up cached token
kubelogin remove-tokens

Restrictions

• Device code login mode doesn’t work when Conditional Access policy is configured on AAD tenant. Use web browser interactive mode instead.

References

• https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-device-code

Azure CLI

This login mode uses the already logged-in context performed by Azure CLI to get the access token. The token will be issued in the same Azure AD tenant as in az login.

kubelogin will not cache any token since it’s already managed by Azure CLI.

NOTE

This login mode only works with managed AAD in AKS.

Usage Examples

az login

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l azurecli

kubectl get nodes

When Azure CLI’s config directory is outside the ${HOME} directory, --azure-config-dir should be specified in convert-kubeconfig subcommand. It will generate the kubeconfig with environment variable configured. The same thing can also be achieved by setting environment variable AZURE_CONFIG_DIR to this directory while running kubectl command.

References

• https://learn.microsoft.com/en-us/cli/azure/
• https://github.com/Azure/azure-cli

Azure Developer CLI (azd)

This login mode uses the already logged-in context performed by Azure Developer CLI to get the access token. The token will be issued in the same Azure AD tenant as in azd auth login.

kubelogin will not cache any token since it’s already managed by Azure Developer CLI.

NOTE

This login mode only works with managed AAD in AKS.

Usage Examples

azd auth login

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l azd

kubectl get nodes

References

• https://learn.microsoft.com/azure/developer/azure-developer-cli/overview
• https://github.com/azure/azure-dev

Web Browser Interactive

This login mode will automatically open a browser to login the user. Once authenticated, the browser will redirect back to a local web server with the credentials. This login mode complies with Conditional Access policy.

In this login mode, the access token will be cached at ${HOME}/.kube/cache/kubelogin directory. This path can be overriden by --token-cache-dir.

Usage Examples

Bearer token with interactive flow

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l interactive

kubectl get nodes

Proof-of-possession (PoP) token with interactive flow

export KUBECONFIG=/path/to/kubeconfig

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

kubectl get nodes

References

• https://learn.microsoft.com/en-us/python/api/azure-identity/azure.identity.interactivebrowsercredential?view=azure-python

Service Principal

This login mode uses the service principal to login. The credential may be provided via environment variables or flag. The supported credentials are password and pfx client certificate.

The token will not be cached on the filesystem.

Usage Examples

Client secret in environment variable

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<spn client id>
export AAD_SERVICE_PRINCIPAL_CLIENT_SECRET=<spn secret>

kubectl get nodes

Client secret in environment variable

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AZURE_CLIENT_ID=<spn client id>
export AZURE_CLIENT_SECRET=<spn secret>

kubectl get nodes

Client secret in command-line flag

export KUBECONFIG=/path/to/kubeconfig

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

kubectl get nodes

Warning

this will leave the secret in the kubeconfig

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>

kubectl get nodes

Client certificate

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>

kubectl get nodes

Proof-of-possession (PoP) token with client secret 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>

kubectl get nodes

Restrictions

• on AKS, it will only work with managed AAD
• the service principal can be member of maximum 200 AAD groups

Managed Service Identity

This login mode should be used in an environment where Managed Service Identity is available such as Azure Virtual Machine, Azure Virtual Machine ScaleSet, Cloud Shell, Azure Container Instance, and Azure App Service.

The token will not be cached on the filesystem.

Usage Examples

Using default Managed Service Identity

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l msi

kubectl get nodes

Using Managed Service Identity with specific identity

export KUBECONFIG=/path/to/kubeconfig

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

kubectl get nodes

Workload Identity

This login mode uses Azure AD federated identity credentials to authenticate to Kubernetes clusters with Azure AD integration. This works by setting the environment variables:

• AZURE_CLIENT_ID is Azure Active Directory application ID that is federated with workload identity
• AZURE_TENANT_ID is Azure Active Directory tenant ID
• AZURE_FEDERATED_TOKEN_FILE is the file containing signed assertion of workload identity. E.g. Kubernetes projected service account (jwt) token
• AZURE_AUTHORITY_HOST is the base URL of an Azure Active Directory authority. E.g. https://login.microsoftonline.com/

With workload identity, it’s possible to access Kubernetes clusters from CI/CD system such as Github, ArgoCD, etc. without storing Service Principal credentials in those external systems. To learn more, here is a sample to setup OIDC federation from Github.

In this login mode, token will not be cached on the filesystem.

Usage Examples

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l workloadidentity

kubectl get nodes

Resource Owner Password Credential (ropc)

Warning:

Microsoft recommends you do not use the ROPC flow

Note:

ROPC is not supported in hybrid identity federation scenarios (for example, Azure AD and ADFS used to authenticate on-premises accounts). If users are redirected to an on-premises identity providers, Azure AD is not able to test the username and password against that identity provider. Pass-through authentication is supported with ROPC, however. It also does not work when MFA policy is enabled Personal accounts that are invited to an Azure AD tenant can’t use ROPC

In this login mode, the access token and refresh token will be cached at ${HOME}/.kube/cache/kubelogin directory. This path can be overriden by --token-cache-dir.

Usage Examples

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l ropc

export AAD_USER_PRINCIPAL_NAME=foo@bar.com
export AAD_USER_PRINCIPAL_PASSWORD=<password>

kubectl get nodes

Reference

https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth-ropc

Using kubelogin with AKS

AKS uses a pair of first party Azure AD applications. These application IDs are the same in all environments.

Azure Kubernetes Service AAD Server

applicationID: 6dae42f8-4368-4678-94ff-3960e28e3630

This is the application used by the server side. The access token accessing AKS clusters need to be issued for this app. In most of kubelogin login modes, --server-id is required parameter in kubelogin get-token.

Azure Kubernetes Service AAD Client

applicationID: 80faf920-1908-4b52-b5ef-a8e7bedfc67a

This is a public client application used by kubelogin to perform login on behalf of the user. It’s used in device code, web browser interactive, and ropc login modes.

Using kubelogin with Azure Arc

kubelogin can be used to authenticate with Azure Arc-enabled clusters by requesting a proof-of-possession (PoP) token. This can be done by providing both of the following flags together:

1. --pop-enabled: indicates that kubelogin should request a PoP token instead of a regular bearer token
2. --pop-claims: is a comma-separated list of key=value claims to include in the PoP token. At minimum, this must include the u-claim as u=ARM_ID_OF_CLUSTER, which specifies the host that the requested token should allow access on.

These flags can be provided to either kubelogin get-token directly to get a PoP token, or to kubelogin convert-kubeconfig for kubectl to request the token internally.

PoP token requests only work with interactive and spn login modes; these flags will be ignored if provided for other login modes.

AAD Server App

applicationID: 6256c85f-0aad-4d50-b960-e6e9b21efe35

This is the application used by the server side. The access token needs to be issued for this app to access a 1P Arc-enabled cluster.

This server app ID is a required parameter for web browser interactive login mode supporting PoP token authentication.

AAD Client App

applicationID: 3f4439ff-e698-4d6d-84fe-09c9d574f06b

This is a 1P client application used by kubelogin to perform login on behalf of the user. It should be used for web browser interactive login mode when using PoP token authentication.

Command Line Tool

kubelogin command-line tool has following subcommands:

kubelogin -h
login to azure active directory and populate kubeconfig with AAD tokens

Usage:
  kubelogin [flags]
  kubelogin [command]

Available Commands:
  completion         Generate the autocompletion script for the specified shell
  convert-kubeconfig convert kubeconfig to use exec auth module
  get-token          get AAD token
  help               Help about any command
  remove-tokens      Remove all cached tokens from filesystem

Flags:
  -h, --help          help for kubelogin
      --logtostderr   log to standard error instead of files (default true)
  -v, --v Level       number for the log level verbosity
      --version       version for kubelogin

Use "kubelogin [command] --help" for more information about a command.

Following sections provide in-depth information on these subcommands:

• kubelogin convert-kubeconfig - converts the kubeconfig to different login mode
• kubelogin get-token - gets the Azure AD token based on configured login mode. This subcommand is typically used in kubeconfig via exec plugin and is invoked by kubectl or any command-line tool, such as helm, implementing exec plugin.
• kubelogin remove-tokens - removes the cached token on the filesystem

convert-kubeconfig

This subcommand converts kubeconfig to Exec plugin using kubelogin get-token with specified login mode.

Note that when --context is specified, only the matching kubeconfig context will be converted. Otherwise, every kubeconfig context that uses azure auth or Exec plugin will be converted.

Usage

kubelogin convert-kubeconfig -h
convert kubeconfig to use exec auth module

Usage:
  kubelogin convert-kubeconfig [flags]

Flags:
      --authority-host string                Workload Identity authority host. It may be specified in AZURE_AUTHORITY_HOST environment variable
      --azure-config-dir string              Azure CLI config path
      --client-certificate string            AAD client cert in pfx. Used in spn login. It may be specified in AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE or AZURE_CLIENT_CERTIFICATE_PATH environment variable
      --client-certificate-password string   Password for AAD client cert. Used in spn login. It may be specified in AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE_PASSWORD or AZURE_CLIENT_CERTIFICATE_PASSWORD environment variable
      --client-id string                     AAD client application ID. It may be specified in AAD_SERVICE_PRINCIPAL_CLIENT_ID or AZURE_CLIENT_ID environment variable
      --client-secret string                 AAD client application secret. Used in spn login. It may be specified in AAD_SERVICE_PRINCIPAL_CLIENT_SECRET or AZURE_CLIENT_SECRET environment variable
      --context string                       The name of the kubeconfig context to use
  -e, --environment string                   Azure environment name (default "AzurePublicCloud")
      --federated-token-file string          Workload Identity federated token file. It may be specified in AZURE_FEDERATED_TOKEN_FILE environment variable
  -h, --help                                 help for convert-kubeconfig
      --identity-resource-id string          Managed Identity resource id.
      --kubeconfig string                    Path to the kubeconfig file to use for CLI requests.
      --legacy                               set to true to get token with 'spn:' prefix in audience claim
  -l, --login string                         Login method. Supported methods: devicecode, interactive, spn, ropc, msi, azurecli, azd, workloadidentity. It may be specified in AAD_LOGIN_METHOD environment variable (default "devicecode")
      --password string                      password for ropc login flow. It may be specified in AAD_USER_PRINCIPAL_PASSWORD or AZURE_PASSWORD environment variable
      --pop-enabled                          set to true to request a proof-of-possession/PoP token, or false to request a regular bearer token. Only works with interactive and spn login modes. --pop-claims must be provided if --pop-enabled is true
      --pop-claims                           claims to include when requesting a PoP token, formatted as a comma-separated string of key=value pairs. Must include the u-claim, `u=ARM_ID` containing the ARM ID of the cluster (host). --pop-enabled must be set to true if --pop-claims are provided
      --server-id string                     AAD server application ID
  -t, --tenant-id string                     AAD tenant ID. It may be specified in AZURE_TENANT_ID environment variable
      --token-cache-dir string               directory to cache token (default "${HOME}/.kube/cache/kubelogin/")
      --use-azurerm-env-vars                 Use environment variable names of Terraform Azure Provider (ARM_CLIENT_ID, ARM_CLIENT_SECRET, ARM_CLIENT_CERTIFICATE_PATH, ARM_CLIENT_CERTIFICATE_PASSWORD, ARM_TENANT_ID)
      --username string                      user name for ropc login flow. It may be specified in AAD_USER_PRINCIPAL_NAME or AZURE_USERNAME environment variable

Global Flags:
      --logtostderr   log to standard error instead of files (default true)
  -v, --v Level       number for the log level verbosity

get-token

This subcommand uses specified login mode to authenticate with Azure AD and return the access token to standard out.

Usage

kubelogin get-token -h
get AAD token

Usage:
  kubelogin get-token [flags]

Flags:
      --authority-host string                Workload Identity authority host. It may be specified in AZURE_AUTHORITY_HOST environment variable
      --client-certificate string            AAD client cert in pfx. Used in spn login. It may be specified in AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE or AZURE_CLIENT_CER
TIFICATE_PATH environment variable
      --client-certificate-password string   Password for AAD client cert. Used in spn login. It may be specified in AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE_PASSWORD or A
ZURE_CLIENT_CERTIFICATE_PASSWORD environment variable
      --client-id string                     AAD client application ID. It may be specified in AAD_SERVICE_PRINCIPAL_CLIENT_ID or AZURE_CLIENT_ID environment variable
      --client-secret string                 AAD client application secret. Used in spn login. It may be specified in AAD_SERVICE_PRINCIPAL_CLIENT_SECRET or AZURE_CLIENT_S
ECRET environment variable
  -e, --environment string                   Azure environment name (default "AzurePublicCloud")
      --federated-token-file string          Workload Identity federated token file. It may be specified in AZURE_FEDERATED_TOKEN_FILE environment variable
  -h, --help                                 help for get-token
      --identity-resource-id string          Managed Identity resource id.
      --legacy                               set to true to get token with 'spn:' prefix in audience claim
  -l, --login string                         Login method. Supported methods: devicecode, interactive, spn, ropc, msi, azurecli, azd, workloadidentity. It may be specified in A
AD_LOGIN_METHOD environment variable (default "devicecode")
      --password string                      password for ropc login flow. It may be specified in AAD_USER_PRINCIPAL_PASSWORD or AZURE_PASSWORD environment variable
      --pop-enabled                          set to true to request a proof-of-possession/PoP token, or false to request a regular bearer token. Only works with interactive and spn login modes. --pop-claims must be provided if --pop-enabled is true
      --pop-claims                           claims to include when requesting a PoP token, formatted as a comma-separated string of key=value pairs. Must include the u-claim, `u=ARM_ID` containing the ARM ID of the cluster (host). --pop-enabled must be set to true if --pop-claims are provided
      --server-id string                     AAD server application ID
  -t, --tenant-id string                     AAD tenant ID. It may be specified in AZURE_TENANT_ID environment variable
      --token-cache-dir string               directory to cache token (default "${HOME}/.kube/cache/kubelogin/")
      --use-azurerm-env-vars                 Use environment variable names of Terraform Azure Provider (ARM_CLIENT_ID, ARM_CLIENT_SECRET, ARM_CLIENT_CERTIFICATE_PATH, ARM
_CLIENT_CERTIFICATE_PASSWORD, ARM_TENANT_ID)
      --username string                      user name for ropc login flow. It may be specified in AAD_USER_PRINCIPAL_NAME or AZURE_USERNAME environment variable

Global Flags:
      --logtostderr   log to standard error instead of files (default true)
  -v, --v Level       number for the log level verbosity

Exec Plugin Examples

cluster info including cluster CA and FQDN are omitted in below examples

Device Code Flow (default)

kind: Config
preferences: {}
users:
  - name: user-name
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        command: kubelogin
        args:
          - get-token
          - --environment
          - AzurePublicCloud
          - --server-id
          - <AAD server app ID>
          - --client-id
          - <AAD client app ID>
          - --tenant-id
          - <AAD tenant ID>

web browser Flow (default)

kind: Config
preferences: {}
users:
  - name: user-name
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        args:
        - get-token
        - --login
        - interactive
        - --server-id
        - <AAD server app ID>
        - --client-id
        - <AAD client app ID>
        - --tenant-id
        - <AAD tenant ID>
        - --environment
        - AzurePublicCloud
        command: kubelogin

Spn login with secret

kind: Config
preferences: {}
users:
  - name: demouser
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        args:
          - get-token
          - --environment
          - AzurePublicCloud
          - --server-id
          - <AAD server app ID>
          - --client-id
          - <AAD client app ID>
          - --client-secret
          - <client_secret>
          - --tenant-id
          - <AAD tenant ID>
          - --login
          - spn
        command: kubelogin
        env: null

Spn login with pfx certificate

kind: Config
preferences: {}
users:
  - name: demouser
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        args:
          - get-token
          - --environment
          - AzurePublicCloud
          - --server-id
          - <AAD server app ID>
          - --client-id
          - <AAD client app ID>
          - --client-certificate
          - <client_certificate_path>
          - --tenant-id
          - <AAD tenant ID>
          - --login
          - spn
        command: kubelogin
        env: null

Managed Service Identity

kind: Config
preferences: {}
users:
  - name: user-name
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        command: kubelogin
        args:
          - get-token
          - --server-id
          - <AAD server app ID>
          - --login
          - msi

Managed Service Identity with specific client ID

kind: Config
preferences: {}
users:
  - name: user-name
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        command: kubelogin
        args:
          - get-token
          - --server-id
          - <AAD server app ID>
          - --client-id
          - <MSI app ID>
          - --login
          - msi

Azure CLI token login

kind: Config
preferences: {}
users:
  - name: demouser
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        args:
          - get-token
          - --server-id
          - <AAD server app ID>
          - --login
          - azurecli
        command: kubelogin
        env: null

Workload Identity

kind: Config
preferences: {}
users:
  - name: demouser
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        args:
          - get-token
          - --server-id
          - <AAD server app ID>
          - --login
          - workloadidentity
        command: kubelogin
        env: null

remove-tokens

This subcommand removes the cached access/refresh token from filesystem. Note that only devicelogin, interactive, and ropc login modes will cache the token.

Usage

kubelogin remove-tokens -h
Remove all cached tokens from filesystem

Usage:
  kubelogin remove-tokens [flags]

Flags:
  -h, --help                     help for remove-tokens
      --token-cache-dir string   directory to cache token (default "${HOME}/.kube/cache/kubelogin/")

Global Flags:
      --logtostderr   log to standard error instead of files (default true)
  -v, --v Level       number for the log level verbosity

Topics

This section documents different usages of kubelogin in details.

Using in different environments

kubelogin supports Azure Environments:

• AzurePublicCloud (default value)
• AzureChinaCloud
• AzureUSGovernmentCloud
• AzureStackCloud

You can specify --environment in kubelogin convert-kubeconfig.

When using AzureStackCloud you will need to specify the actual endpoints in a config file, and set the environment variable AZURE_ENVIRONMENT_FILEPATH to that file.

The configuration parameters of this file:

{
  "name": "AzureStackCloud",
  "managementPortalURL": "...",
  "publishSettingsURL": "...",
  "serviceManagementEndpoint": "...",
  "resourceManagerEndpoint": "...",
  "activeDirectoryEndpoint": "...",
  "galleryEndpoint": "...",
  "keyVaultEndpoint": "...",
  "graphEndpoint": "...",
  "serviceBusEndpoint": "...",
  "batchManagementEndpoint": "...",
  "storageEndpointSuffix": "...",
  "sqlDatabaseDNSSuffix": "...",
  "trafficManagerDNSSuffix": "...",
  "keyVaultDNSSuffix": "...",
  "serviceBusEndpointSuffix": "...",
  "serviceManagementVMDNSSuffix": "...",
  "resourceManagerVMDNSSuffix": "...",
  "containerRegistryDNSSuffix": "...",
  "cosmosDBDNSSuffix": "...",
  "tokenAudience": "...",
  "resourceIdentifiers": {
    "graph": "...",
    "keyVault": "...",
    "datalake": "...",
    "batch": "...",
    "operationalInsights": "..."
  }
}

The full configuration is available in the source code at https://github.com/Azure/go-autorest/blob/main/autorest/azure/environments.go.

Using Service Principal

This section documents the end to end flow to use kubelogin to access AKS cluster with a service principal.

1. Create a service principal or use an existing one.

az ad sp create-for-rbac --skip-assignment --name myAKSAutomationServicePrincipal

The output is similar to the following example.

{
  "appId": "<spn client id>",
  "displayName": "myAKSAutomationServicePrincipal",
  "name": "http://myAKSAutomationServicePrincipal",
  "password": "<spn secret>",
  "tenant": "<aad tenant id>"
}

2. Query your service principal AAD Object ID by using the command below.

az ad sp show --id <spn client id> --query "id"

3. To configure the role binding on Azure Kubernetes Service, the user in rolebinding should be the SP’s Object ID.

For example,

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: sp-role-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
  - apiGroup: rbac.authorization.k8s.io
    kind: User
    name: <service-principal-object-id>

4. Use kubelogin to convert the kubeconfig

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<spn client id>
export AAD_SERVICE_PRINCIPAL_CLIENT_SECRET=<spn secret>

kubectl get nodes

or write your spn secret permanently into the kubeconfig (not preferred!):

export KUBECONFIG=/path/to/kubeconfig

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

kubectl get nodes

Setup k8s OIDC Provider using Azure AD

kubelogin can be used to authenticate to general kubernetes clusters using AAD as an OIDC provider.

1. Create an AAD Enterprise Application and the corresponding App Registration. Check the Allow public client flows checkbox. Configure groups to be included in the response. Take a note of the directory (tenant) ID as $AAD_TENANT_ID and the application (client) ID as $AAD_CLIENT_ID

2. Configure the API server with the following flags:

   • Issuer URL: --oidc-issuer-url=https://sts.windows.net/$AAD_TENANT_ID/
   • Client ID: --oidc-client-id=$AAD_CLIENT_ID
   • Username claim: --oidc-username-claim=upn

   See the kubernetes docs for optional flags. For EKS clusters configure this on the Management Console or via terraform.

3. Configure the Exec plugin with kubelogin to use the application from the first step:

   kubectl config set-credentials "azure-user" \
     --exec-api-version=client.authentication.k8s.io/v1beta1 \
     --exec-command=kubelogin \
     --exec-arg=get-token \
     --exec-arg=--environment \
     --exec-arg=AzurePublicCloud \
     --exec-arg=--server-id \
     --exec-arg=$AAD_CLIENT_ID \
     --exec-arg=--client-id \
     --exec-arg=$AAD_CLIENT_ID \
     --exec-arg=--tenant-id \
     --exec-arg=$AAD_TENANT_ID
   

4. Use this credential to connect to the cluster:

   kubectl config set-context "$CLUSTER_NAME" --cluster="$CLUSTER_NAME" --user=azure-user
   kubectl config use-context "$CLUSTER_NAME"
   

Using kubelogin in Jenkins

In Jenkins, since workspaces are most likely run under jenkins user, different login modes may have different configuration requirements to allow multiple builds to run concurrently. When it is not configured properly, there may be clashing in cache or login context that results in You must be logged in to the server (Unauthorized) error message.

Using Azure CLI Login mode

When Azure CLI is installed in Jenkins environment, Azure CLI’s config directory likely resides in Jenkins workspace directory. To use the Azure CLI, environment variable AZURE_CONFIG_DIR should be specified.

Using kubelogin convert-kubeconfig subcommand with --azure-config-dir, the generated kubeconfig will configure the environment variable for get-token subcommand to find the corresponding Azure config directory. For example,

stage('Download kubeconfig and convert') {
    steps {
        sh 'az aks get-credentials -g ${RESOURCE_GROUP} -n ${CLUSTER_NAME}'
        sh 'kubelogin convert-kubeconfig -l azurecli --azure-config-dir ${WORKSPACE}/.azure'
    }
}

stage('Run kubectl') {
    steps {
        sh 'kubectl get nodes'
    }
}

Using Device Code, Web Browser, and ROPC Login Modes

Since kubelogin by default caches tokens at ${HOME}/.kube/cache/kubelogin in device code, web browser interactive, and ropc login modes, kubelogin covert-kubeconfig --token-cache-dir should be specified to a directory under Jenkins workspace such as ${WORKSPACE}/.kube/cache/kubelogin.

Known Issues

• Maximum 200 groups will be included in the Azure AD JWT. For more than 200 groups, consider using Application Roles
• Groups created in Azure AD can only be included by their ObjectID and not name, as sAMAccountName is only available for groups synchronized from Active Directory
• kubelogin may not work with MSI when run in Azure Container Instance
• On AKS, service principal login mode will only work with managed AAD, not legacy AAD.
• Device code login mode does not work when Conditional Access policy is configured on Azure AD tenant. Use web browser interactive instead.

Development

Releasing

To make a new release and publish please follow the following steps.

1. Create a branch publish-x.y.z
2. Add a section to CHANGELOG.md with the header ## [x.y.z] (N.B: make sure to write the new version in square brackets as the changelog-reader action only works if the CHANGELOG.md file follows the Keep a Changelog standard)
3. Create a new PR, get approval and merge
4. Run the release workflow manually from the GH Actions tab

Sample Changelog content for first release.

For first release using new release and publish using changelog here is a sample:

## [0.0.26]

* What is getting released here + @commit

Thanks to whoever was involved, pm.

In Event of Special Case Failures Post Build and Release.

In an event where build and release were successful but publish failed for something else, in that case please make sure we delete the unsucessful release note and release tag, before re-running the release again, this will get release fresh release notes and tag.

Contributing

The Azure Kubelogin project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. Contributing

Microsoft Open Source Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct.

Resources:

• Microsoft Open Source Code of Conduct
• Microsoft Code of Conduct FAQ
• Contact opencode@microsoft.com with questions or concerns