Uso de kubelogin para autenticar usuarios en Azure Kubernetes Service (AKS)

El complemento kubelogin en Azure es un complemento de credenciales de cliente plugin 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. Para obtener más información, consulte la introducción a kubelogin y la introducción a kubectl.

Este artículo ofrece una introducción y ejemplos sobre cómo usar kubelogin con los métodos de autenticación admitidos de Microsoft Entra recomendados para AKS.

Limitaciones de la autenticación de Kubelogin en AKS

  • Los grupos creados en Microsoft Entra solo se incluyen por su valor ObjectID y no por su nombre para mostrar. El comando sAMAccountName solo está disponible para grupos sincronizados desde Windows Server Active Directory local.
  • El método de autenticación de la entidad de servicio solo funciona con la integración administrada de Microsoft Entra ID, no con la integración heredada de Microsoft Entra ID.
  • La entidad de servicio puede ser miembro de un máximo de 200 grupos de Microsoft Entra. Si tiene más de 200 grupos, considere la posibilidad de utilizar roles de aplicación.
  • El método de autenticación por 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 en su lugar.
  • El método de autenticación de la CLI de Azure solo funciona con Microsoft Entra.

Funcionamiento de la autenticación kubelogin en AKS

Los clústeres de AKS que ejecutan kubernetes versión 1.24 o posterior usan automáticamente el formato del complemento kubelogin exec. Los clústeres que ejecutan versiones de Kubernetes anteriores a la 1.24 requieren la conversión manual a este formato.

Para la mayoría de las interacciones con kubelogin, use el convert-kubeconfig subcomando. El subcomando usa el archivo kubeconfig que especifique 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 OAuth 2.0 de Microsoft Entra. El comportamiento de la caché depende del método de autenticación. El código de dispositivo, el inicio de sesión interactivo en el navegador web y la autenticación mediante credenciales de contraseña del propietario del recurso (ROPC) almacenan en caché los registros de autenticación en el directorio de caché de kubelogin. Los métodos como CLI de Azure y CLI de Azure para desarrolladores usan la memoria caché administrada por su respectiva herramienta de línea de comandos en lugar de la caché de kubelogin.

Autenticación con código de dispositivo

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

Nota:

Antes de la introducción de los complementos kubelogin y exec, el método de autenticación de Azure en kubectl solo admitía el flujo de código de dispositivo. Utilizaba una versión anterior de una biblioteca que genera un token que tiene la reclamación audience con el prefijo spn:. No es compatible con Microsoft Entra, que usa un flujo en nombre de (OBO). Cuando se ejecuta el subcomando convert-kubeconfig, kubelogin elimina el prefijo spn: de la reclamación de audiencia.

Parámetros para la autenticación de código de dispositivo

En la tabla siguiente se describen los parámetros que puede usar con la autenticación de código de dispositivo:

Parámetro Description
-l devicecode (opcional) Especifica el método de autenticación kubelogin. Este parámetro es opcional porque el código del dispositivo es el método predeterminado.
--legacy Utiliza el comportamiento heredado para los clústeres configurados con la integración heredada de Microsoft Entra ID. Si el archivo kubeconfig es para este clúster, kubelogin agrega automáticamente la --legacy marca .
--cache-dir Invalida la ruta de acceso predeterminada del directorio de caché de tokens, que es ${HOME}/.kube/cache/kubelogin.

Autenticación de la CLI de Azure

El método de autenticación de la CLI de Azure (comando: -l azurecli) usa el contexto de inicio de sesión que la CLI de Azure establece 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 la CLI de Azure ya las administra.

Parámetros para la autenticación de la CLI de Azure

En la tabla siguiente se describen los parámetros que puede usar con la autenticación de la CLI de Azure:

Parámetro Description
-l azurecli Especifica el método de autenticación kubelogin.
--azure-config-dir Especifica el directorio de configuración de la CLI de Azure. El directorio predeterminado es ${HOME}/.azure.

Inicio de sesión en Azure

Inicie sesión en Azure mediante el az login comando .

az login

Autenticación interactiva del explorador web

El método interactivo del explorador web (comando: -l interactive) 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.

Puede usar un token de portador o un token de prueba de posesión (PoP) con este método de autenticación.

Parámetros para la autenticación de tokens de portador

En la tabla siguiente se describen los parámetros que puede usar con la autenticación de token de portador:

Parámetro Description
-l interactive Especifica el método de autenticación kubelogin.
--cache-dir Invalida la ruta de acceso predeterminada del directorio de caché de tokens, que es ${HOME}/.kube/cache/kubelogin.

Parámetros para la autenticación de tokens poP

En la tabla siguiente se describen los parámetros que puede usar con la autenticación de token de PoP:

Parámetro Description
-l interactive Especifica el método de autenticación kubelogin.
--pop-enabled Habilita la autenticación de tokens poP.
--pop-claims Especifica las reclamaciones del token PoP en un formato de par clave-valor. Por ejemplo, u=/ARM/ID/OF/CLUSTER.

Autenticación de entidad de servicio

El método de autenticación de la entidad de servicio (comando: -l spn) utiliza una entidad de servicio para autenticar al usuario. Se puede proporcionar la credencial estableciendo una variable de entorno o utilizando la credencial en un argumento de línea de comandos. Las credenciales compatibles que puede utilizar son una contraseña o un certificado de cliente PFX (Personal Information Exchange).

Parámetros para la autenticación de la entidad de servicio

En la tabla siguiente se describen los parámetros que puede usar con la autenticación del principal de servicio:

Parámetro Description
-l spn Especifica el método de autenticación kubelogin.
--client-id El ID de aplicación (client-id) del principal de servicio.
--client-secret El secreto de cliente de la entidad de servicio.

Autenticación de identidad administrada

Use el método de autenticación de identidad administrada (comando: -l msi) 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 (VM) de Azure, Virtual Machine Scale Sets o Azure Cloud Shell.

Puede usar la identidad administrada predeterminada asignada al recurso o a una identidad administrada específica asignada por el usuario.

Parámetros para la autenticación de identidad administrada

En la tabla siguiente se describen los parámetros que puede usar con la autenticación de identidad administrada:

Parámetro Description
-l msi Especifica el método de autenticación kubelogin.
--client-id El identificador de aplicación (client-id) de la identidad administrada asignada por el usuario. Si no especifica este parámetro, se usa la identidad administrada predeterminada.

Autenticación de identidad de carga de trabajo

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

Variable Description
AZURE_CLIENT_ID El ID de aplicación de Microsoft Entra que está 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 afirmación firmada de la identidad de la carga de trabajo, como un token de cuenta de servicio proyectada de Kubernetes (JWT).
AZURE_AUTHORITY_HOST 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 Argo CD sin almacenar credenciales de entidad de servicio en los sistemas externos. Para configurar la federación OpenID Connect (OIDC) desde GitHub, consulte el ejemplo de federación OIDC.

Parámetros para la autenticación de identidad de carga de trabajo

En la tabla siguiente se describen los parámetros que puede usar con la autenticación de identidad de carga de trabajo:

Parámetro Description
-l workloadidentity Especifica el método de autenticación kubelogin.

autenticación de la CLI para desarrolladores de Azure

El método de autenticación Azure Developer CLI (comando: -l azd) usa el contexto de inicio de sesión que establece la CLI para desarrolladores de Azure para obtener el token de acceso. El token se emite en el mismo inquilino de Microsoft Entra que azd auth login. kubelogin no escribe tokens en su caché de tokens porque la CLI para desarrolladores de Azure las administra.

Este método de autenticación solo funciona con Microsoft Entra administrado en AKS. Para obtener más información, consulte la introducción a la CLI para desarrolladores de Azure.

Autenticación de Azure Pipelines

El método de autenticación Azure Pipelines (comando: -l azurepipelines) usa una conexión de servicio Azure Resource Manager y el token de acceso del sistema de la canalización para autenticarse. Este método solo funciona en Azure Pipelines. La canalización debe tener una conexión de servicio Azure Resource Manager y permitir que los scripts accedan al token de OAuth.

Cuando se usa una AzureCLI@2 tarea con una conexión de servicio Azure Resource Manager, kubelogin puede usar el identificador de inquilino, el identificador de cliente y el identificador de conexión de servicio que Azure Pipelines proporciona como variables de entorno. Para obtener más información, consulte conexiones de servicio de Azure Pipelines.

Warning

kubelogin también admite el método de autenticación de credenciales de contraseña del propietario del recurso (ROPC). Microsoft recomienda no usar ROPC porque no es compatible con la autenticación multifactor y algunos escenarios de identidad híbrida. Para obtener más información, consulte la guía Plataforma de identidad de Microsoft ROPC.

Exportar la ruta de acceso del archivo kubeconfig

Antes de ejecutar el convert-kubeconfig subcomando, exporte la ruta de acceso del archivo kubeconfig a la KUBECONFIG variable de entorno. Por ejemplo:

export KUBECONFIG=/path/to/kubeconfig

Convertir el archivo kubeconfig

Ejecute el convert-kubeconfig subcomando para convertir el archivo kubeconfig para usar el complemento exec para el método de autenticación elegido.

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. Ejecute el convert-kubeconfig subcomando para convertir el archivo kubeconfig para usar el complemento exec.

    kubelogin convert-kubeconfig -l spn

  2. Establezca las variables de entorno para el identificador de cliente y el secreto de cliente o el certificado de cliente. Por ejemplo:

    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

Conversión del archivo kubeconfig mediante la CLI para desarrolladores de Azure

  1. Inicie sesión con la CLI para desarrolladores de Azure.

    azd auth login

  2. Convierta el archivo kubeconfig para usar el método de autenticación de la CLI para desarrolladores de Azure.

    kubelogin convert-kubeconfig -l azd

Convertir el archivo kubeconfig en Azure Pipelines

En una tarea AzureCLI@2 que usa una conexión de servicio de Azure Resource Manager, convierta el archivo kubeconfig para usar la autenticación de Azure Pipelines.

kubelogin convert-kubeconfig -l azurepipelines

Eliminación de tokens almacenados en caché

Quite los tokens almacenados en caché mediante el kubelogin remove-cache-dir comando .

kubelogin remove-cache-dir

Obtención de información de nodo

Obtenga información del nodo mediante el kubectl get comando .

kubectl get nodes

Cómo usar los identificadores de aplicación de kubelogin con AKS

AKS utiliza un par de aplicaciones propias de Microsoft Entra. Los identificadores de estas aplicaciones son los mismos en todos los entornos.

Application Id. de aplicación (GUID) Se usa en
Aplicación de servidor de AKS (--server-id) 6dae42f8-4368-4678-94ff-3960e28e3630 Audiencia del token para todos los métodos de autenticación de kubelogin admitidos al acceder a AKS.
Aplicación cliente pública de AKS (--client-id) 80faf920-1908-4b52-b5ef-a8e7bedfc67a Código de dispositivo, explorador web interactivo y autenticación ROPC.

Cuando llame directamente a kubelogin get-token para AKS, especifique el identificador de la aplicación de servidor de AKS con --server-id. Para obtener parámetros específicos del modo, consulte la referencia de kubeloginget-token.

Nota:

El identificador de la aplicación cliente pública de AKS en esta sección es el valor --client-id para la autenticación con código de dispositivo, la autenticación interactiva en navegador web y la autenticación ROPC. Para la autenticación de la entidad de servicio y la identidad administrada, --client-id identifica la entidad de servicio o la identidad administrada asignada por el usuario en su lugar.

Por ejemplo, obtenga un token mediante la autenticación de código de dispositivo y los identificadores de aplicación de AKS:

kubelogin get-token \
    --login devicecode \
    --server-id 6dae42f8-4368-4678-94ff-3960e28e3630 \
    --client-id 80faf920-1908-4b52-b5ef-a8e7bedfc67a \
    --tenant-id <microsoft-entra-tenant-id>

Contenido relacionado

  • Se actualizó por última vez el