Uso de kubelogin para autenticar usuarios en Azure Kubernetes Service

  • Artículo

El complemento kubelogin en Azure es un complemento de credenciales de cliente que implementa la autenticación de Microsoft Entra. El complemento kubelogin ofrece características que no están disponibles en la herramienta de línea de comandos kubectl.

Los clústeres de Azure Kubernetes Service (AKS) que se integran con el identificador de Entra de Microsoft y que ejecutan Kubernetes versión 1.24 o posterior usan automáticamente el formato kubelogin.

En este artículo se proporciona información general y ejemplos de cómo usar kubelogin para todos los métodos de autenticación admitidos de Microsoft Entra en AKS.

Limitaciones

  • Puede incluir un máximo de 200 grupos en una notificación de Token web JSON (JWT) de Microsoft Entra. Si tiene más de 200 grupos, considere la posibilidad de usar roles de aplicación.
  • Los grupos creados en el identificador de Entra de Microsoft solo se incluyen por su valor ObjectID y no por su nombre para mostrar. El sAMAccountName comando solo está disponible para grupos que se sincronizan desde Windows Server Active Directory local.
  • En AKS, el método de autenticación de la entidad de servicio solo funciona con el identificador de Microsoft Entra administrado y no con la versión anterior de Azure Active Directory.
  • El método de autenticación de código de dispositivo no funciona cuando se establece una directiva de acceso condicional de Microsoft Entra en un inquilino de Microsoft Entra. En ese escenario, use la autenticación interactiva del explorador web.

Funcionamiento de la autenticación

Para la mayoría de las interacciones con kubelogin, se usa el convert-kubeconfig subcomando. El subcomando usa el archivo kubeconfig especificado en --kubeconfig o en la KUBECONFIG variable de entorno para convertir el archivo kubeconfig final al formato exec basado en el método de autenticación especificado.

Los métodos de autenticación que implementa kubelogin son flujos de concesión de tokens de Microsoft Entra OAuth 2.0. Las marcas de parámetro siguientes son habituales en subcomandos kubelogin. En general, estas marcas están listas para usarse al obtener el archivo kubeconfig de AKS.

  • --tenant-id: identificador de inquilino de Microsoft Entra.
  • --client-id: el identificador de aplicación de la aplicación cliente pública. Esta aplicación cliente solo se usa en los métodos de inicio de sesión de credenciales de contraseña de propietario de recursos (ROPC) (identidad de flujo de trabajo) del código del dispositivo, el explorador web interactivo y OAuth 2.0.
  • --server-id: el identificador de aplicación de la aplicación web o el servidor de recursos. El token se emite a este recurso.

Nota:

En cada método de autenticación, el token no se almacena en caché en el sistema de archivos.

Métodos de autenticación

En las secciones siguientes se describen los métodos de autenticación admitidos y cómo usarlos:

  • Código del dispositivo
  • CLI de Azure
  • Explorador web interactivo
  • Entidad de servicio
  • Identidad administrada
  • Identidad de la carga de trabajo

Código del dispositivo

El código de dispositivo es el método de autenticación predeterminado para el convert-kubeconfig subcomando. El -l devicecode es opcional. Este método de autenticación solicita al usuario que inicie sesión desde una sesión del explorador.

Antes de que se introdujeran los complementos kubelogin y exec, el método de autenticación de Azure en kubectl solo admitía el flujo de código del dispositivo. Usó una versión anterior de una biblioteca que genera un token que tiene la audience notificación con un spn: prefijo. No es compatible con el identificador de Entra de Microsoft administrado de AKS, que usa un flujo en nombre de (OBO). Al ejecutar el convert-kubeconfig subcomando, kubelogin quita el spn: prefijo de la notificación de audiencia.

Si los requisitos incluyen el uso de la funcionalidad de versiones anteriores, agregue el --legacy argumento . Si usa el archivo kubeconfig en un clúster de Azure Active Directory de versión anterior, kubelogin agrega automáticamente la --legacy marca.

En este método de inicio de sesión, el token de acceso y el token de actualización se almacenan en caché en el directorio ${HOME}/.kube/cache/kubelogin . Para invalidar esta ruta de acceso, incluya el --token-cache-dir parámetro .

Si el clúster integrado de Microsoft Entra de AKS usa Kubernetes 1.24 o versiones anteriores, debe convertir manualmente el formato de archivo kubeconfig ejecutando los siguientes comandos:

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

Ejecute este comando kubectl para obtener información del nodo:

kubectl get nodes

Para limpiar los tokens almacenados en caché, ejecute el siguiente comando:

kubelogin remove-tokens

Nota:

El método de inicio de sesión de código de dispositivo no funciona cuando se configura una directiva de acceso condicional en un inquilino de Microsoft Entra. En este escenario, use el método interactivo del explorador web.

CLI de Azure

El método de autenticación de la CLI de Azure usa el contexto de sesión que establece la CLI de Azure para obtener el token de acceso. El token se emite en el mismo inquilino de Microsoft Entra que az login. kubelogin no escribe tokens en el archivo de caché de tokens porque ya están administrados por la CLI de Azure.

Nota:

Este método de autenticación solo funciona con el identificador de Microsoft Entra administrado por AKS.

En el ejemplo siguiente se muestra cómo usar el método de la CLI de Azure para autenticarse:

az login

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l azurecli

Ejecute este comando kubectl para obtener información del nodo:

kubectl get nodes

Si el directorio de configuración de la CLI de Azure está fuera del directorio ${HOME} , use el --azure-config-dir parámetro con el convert-kubeconfig subcomando. El comando genera el archivo kubeconfig con la variable de entorno configurada. Puede obtener la misma configuración estableciendo la AZURE_CONFIG_DIR variable de entorno en este directorio al ejecutar un comando kubectl.

Explorador web interactivo

El método interactivo del explorador web de autenticación abre automáticamente un explorador web para iniciar sesión en el usuario. Una vez autenticado el usuario, el explorador redirige al servidor web local mediante las credenciales comprobadas. Este método de autenticación cumple la directiva de acceso condicional.

Cuando se autentica mediante este método, el token de acceso se almacena en caché en el directorio ${HOME}/.kube/cache/kubelogin . Puede invalidar esta ruta de acceso mediante el --token-cache-dir parámetro .

Portador token

En el ejemplo siguiente se muestra cómo usar un token de portador con el flujo interactivo del explorador web:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l interactive

Ejecute este comando kubectl para obtener información del nodo:

kubectl get nodes

Token de prueba de posesión

En el ejemplo siguiente se muestra cómo usar un token de prueba de posesión (PoP) con el flujo interactivo del explorador web:

export KUBECONFIG=/path/to/kubeconfig

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

Ejecute este comando kubectl para obtener información del nodo:

kubectl get nodes

Entidad de servicio

Este método de autenticación usa una entidad de servicio para iniciar sesión en el usuario. Puede proporcionar la credencial estableciendo una variable de entorno o usando la credencial en un argumento de línea de comandos. Las credenciales admitidas que puede usar son una contraseña o un certificado de cliente de Intercambio de información personal (PFX).

Antes de usar este método, tenga en cuenta las siguientes limitaciones:

  • Este método solo funciona con el identificador de Microsoft Entra administrado.
  • La entidad de servicio puede ser miembro de un máximo de 200 grupos de Microsoft Entra.

Variables de entorno

En el ejemplo siguiente se muestra cómo configurar un secreto de cliente mediante variables de entorno:

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>

Ejecute este comando kubectl para obtener información del nodo:

kubectl get nodes

Luego, ejecute este comando:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

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

Ejecute este comando kubectl para obtener información del nodo:

kubectl get nodes

Argumento de línea de comandos

En el ejemplo siguiente se muestra cómo configurar un secreto de cliente en un argumento de línea de comandos:

export KUBECONFIG=/path/to/kubeconfig

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

Ejecute este comando kubectl para obtener información del nodo:

kubectl get nodes

Advertencia

El método de argumento de la línea de comandos almacena el secreto en el archivo kubeconfig.

Certificado de cliente

En el ejemplo siguiente se muestra cómo configurar un secreto de cliente mediante un certificado de cliente:

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>

Ejecute este comando kubectl para obtener información del nodo:

kubectl get nodes

Luego, ejecute este comando:

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>

Ejecute este comando kubectl para obtener información del nodo:

kubectl get nodes

Token de poP y variables de entorno

En el ejemplo siguiente se muestra cómo configurar un token de poP que usa un secreto de cliente que obtiene de variables de entorno:

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>

Ejecute este comando kubectl para obtener información del nodo:

kubectl get nodes

Identidad administrada

Use el método de autenticación de identidad administrada para las aplicaciones que se conectan a los recursos que admiten la autenticación de Microsoft Entra. Algunos ejemplos incluyen el acceso a recursos de Azure, como una máquina virtual de Azure, un conjunto de escalado de máquinas virtuales o Azure Cloud Shell.

Identidad administrada predeterminada

En el ejemplo siguiente se muestra cómo usar la identidad administrada predeterminada:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l msi

Ejecute este comando kubectl para obtener información del nodo:

kubectl get nodes

Identidad específica

En el ejemplo siguiente se muestra cómo usar una identidad administrada con una identidad específica:

export KUBECONFIG=/path/to/kubeconfig

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

Ejecute este comando kubectl para obtener información del nodo:

kubectl get nodes

Identidad de la carga de trabajo

El método de autenticación de identidad de carga de trabajo usa credenciales de identidad federadas con Microsoft Entra para autenticar el acceso a los clústeres de AKS. El método usa la autenticación integrada de Microsoft Entra. Funciona estableciendo las siguientes variables de entorno:

  • AZURE_CLIENT_ID: identificador de aplicación de Microsoft Entra federado con la identidad de carga de trabajo.
  • AZURE_TENANT_ID: identificador de inquilino de Microsoft Entra.
  • AZURE_FEDERATED_TOKEN_FILE: el archivo que contiene una aserción firmada de la identidad de carga de trabajo, como un token de cuenta de servicio proyectado (JWT) de Kubernetes.
  • AZURE_AUTHORITY_HOST: la dirección URL base de una autoridad de Microsoft Entra. Por ejemplo, https://login.microsoftonline.com/.

Puede usar una identidad de carga de trabajo para acceder a clústeres de Kubernetes desde sistemas de CI/CD como GitHub o ArgoCD sin almacenar credenciales de entidad de servicio en los sistemas externos. Para configurar la federación de openID Conectar (OIDC) desde GitHub, consulte el ejemplo de federación de OIDC.

En el ejemplo siguiente se muestra cómo usar una identidad de carga de trabajo:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l workloadidentity

Ejecute este comando kubectl para obtener información del nodo:

kubectl get nodes

Uso de kubelogin con AKS

AKS usa un par de aplicaciones de Microsoft Entra de primera entidad. Los identificadores de estas aplicaciones son los mismos en todos los entornos.

El identificador de aplicación de servidor de Microsoft Entra de AKS que usa el lado servidor es 6dae42f8-4368-4678-94ff-3960e28e3630. El token de acceso que accede a los clústeres de AKS debe emitirse para esta aplicación. En la mayoría de los métodos de autenticación kubelogin, debe usar --server-id con kubelogin get-token.

El identificador de aplicación cliente de Microsoft Entra de AKS que kubelogin usa para realizar la autenticación de cliente pública en nombre del usuario es 80faf920-1908-4b52-b5ef-a8e7bedfc67a. El identificador de aplicación cliente se usa en el código de dispositivo y los métodos de autenticación interactivas del explorador web.

Contenido relacionado