Configura clústeres para GKE Identity Service con OIDC

Este documento está dirigido a los administradores de clústeres o los operadores de aplicaciones que deseen configurar GKE Identity Service en clústeres individuales, lo que permite que los desarrolladores y otros usuarios accedan a los clústeres con sus detalles de identidad existentes desde un proveedor de OpenID Connect (OIDC). En la guía se supone que leíste la descripción general de GKE Identity Service.

Si deseas obtener información para configurar GKE Identity Service para un clúster con un proveedor de LDAP, consulta Configura GKE Identity Service con LDAP.
Si deseas obtener información para configurar GKE Identity Service a nivel de flota para tipos de clústeres compatibles con tu configuración de autenticación administrada por Google Cloud, consulta Configura GKE Identity Service para una flota.

En las instrucciones de este documento, se da por sentado que GKE Identity Service ya está registrado en tu proveedor de identidad como una aplicación cliente.

Descripción general de la configuración

La configuración de GKE Identity Service para un clúster individual implica los siguientes usuarios y pasos:

El administrador de la plataforma registra GKE Identity Service como una aplicación cliente con su proveedor de identidad preferido y obtiene un ID de cliente y un secreto. Para hacerlo, sigue las instrucciones en Configura proveedores para GKE Identity Service.
El administrador del clúster configura los clústeres para que usen el servicio y sigue las instrucciones de esta página.
El administrador del clúster configura el acceso de usuarios y, de forma opcional, configura el control de acceso basado en funciones (RBAC) de Kubernetes para los usuarios en los clústeres. Para hacerlo, sigue las instrucciones en Configura el acceso de usuarios a GKE Identity Service.

Requisitos previos

Tu clúster debe ser un clúster de GKE local (VMware o equipos físicos), en AWS o Azure. La configuración de OIDC por clúster no es compatible con clústeres conectados o clústeres de GKE.
Si quieres realizar la autenticación a través de la consola de Google Cloud, cada clúster que desees configurar para la autenticación de OIDC debe estar registrado en la flota de tu proyecto.

Antes de comenzar

Asegúrate de que el administrador de la plataforma te haya brindado toda la información necesaria de Registra Anthos Identity Service con tu proveedor antes de comenzar la configuración, incluido el ID de cliente y el secreto para GKE Identity Service.
Asegúrate de tener instaladas las siguientes herramientas de línea de comandos:
- La versión más reciente de Google Cloud CLI, que incluye gcloud, la herramienta de línea de comandos para interactuar con Google Cloud. Si necesitas instalar Google Cloud CLI, consulta la Guía de instalación.
- kubectl para ejecutar comandos en clústeres de Kubernetes. Si necesitas instalar kubectl, sigue estas instrucciones.
Si usas Cloud Shell como entorno de shell para interactuar con Google Cloud, estas herramientas están instaladas.
Asegúrate de haber inicializado la CLI de gcloud para usarla con el proyecto en el que se registran los clústeres.
Si necesitas conectarte al plano de control de un clúster de GKE de AWS o Azure que está fuera de la VPC actual a través de un host de bastión, asegúrate de haber creado el host de bastión y de iniciar un túnel SSH en el puerto 8118 antes de esta configuración. Luego, cuando sigas esta guía con HTTPS_PROXY=http://localhost:8118, antepone los comandos de kubectl. Si usaste un puerto diferente cuando iniciaste el túnel SSH, reemplaza 8118 por el puerto seleccionado.

Configura los clústeres

A fin de configurar los clústeres para que usen el proveedor seleccionado, GKE Identity Service necesita que especifiques detalles sobre el proveedor de identidad, la información en los tokens JWT que proporciona para la identificación de usuarios y otra información brindada cuando registras GKE Identity Service como una aplicación cliente.

Por ejemplo, si tu proveedor crea tokens de identidad con los siguientes campos (entre otros), en los que iss es el URI del proveedor de identidad, sub identifica al usuario y groupList enumera los grupos de seguridad que usuario pertenece a:

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

…tu configuración tendrá los siguientes campos correspondientes:

issuerURI: 'https://server.example.com'
userClaim: 'sub'
groupsClaim: 'groupList'
...

El administrador de la plataforma, o la persona que administre la identidad en tu organización, debería proporcionarte la mayor parte de la información que necesitas para crear la configuración.

GKE Identity Service usa un tipo de recurso personalizado (CRD) de Kubernetes llamado ClientConfig para la configuración del clúster, con campos para toda la información que necesita GKE Identity Service para interactuar con el proveedor de identidad. Cada clúster de GKE tiene un recurso ClientConfig llamado default en el espacio de nombres kube-public que se actualiza con los detalles de la configuración. Para ello, sigue las instrucciones que se indican a continuación.

Puedes ver algunos de los parámetros de configuración de ejemplo específicas para los proveedores populares en Configuración específica del proveedor.

kubectl

Para editar tu ClientConfig predeterminada, asegúrate de que puedes conectarte al clúster a través de kubectl y ejecuta el siguiente comando:

kubectl --kubeconfig=KUBECONFIG_PATH edit ClientConfigs default -n kube-public

Reemplaza KUBECONFIG_PATH por la ruta de acceso al archivo kubeconfig de tu clúster, por ejemplo $HOME/.kube/config.

Un editor de texto carga el recurso ClientConfig de tu clúster. Agrega el objeto spec.authentication.oidc como se muestra a continuación. No modifiques ningún dato predeterminado que ya se haya escrito.

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - name: NAME
    oidc:
      certificateAuthorityData: CERTIFICATE_STRING
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      deployCloudConsoleProxy: PROXY_BOOLEAN
      extraParams: EXTRA_PARAMS
      groupsClaim: GROUPS_CLAIM
      groupPrefix: GROUP_PREFIX
      issuerURI: ISSUER_URI
      kubectlRedirectURI: KUBECTL_REDIRECT_URI
      scopes: SCOPES
      userClaim: USER_CLAIM
      userPrefix: USER_PREFIX
      enableAccessToken: ENABLE_ACCESS_TOKEN
    proxy: PROXY_URL

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

En la siguiente tabla, se describen los campos del objeto de ClientConfig oidc. La mayoría de los campos son opcionales. Los campos que debes agregar dependen de tu proveedor de identidad y las opciones de configuración que elige el administrador de la plataforma cuando configuras el proveedor de GKE Identity Service.

Campo	Obligatorio	Descripción	Formato
nombre	sí	El nombre que deseas usar para identificar esta configuración, que suele ser el nombre del proveedor de identidad. El nombre de configuración debe comenzar con una letra minúscula seguida con un máximo de 39 letras minúsculas, números o guiones, y no puede terminar con un guion.	String
certificateAuthorityData	No	Si el administrador de la plataforma lo proporciona, una string de certificado con codificación PEM para el proveedor de identidad. Incluye la string resultante en `certificateAuthorityData` como una sola línea.	String
clientID	Sí	El ID de cliente que se muestra cuando registras GKE Identity Service con tu proveedor de OIDC.	String
clientSecret	No	Secreto compartido entre la aplicación cliente de OIDC y el proveedor de OIDC	String
deployCloudConsoleProxy	No	Especifica si se implementa un proxy que permite que la consola de Google Cloud se conecte a un proveedor de identidad local al que no se puede acceder públicamente a través de Internet. El valor predeterminado es de `false`.	Booleano
extraParams	No	Parámetros clave=valor adicionales para enviar al proveedor de identidad, especificado como una lista separada por comas, por ejemplo, “prompt=consent,access_type=offline”.	Lista delimitada por comas
groupsClaim	No	La reclamación de JWT (nombre de campo) que usa tu proveedor para mostrar los grupos de seguridad de una cuenta.	String
groupPrefix	No	El prefijo que quieres anteponer a los nombres de los grupos de seguridad para evitar conflictos con los nombres existentes en las reglas de control de acceso si tienes configuraciones para varios proveedores de identidad (por lo general, el nombre del proveedor).	String
issuerURI	Sí	El URI en el que se realizan las solicitudes de autorización al proveedor de identidad. El URI debe usar HTTPS.	String de URL
kubectlRedirectURI	Sí	La URL y el puerto de redireccionamiento que usa la CLI de gcloud, y que especifica tu administrador de la plataforma durante el registro; suelen tener el formato “http://localhost:PORT/callback”.	String de URL
scopes	Sí	Los permisos adicionales que se deben enviar al proveedor de OpenID. Por ejemplo, Okta y Microsoft Azure requieren el permiso `offline_access`.	Lista delimitada por comas
userClaim	No	La reclamación de JWT (nombre de campo) que usa tu proveedor para identificar una cuenta de usuario. Si no especificas un valor aquí, GKE Identity Service usa “sub”, que es la reclamación de ID de usuario que usan muchos proveedores. Puedes elegir otras reclamaciones, como “correo electrónico” o “nombre”, según el proveedor de OpenID. Las reclamaciones que no sean “correo electrónico” tienen el prefijo de la URL de la entidad emisora para evitar conflictos de nombres.	String
userPrefix	No	El prefijo que deseas anteponer a las reclamaciones de los usuarios para evitar conflictos con los nombres existentes, si no deseas usar el prefijo predeterminado.	String
enableAccessToken	No	Si se habilita, GKE Identity Service puede usar el extremo userinfo del proveedor de identidad para obtener información de los grupos cuando un usuario accede desde la línea de comandos. Esto te permite usar grupos de seguridad para autorización si tienes un proveedor (como Okta) que proporcione reclamaciones de grupos desde este extremo. Si no la estableces, se considerará `false`.	Booleano
proxy	No	Dirección del servidor proxy que se usará para conectarse al proveedor de identidad, si corresponde. Es posible que debas configurarlo si, por ejemplo, tu clúster está en una red privada y necesita conectarse a un proveedor de identidad pública. Por ejemplo: `http://user:password@10.10.10.10:8888`.	String

Después de completar tu ClientConfig, guarda el archivo, que actualiza el ClientConfig en tu clúster. Si se producen errores de sintaxis, se te solicitará que vuelvas a editar la configuración para solucionarlos.

Parámetros de configuración específica del proveedor

En esta sección, se proporciona orientación de configuración para algunos proveedores de OIDC populares, incluidas opciones de configuración de ejemplo que puedes copiar y editar con tus propios detalles.

Azure AD

Esta es la configuración predeterminada para configurar GKE Identity Service con Azure AD. El uso de esta configuración permite que GKE Identity Service obtenga información de usuarios y sobre la pertenencia a grupos de Azure AD, y te permite configurar el control de acceso basado en roles (RBAC) de Kubernetes en función de los grupos. Sin embargo, el uso de esta configuración limita la recuperación de alrededor de 200 grupos por usuario.

Si necesitas recuperar más de 200 grupos por usuario, consulta las instrucciones de Azure AD (Advanced).

...
spec:
  authentication:
  - name: oidc-azuread
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      extraParams: prompt=consent, access_type=offline
      issuerURI: https://login.microsoftonline.com/TENANT_ID/v2.0
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: openid,email,offline_access
      userClaim: email

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

Reemplaza lo siguiente:

CLIENT_ID: El ID de cliente que se muestra cuando registras GKE Identity Service con tu proveedor.
CLIENT_SECRET: Secreto compartido entre la aplicación cliente de OIDC y el proveedor de OIDC.
TENANT: El tipo de cuenta de Azure AD que se autenticará. Los valores admitidos son el ID del usuario o su nombre para las cuentas que pertenecen a una instancia específica. El nombre del usuario también se conoce como dominio principal. Para obtener detalles sobre cómo encontrar estos valores, consulta Encuentra el ID de usuario de Microsoft Azure AD y el nombre de dominio principal.
PORT: El número de puerto que se eligió para la URL de redireccionamiento que usa la CLI de gcloud, que especificó tu administrador de plataforma en el registro.

Azure AD (Advanced)

Esta configuración opcional para Azure AD permite que GKE Identity Service recupere información de usuarios y grupos sin límite en la cantidad de grupos por usuario a través de la API de Microsoft Graph.

Si deseas obtener información sobre plataformas que admiten esta configuración, consulta Configuración avanzada para Azure AD.

Si necesitas recuperar menos de 200 grupos por usuario, te recomendamos que uses la configuración predeterminada con un ancla oidc en tu ClientConfig. Si deseas obtener más información, consulta las instrucciones para Azure AD.

Todos los campos de la siguiente configuración de ejemplo son obligatorios.

...
spec:
  authentication:
  - name: NAME
    proxy: PROXY_URL
    azureAD:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      tenant: TENANT_ID
      kubectlRedirectURI: http://localhost:PORT/callback
      groupFormat: GROUP_FORMAT
      userClaim: USER_CLAIM

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

Reemplaza lo siguiente:

NAME: El nombre que deseas usar para identificar esta configuración, que suele ser el nombre del proveedor de identidad. El nombre de configuración debe comenzar con una letra minúscula seguida con un máximo de 39 letras minúsculas, números o guiones, y no puede terminar con un guion.
PROXY_URL: Dirección del servidor proxy que se usará para conectarse al proveedor de identidad, si corresponde. Es posible que debas configurarlo si, por ejemplo, tu clúster está en una red privada y necesita conectarse a un proveedor de identidad pública. Por ejemplo: http://user:password@10.10.10.10:8888.
CLIENT_ID: El ID de cliente que se muestra cuando registras GKE Identity Service con tu proveedor.
CLIENT_SECRET: Secreto compartido entre la aplicación cliente de OIDC y el proveedor de OIDC.
TENANT: El tipo de cuenta de Azure AD que se autenticará. Los valores admitidos son el ID del usuario o su nombre para las cuentas que pertenecen a una instancia específica. El nombre del usuario también se conoce como dominio principal. Para obtener detalles sobre cómo encontrar estos valores, consulta Encuentra el ID de usuario de Microsoft Azure AD y el nombre de dominio principal.
PORT: El número de puerto que se eligió para la URL de redireccionamiento que usa la CLI de gcloud, que especificó tu administrador de plataforma en el registro.
GROUP_FORMAT: El formato en el que deseas recuperar la información del grupo. Este campo puede tener valores correspondientes a ID o NAME de los grupos de usuarios. Ten en cuenta que, por el momento, esta configuración solo está disponible para Google Distributed Cloud Virtual para clústeres de Bare Metal.
USER_CLAIM (opcional): La reclamación de JWT (nombre de campo) que usa tu proveedor para identificar una cuenta. Si no especificas un valor aquí, GKE Identity Service usa un valor en el orden de "email", "preferred_username" o "sub" para recuperar los detalles del usuario. Este atributo se puede usar a partir de la versión 1.28 de GKE Enterprise.

Okta

En el siguiente ejemplo, se muestra cómo configurar la autenticación mediante usuarios y grupos con Okta como proveedor de identidad. Esta configuración permite que Anthos Identity Service recupere reclamaciones de usuarios y grupos mediante un token de acceso y el extremo userinfo de Okta.

...
spec:
  authentication:
  - name: okta
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      enableAccessToken: true
      extraParams: prompt=consent
      groupsClaim: groups
      issuerURI: https://OKTA_ISSUER_URI/
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: offline_access,email,profile,groups
      userClaim: email

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

Límites de acceso de grupos

En el caso de los usuarios de Okta, Anthos Identity Service puede recuperar información de grupo para usuarios cuyos nombres de grupo, si se concatenan, tienen una longitud inferior a 170,000 caracteres. Esto corresponde a una membresía de alrededor de 650 grupos, según la longitud máxima del grupo de Okta. Si el usuario es miembro de demasiados grupos, la llamada de autenticación falla.

Próximos pasos

Después de aplicar la configuración, continúa con la configuración del acceso de los usuarios a los clústeres.