Autentica con OpenID Connect (OIDC)

En esta página, se muestra cómo configurar GKE On-Prem a fin de usar un proveedor de OpenID para la autenticación de clústeres de usuarios. Para aprender a usar OIDC con AD FS, consulta Autentica con OIDC y AD FS. Para aprender a usar OIDC con el proveedor de Google OpenID, consulta Autentica con OIDC y Google.

Para obtener una descripción general del flujo de autenticación de GKE On-Prem, consulta Autenticación.

Descripción general

GKE On-Prem admite OpenID Connect (OIDC) como uno de los mecanismos de autenticación para interactuar con el servidor de la API de Kubernetes de un clúster de usuario. Con OIDC, puedes administrar el acceso a los clústeres de Kubernetes mediante los procedimientos estándar de tu organización para la creación, inhabilitación y habilitación de cuentas de empleado.

Hay dos formas en que un empleado puede usar el flujo de autenticación OIDC:

  • Un empleado puede usar kubectl para iniciar un flujo de OIDC. A fin de que este flujo sea automático, GKE On-Prem proporciona el complemento de Anthos para Kubectl, un complemento de kubectl.
  • Un empleado puede usar Google Cloud Console para iniciar un flujo de autenticación de OIDC.

En este ejercicio, configurarás ambas opciones: kubectl y la consola de Google Cloud.

Antes de comenzar

En este tema suponemos que estás familiarizado con OAuth 2.0 y OpenID Connect. En este tema suponemos que estás familiarizado con los alcances de OpenID y las reclamaciones.

Personas

En este tema, se hace referencia a tres personas:

  • Administrador de la organización: Esta persona elige un proveedor de OpenID y registra las aplicaciones cliente con este.

  • Administrador de clústeres: Esta persona crea uno o más clústeres de usuario y archivos de configuración de autenticación para los desarrolladores que los usan.

  • Desarrollador: Esta persona ejecuta cargas de trabajo en uno o más clústeres y usa OIDC para la autenticación.

Elige un proveedor de OpenID

Esta sección está destinada a los administradores de la organización.

Puedes usar el proveedor de OpenID que desees. Para ver una lista de proveedores certificados, consulta OpenID Certification (Certificación de OpenID).

Una posibilidad es usar Active Directory Federated Services (AD FS) (Servicios federados de Active Directory) como tu proveedor de OpenID y usar una instancia local de Active Directory como tu base de datos de empleados. Para obtener más información, consulta Autenticar con OIDC y AD FS.

Otra posibilidad es usar Google como tu proveedor de OpenID.

Crea una URL de redireccionamiento para el complemento de Anthos para Kubectl

Esta sección está destinada a los administradores de la organización.

Como parte del establecimiento de una relación con tu proveedor de OpenID, debes especificar una URL de redireccionamiento que el proveedor pueda usar a fin de mostrar tokens de ID al complemento de Anthos para Kubectl. El complemento de Anthos para Kubectl se ejecuta en la máquina local de cada desarrollador y escucha en el puerto que elijas. Elige un número de puerto mayor que 1,024 que sea adecuado para este propósito. A continuación, se muestra la URL de redireccionamiento:

http://localhost:[PORT]/callback

en el que [PORT] es tu número de puerto.

Cuando configures tu proveedor de OpenID, especifica http://localhost:[PORT]/callback como una de tus URL de redireccionamiento. La forma de hacerlo depende del proveedor.

Configura una URL de redireccionamiento para la consola de Google Cloud

Esta sección está destinada a los administradores de la organización.

Además de tener una URL de redireccionamiento para kubectl, necesitas una URL de redireccionamiento para la consola de Google Cloud. La URL de redireccionamiento de la consola de Google Cloud es la siguiente:

https://console.cloud.google.com/kubernetes/oidc

Cuando configures tu proveedor de OIDC, especifica https://console.cloud.google.com/kubernetes/oidc como una de tus URL de redireccionamiento. La forma de hacerlo depende del proveedor.

Registra las aplicaciones cliente con el proveedor de OpenID

Esta sección está destinada a los administradores de la organización.

Antes de que los desarrolladores puedan usar el complemento de Anthos para Kubectl o la consola de Google Cloud con tu proveedor de OpenID, debes registrar esos dos clientes con el proveedor de OpenID. El registro incluye estos pasos:

  • Obtén más información sobre el URI de la entidad emisora del proveedor. Aquí es donde el complemento de Anthos para Kubectl o la consola de Google Cloud envían las solicitudes de autenticación.

  • Proporciona al proveedor la URL de redireccionamiento del complemento de Anthos para Kubectl.

  • Proporciona al proveedor la URL de redireccionamiento para la consola de Google Cloud. Esta es https://console.cloud.google.com/kubernetes/oidc

  • Establece un ID de cliente. Este es el ID que el proveedor usa a fin de identificar el complemento de Anthos para Kubectl y la consola de Google Cloud.

  • Establece un único secreto del cliente. El complemento de Anthos para Kubectl y la consola de Google Cloud usan este secreto a fin de autenticarse en el proveedor de OpenID.

  • Establece un permiso personalizado que el complemento de Anthos para Kubectl o la consola de Google Cloud puedan usar a fin de solicitar los grupos de seguridad del usuario.

  • Establecer un nombre de reclamación personalizado que el proveedor usará para mostrar los grupos de seguridad del usuario

La forma en la que realices estos pasos depende del proveedor de OpenID. Para obtener información sobre cómo realizar los pasos de registro con AD FS, consulta Autentica con OIDC y AD FS.

Propaga la especificación oidc en el archivo de configuración de GKE On-Prem

Esta sección está destinada a los administradores de clústeres.

Antes de crear un clúster de usuarios, debes generar un archivo de configuración de GKE On-Prem mediante gkectl create-config. La configuración incluye la siguiente especificación oidc. Debes propagar oidc con valores específicos de tu proveedor:

oidc:
  issuerurl:
  kubectlredirecturl:
  clientid:
  clientsecret:
  username:
  usernameprefix:
  group:
  groupprefix:
  scopes:
  extraparams:
  usehttpproxy:
  capath:
  • issuerurl: obligatorio. Es la URL del proveedor de OpenID, como "https://example.com/adfs". Las aplicaciones cliente, como el complemento de Anthos para Kubectl y la consola de Google Cloud, envían solicitudes de autorización a esta URL. El servidor de la API de Kubernetes usa esta URL a fin de descubrir claves públicas para la verificación de tokens. Debe usar HTTPS.
  • kubectlredirecturl: (Obligatorio). Es la URL de redireccionamiento configurada antes para el complemento de Anthos para Kubectl.
  • clientid: obligatorio. Es el ID de la aplicación cliente que realiza solicitudes de autenticación al proveedor de OpenID. Tanto el complemento de Anthos para Kubectl como la consola de Google Cloud usan este ID.
  • clientsecret: Opcional Es el secreto de la aplicación cliente. Tanto el complemento de Anthos para Kubectl como la consola de Google Cloud usan este secreto.
  • username: Opcional Es la reclamación de JWT que se debe usar como nombre de usuario. El valor predeterminado es sub, que se espera que sea un identificador único del usuario final. Puedes elegir otras reclamaciones, como email o name, en función del proveedor de OpenID. Sin embargo, a las reclamaciones que no sean email se les agrega el prefijo de la URL de la entidad emisora para evitar conflictos de nombres con otros complementos.
  • usernameprefix: Opcional. Es el prefijo que se antepone a las reclamaciones de nombre de usuario para evitar conflictos con los nombres existentes. Si no proporcionas este campo y username es un valor distinto de email, el prefijo se configurará de forma predeterminada como issuerurl#. Puedes usar el valor - para inhabilitar todos los prefijos.
  • group: Opcional Es la reclamación de JWT que el proveedor usará para mostrar los grupos de seguridad.
  • groupprefix: Opcional. Es el prefijo que se antepone a las reclamaciones de grupos para evitar conflictos con los nombres existentes. Por ejemplo, con un grupo foobar y un prefijo gid-, el valor es gid-foobar. De forma predeterminada, este valor se encuentra vacío y no tiene un prefijo.
  • scopes: Opcional. Son los permisos adicionales que se deben enviar al proveedor de OpenID como una lista separada por comas.
    • Para la autenticación con Okta o Microsoft Azure, pasa offline_access.

  • extraparams: Opcional. Son los parámetros adicionales de clave-valor que se deben enviar al proveedor de OpenID como una lista separada por comas.
  • usehttpproxy: Opcional Especifica si se debe implementar un proxy inverso en el clúster con el fin de permitir que Google Cloud Console acceda al proveedor de OIDC local para la autenticación de usuarios. El valor debe ser una string: "true" o "false". Si no se puede acceder al proveedor de identidad no a través de la Internet pública y deseas autenticarte mediante Google Cloud Console, este campo se debe configurar como "true". Si queda en blanco, el valor predeterminado de este campo es "false".

  • capath: Opcional. Es la ruta al certificado de la autoridad certificada (CA) que emitió el certificado web del proveedor de identidad. Es posible que este valor no sea necesario. Por ejemplo, si al certificado del proveedor de identidad lo emitió una CA pública conocida, no es necesario proporcionar un valor aquí. Sin embargo, si usehttpproxy es “true”, se debe proporcionar este valor, incluso en el caso de una CA pública conocida.

Ejemplo: Autoriza usuarios y grupos

Muchos proveedores codifican las propiedades de identificación de los usuarios, como el correo electrónico y los ID de usuario, en un token. Sin embargo, estas propiedades tienen riesgos implícitos para las políticas de autenticación:

  • Los ID de usuario pueden dificultar la lectura y la auditoría de las políticas.
  • Los correos electrónicos pueden generar un riesgo de disponibilidad (si un usuario cambia su correo electrónico principal) y un posible riesgo de seguridad (si se puede reasignar un correo electrónico).

Por lo tanto, se recomienda usar políticas de grupos, ya que el ID de un grupo puede ser persistente y más sencillo de auditar.

Supongamos que tu proveedor crea tokens de identidad en los que se incluyen los siguientes campos:

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  ...
}

En este formato de token, deberías propagar la especificación oidc del archivo de configuración de la siguiente manera:

issueruri: 'https://server.example.com'
username: 'sub'
usernameprefix: 'uid-'
group: 'groupList'
groupprefix: 'gid-'
extraparams: 'resource=token-groups-claim'
...

Después de crear el clúster de usuarios, podrías usar el control de acceso basado en funciones (RBAC) de Kubernetes para otorgar acceso con privilegios a los usuarios autenticados. Por ejemplo, podrías crear un ClusterRole que otorgue a sus usuarios acceso de solo lectura a los secretos del clúster y crear un recurso ClusterRoleBinding para vincular la función al grupo autenticado:

ClusterRole

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: secret-reader
rules:
- apiGroups: [""]
  # The resource type for which access is granted
  resources: ["secrets"]
  # The permissions granted by the ClusterRole
  verbs: ["get", "watch", "list"]

ClusterRoleBinding

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: read-secrets-admins
subjects:
  # Allows anyone in the "us-east1-cluster-admins" group to
  # read Secrets in any namespace within this cluster.
- kind: Group
  name: gid-us-east1-cluster-admins # Name is case sensitive
  apiGroup: rbac.authorization.k8s.io
  # Allows this specific user to read Secrets in any
  # namespace within this cluster
- kind: User
  name: uid-u98523-4509823
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: secret-reader
  apiGroup: rbac.authorization.k8s.io

Crea tu primer archivo de configuración de autenticación

Esta sección está destinada a los administradores de clústeres.

Después de crear un clúster de usuario, crea un archivo de configuración de autenticación para tu clúster:

gkectl create-login-config --kubeconfig [USER_CLUSTER_KUBECONFIG]

En el comando anterior, [USER_CLUSTER_KUBECONFIG] es la ruta de acceso del archivo kubeconfig del clúster de usuario. Cuando creaste tu clúster de usuario, gkectl create cluster generó un archivo kubeconfig para el clúster.

El comando anterior crea un archivo llamado kubectl-anthos-config.yaml en el directorio actual.

Agrega clústeres adicionales a tu archivo de configuración de autenticación

Esta sección está destinada a los administradores de clústeres.

Puedes almacenar la configuración de autenticación para varios clústeres en un solo archivo. Luego, puedes distribuir ese archivo a los desarrolladores que necesiten acceso a todos esos clústeres.

Comienza con un archivo de configuración de autenticación existente. Luego, usa el siguiente comando para combinar ese archivo con la configuración de un clúster adicional:

gkectl create-login-config --kubeconfig [USER_CLUSTER_KUBECONFIG] \
    --merge-from [IN_AUTH_CONFIG_FILE] --output [OUT_AUTH_CONFIG_FILE]

donde

  • [USER_CLUSTER_KUBECONFIG]es el archivo kubeconfig del clúster adicional.

  • [IN_AUTH_CONFIG_FILE] es la ruta del archivo de configuración de autenticación existente.

  • [OUT_AUTH_CONFIG_FILE] es la ruta de acceso en la que deseas guardar el archivo que contiene la configuración combinada. Puede ser igual que [IN_AUTH_CONFIG_FILE].

Distribuye el archivo de configuración de autenticación

Esta sección está destinada a los administradores de clústeres.

El archivo de configuración de autenticación que distribuyes a tus desarrolladores debe llamarse kubectl-anthos-config.yaml. Puedes distribuir el archivo de configuración de autenticación de varias maneras:

  • Proporciona el archivo de forma manual a cada desarrollador.

  • Aloja el archivo en una URL para que los desarrolladores puedan descargarlo.

  • Envía el archivo a la máquina de cada desarrollador.

Sin importar método de distribución, para una configuración predeterminada, el archivo de configuración de autenticación debe almacenarse en esta ubicación en la máquina de cada desarrollador:

Linux

$HOME/.config/google/anthos/kubectl-anthos-config.yaml

macOS

$HOME/Library/Preferences/google/anthos/kubectl-anthos-config.yaml

Windows

%APPDATA%\google\anthos\kubectl-anthos-config.yaml

Si no deseas usar la configuración predeterminada, puedes crear una configuración personalizada.

Ubica el archivo de configuración de autenticación

Esta sección está destinada a los desarrolladores.

El archivo de configuración de autenticación contiene los detalles de todos los clústeres a los que puedes autenticarte. No modifiques el contenido de este archivo.

Si el administrador de clústeres te proporcionó un archivo de configuración de autenticación, ubica el archivo en el directorio correcto. Si el administrador del clúster ya instaló la configuración en tu máquina, puedes omitir esta sección.

Copia el archivo de configuración de autenticación en su ubicación predeterminada:

Linux

mkdir -p  $HOME/.config/google/anthos/
cp [AUTH_CONFIG_FILE] $HOME/.config/google/anthos/kubectl-anthos-config.yaml

en el que [AUTH_CONFIG_FILE] es el nombre de tu archivo de configuración de autenticación.

macOS

mkdir -p  $HOME/Library/Preferences/google/anthos/
cp [AUTH_CONFIG_FILE] $HOME/Library/Preferences/google/anthos/kubectl-anthos-config.yaml

en el que [AUTH_CONFIG_FILE] es el nombre de tu archivo de configuración de autenticación.

Windows

md "%APPDATA%\google\anthos"
copy [AUTH_CONFIG_FILE] "%APPDATA%\google\anthos\kubectl-anthos-config.yaml"

En el ejemplo anterior, [AUTH_CONFIG_FILE] es el nombre del archivo de configuración de autenticación.

Obtén el complemento de Anthos para Kubectl

Esta sección está destinada a los administradores de clústeres.

El complemento de Anthos para Kubectl se incluye en tu estación de trabajo de administrador en:

Linux

/usr/bin/kubectl_anthos/v1.0beta/linux_amd64/kubectl-anthos

macOS

/usr/bin/kubectl_anthos/v1.0beta/darwin_amd64/kubectl-anthos

Windows

/usr/bin/kubectl_anthos/v1.0beta/windows_amd64/kubectl-anthos

Puedes distribuir el complemento a tus desarrolladores o hacer que descarguen el complemento directamente.

Descarga el complemento de Anthos para Kubectl

Esta sección es para administradores y desarrolladores de clústeres.

Cada desarrollador debe tener el complemento de Anthos para Kubectl en su propia máquina. Los desarrolladores pueden descargar el complemento de forma individual o el administrador de clústeres puede descargarlo y, luego, distribuirlo a los desarrolladores.

Nota para los desarrolladores: Pregúntale a tu administrador de clústeres qué versión del complemento debes usar.

Descarga el complemento de Anthos para Kubectl:

Linux

gsutil cp gs://gke-on-prem-release/kubectl-anthos/v1.0beta/linux_amd64/kubectl-anthos ./
chmod +x kubectl-anthos

macOS

gsutil cp gs://gke-on-prem-release/kubectl-anthos/v1.0beta/darwin_amd64/kubectl-anthos ./
chmod +x kubectl-anthos

Windows

gsutil cp gs://gke-on-prem-release/kubectl-anthos/v1.0beta/windows_amd64/kubectl-anthos ./
rename kubectl-anthos kubectl-anthos.exe.

Instala el complemento de Anthos para Kubectl

Esta sección está destinada a los desarrolladores.

El administrador de tu clúster puede proporcionarte el complemento de Anthos para Kubectl. También, es posible que el administrador de tu clúster te solicite descargar el complemento tú mismo.

Si deseas instalar el complemento de Anthos para Kubectl, mueve el archivo ejecutable a cualquier ubicación en tu RUTA. Para Linux y macOS, el archivo ejecutable debe llamarse kubectl-anthos. Para Windows, debe llamarse kubectl-anthos.exe. Para obtener más información, consulta Instala complementos de kubectl.

Verifica que esté instalado el complemento de Anthos para Kubectl:

kubectl plugin list
kubectl anthos version

Enumera los clústeres disponibles

Esta sección está destinada a los desarrolladores.

Si tu archivo de configuración de autenticación está en la ruta de acceso predeterminada, ingresa este comando para enumerar los clústeres en los que puedes autenticarte:

kubectl anthos listclusters

Si tu archivo de configuración de autenticación no está en la ruta predeterminada, ingresa este comando para enumerar los clústeres:

kubectl anthos listclusters --loginconfig [AUTH_CONFIG_FILE]

en el que [AUTH_CONFIG_FILE] es la ruta de acceso a tu archivo de configuración de autenticación.

Usa el complemento de Anthos para Kubectl a fin de autenticar

Esta sección está destinada a los desarrolladores.

Accede a un clúster de usuario:

kubectl anthos login --cluster [CLUSTER_NAME] --user [USER_NAME] \
     --loginconfig [AUTH_CONFIG_FILE] --kubeconfig [USER_CLUSTER_KUBECONFIG]

Donde:

  • [CLUSTER_NAME] es el nombre del clúster de usuario. Este nombre se debe seleccionarse de la lista que proporciona el comando kubectl anthos listclusters.

  • [USER_NAME] es un parámetro opcional que especifica el nombre de usuario para las credenciales almacenadas en el archivo kubeconfig. El valor predeterminado es [CLUSTER_NAME]-anthos-default-user.

  • [AUTH_CONFIG_FILE] es la ruta de tu archivo de configuración de autenticación. Si tu archivo de configuración de autenticación está en la ubicación predeterminda, puedes omitir este parámetro.

  • [USER_CLUSTER_KUBECONFIG] es la ruta de acceso del archivo kubeconfig de tu clúster de usuario. Si no existe un archivo kubeconfig, el comando genera un nuevo archivo kubeconfig a partir del archivo de configuración de autenticación y agrega los detalles del clúster y el archivo kubeconfig.

kubectl anthos login inicia un navegador en el que puedes ingresar tus credenciales.

El archivo kubeconfig proporcionado ahora contiene un token de ID que kubectl puede usar para autenticarse en el servidor de la API de Kubernetes en el clúster de usuarios.

El comando kubectl anthos login tiene una marca opcional --dry-run. Si incluyes la marca --dry-run, el comando imprime los comandos kubectl que agregarían tokens al archivo kubeconfig, pero en realidad no guarda los tokens en el archivo kubeconfig.

Ingresa un comando kubectl para verificar que la autenticación se realizó de forma correcta. Por ejemplo:

kubectl get nodes --kubeconfig [USER_CLUSTER_KUBECONFIG]

Usa OIDC con Google Cloud Console

Esta sección está destinada a los desarrolladores.

  1. Verifica que tu clúster esté configurado para OIDC.

  2. Verifica que tu clúster se haya registrado con Google Cloud, ya sea de forma automática durante la creación del clúster o de forma manual.

  3. Visita la página Clústeres de Kubernetes en la consola de Google Cloud.

    Visitar la página Clústeres de Kubernetes

  4. En la lista de clústeres, ubica tu clúster de GKE local y haz clic en Acceder.

  5. Selecciona Autenticar con el proveedor de identidad configurado para el clúster y haz clic en ACCEDER.

    Se te redireccionará al proveedor de identidad, en el que es posible que debas acceder u otorgar consentimiento a la consola de Google Cloud para que acceda a tu cuenta. Luego, se te redireccionará a la página Clústeres de Kubernetes en la consola de Google Cloud.

Configuración personalizada

De forma predeterminada, el complemento de Anthos para Kubectl espera que el archivo de configuración de autenticación esté en una ubicación determinada. Si no deseas colocar el archivo de configuración de autenticación en la ubicación predeterminada, puedes pasar de forma manual la ruta del archivo de configuración de autenticación a los comandos del complemento mediante la marca --login-config. Por ejemplo, consulta Usa el complemento de Anthos para Kubectl a fin de autenticar.

Soluciona problemas de OIDC en GKE On-Prem

La configuración no es válida

Si la consola de Google Cloud no puede leer la configuración de OIDC del clúster, el botón ACCEDER estará inhabilitado.

La configuración del proveedor no es válida

Si la configuración de tu proveedor de identidad no es válida, verás una pantalla de error del proveedor de identidad después de hacer clic en ACCEDER. Sigue las instrucciones específicas del proveedor para configurar correctamente el proveedor o el clúster.

Los permisos no son válidos

Si completas el flujo de autenticación, pero aún no ves los detalles del clúster, asegúrate de haber otorgado los permisos de RBAC correctos a la cuenta que usaste con OIDC. Ten en cuenta que esta cuenta podría ser diferente de la que usas para acceder a la consola de Google Cloud.

Error: missing 'RefreshToken' field in 'OAuth2Token' in credentials struct

Es posible que se genere este error si el servidor de autorización solicita el consentimiento, pero no se proporcionó el parámetro de autenticación requerido. Proporciona el parámetro prompt=consent en el campo oidc: extraparams del archivo de configuración de GKE On-Prem y vuelve a generar el archivo de autenticación del cliente con la marca --extra-params prompt=consent.