Configura clústeres miembros de la flota para la autenticación de OIDC

En este documento, se describe cómo los administradores de clústeres o los operadores de aplicaciones pueden configurar clústeres para admitir la autenticación con un proveedor externo de OpenID Connect (OIDC).

Limitaciones

Debes usar un tipo de clúster que admita OIDC.

Antes de comenzar

1. Install the Google Cloud CLI.

2. Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

3. Para inicializar gcloud CLI, ejecuta el siguiente comando:

   gcloud init

4. Después de inicializar gcloud CLI, actualízala y, luego, instala los componentes necesarios:

   gcloud components update
   gcloud components install kubectl

5. Asegúrate de que el administrador de tu plataforma te haya proporcionado toda la información del proveedor que necesitas. Para obtener más información, consulta Cómo compartir los detalles del proveedor de identidad.
6. Para autenticarte con la consola de Google Cloud , registra cada clúster que desees configurar en la flota de tu proyecto. Para obtener más información, consulta Descripción general de la creación de flotas.
7. Para conectarte al plano de control de un clúster de AWS o Azure que está fuera de tu red de 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. Cuando ejecutes comandos de kubectl en este documento, anteponles HTTPS_PROXY=http://localhost:PORT, donde PORT es el número de puerto que usaste cuando iniciaste el túnel SSH.
8. En el caso de los clústeres de GKE en Google Cloud, regístralos en tu flota.

Configura los clústeres

Para configurar la autenticación en un clúster con OIDC, agrega la siguiente información a un recurso personalizado de Kubernetes llamado ClientConfig:

• Información sobre tu proveedor de identidad, como un ID de cliente y un secreto
• Es la información sobre los tokens web JSON (JWT) que usa tu proveedor de identidad para la autenticación.
• Cualquier parámetro o permiso adicional que sea exclusivo de tu proveedor de identidad

Para obtener más información sobre la información que necesitas del administrador de la plataforma o de quien administre la identidad en tu organización, consulta Comparte los detalles del proveedor de identidad.

El clúster usa los campos del recurso personalizado ClientConfig para interactuar con tu proveedor de identidad. Cada clúster tiene un ClientConfig llamado default en el espacio de nombres kube-public. Los campos específicos que modifiques dependerán de tu proveedor de identidad.

Para editar el ClientConfig de default, asegúrate de que puedes conectarte a tu clúster kubectl y, luego, 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 en el siguiente ejemplo. 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_AUTHORITY_DATA
      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.

Por ejemplo, considera los siguientes campos de token de identidad:

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['[e-mail]', '[e-mail]']
  # Multiple lines are omitted here
}

En este ejemplo, iss es el URI del proveedor de identidad, sub identifica al usuario y groupList enumera los grupos de seguridad a los que pertenece el usuario. En este ejemplo, solo se muestra una muestra de los campos que podría tener el token real.

Para el token de ejemplo anterior, actualiza los siguientes campos en el objeto spec.authentication.oidc de ClientConfig:

issuerURI: 'https://server.example.com'
userClaim: 'sub'
groupsClaim: 'groupList'
# Multiple lines are omitted here

Puedes agregar varias configuraciones de proveedores de identidad de OIDC, LDAP y SAML al mismo ClientConfig. El clúster intenta autenticarse con cada configuración en el orden en que se definen y se detiene después de la primera autenticación exitosa. El siguiente ejemplo de ClientConfig define varios proveedores de identidad en un orden específico:

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - aws:
      region: us-west-2
    name: AWS Login
  - ldap:
  # Multiple lines are omitted here.
  - saml:
  # Multiple lines are omitted here.
  - azureAD:
  # Multiple lines are omitted here.
  - oidc:
    name: Okta OIDC
  # Multiple lines are omitted here.
  - oidc:
    name: Google OIDC
  # Multiple lines are omitted here.

Campos de OIDC de ClientConfig

En la siguiente tabla, se describen los campos del objeto de ClientConfig oidc. Los campos que debes agregar dependen de los tokens de tu proveedor de identidad y de cómo el administrador de la plataforma configuró el proveedor.

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í	Es el ID de cliente del proveedor de identidad.	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 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 y no debe terminar con una barra.	String de URL
kubectlRedirectURI	Sí	La URL y el puerto de redireccionamiento que usa gcloud CLI y que especifica el administrador de la plataforma durante el registro, por lo general, en 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í, el valor predeterminado es “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, el clúster 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 editar tu ClientConfig, guarda el archivo para actualizar el ClientConfig de tu clúster. Si cometes algún error de sintaxis, verás un mensaje para corregir esos errores y guardar el archivo.

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.

Precaución: Debes usar el método estándar de OIDC o el método de Microsoft Entra ID (avanzado). No apliques ambos. Estas configuraciones son mutuamente excluyentes. Si intentas usar ambos complementos de forma simultánea, el complemento estándar de OIDC anulará el complemento de Microsoft Entra ID (avanzado), lo que provocará errores de autenticación para los usuarios con más de 200 membresías de grupo.

Microsoft Entra ID

Esta es la configuración predeterminada para configurar un clúster para la autenticación con Microsoft Entra ID. El uso de esta configuración permite que el clúster obtenga información de usuarios y sobre la pertenencia a grupos de Microsoft Entra ID, 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 Microsoft Entra ID (Advanced).

# Multiple lines are omitted here.
spec:
  authentication:
  - name: oidc-entraid
    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
# Multiple lines are omitted here. Do not modify any pre-filled data.

Reemplaza lo siguiente:

• CLIENT_ID: Es el ID de cliente de Microsoft Entra ID.
• CLIENT_SECRET: Secreto compartido entre la aplicación cliente de OIDC y el proveedor de OIDC.
• TENANT_ID: Es el tipo de cuenta de Microsoft Entra ID 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 Entra y el nombre de dominio principal.
• PORT: El número de puerto que se eligió para la URL de redireccionamiento que usa gcloud CLI, que especificó tu administrador de plataforma en el registro.

Microsoft Entra ID (avanzado)

Esta configuración opcional para Microsoft Entra ID permite que el clúster 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 las plataformas que admiten esta configuración, consulta Configuración avanzada para Microsoft Entra ID.

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 Microsoft Entra ID.

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

# Multiple lines are omitted here.
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
# Multiple lines are omitted here. Do not modify any pre-filled data.

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: Es el ID de cliente de Microsoft Entra ID.
• CLIENT_SECRET: Secreto compartido entre la aplicación cliente de OIDC y el proveedor de OIDC.
• TENANT: Es el tipo de cuenta de Microsoft Entra 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 Entra y el nombre de dominio principal.
• PORT: El número de puerto que se eligió para la URL de redireccionamiento que usa gcloud CLI, 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 este parámetro de configuración solo está disponible para clústeres en implementaciones de Google Distributed Cloud de equipos físicos.
• 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í, el clúster 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.

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 el clúster recupere reclamaciones de usuarios y grupos a través de un token de acceso y el extremo userinfo de Okta.

Nota: Si bien esta configuración es para Okta, también puedes recuperar información de usuarios y grupos de cualquier otro proveedor de identidad que admita un extremo userinfo. En la configuración, especifica enableAccessToken: true para usar esta función.

# Multiple lines are omitted here.
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
# Multiple lines are omitted here. Do not modify any pre-filled data.

Límites de acceso de grupos

En el caso de los usuarios de Okta, el clúster 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.