Configurar clústeres para GKE Identity Service con OIDC

Este documento está dirigido a administradores de clústeres u operadores de aplicaciones que quieran configurar GKE Identity Service en clústeres individuales para que los desarrolladores y otros usuarios puedan iniciar sesión en los clústeres con sus credenciales de un proveedor de OpenID Connect (OIDC).

Requisitos previos

• Tu clúster debe ser un clúster de GKE on-premise (VMware o Bare Metal), en AWS o en Azure. No se admite la configuración de OIDC por clúster en clústeres adjuntos ni en clústeres de GKE.
• Para autenticarte a través de la consola de Google Cloud , cada clúster que quieras configurar para la autenticación OIDC debe estar registrado en tu flota de proyectos.

Antes de empezar

• Antes de empezar la configuración, asegúrate de que el administrador de tu plataforma te haya proporcionado toda la información necesaria de Registrar el servicio de identidad de GKE con tu proveedor, incluido el ID y el secreto de cliente del servicio de identidad de GKE.

• Asegúrate de que tienes instaladas las siguientes herramientas de línea de comandos:

  • La versión más reciente de la CLI de Google Cloud, 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 ya están instaladas.

• Asegúrate de haber inicializado la CLI de gcloud para usarla con el proyecto en el que están registrados los clústeres.

• Si necesitas conectarte al plano de control de un clúster de GKE de AWS o Azure que esté fuera de tu VPC actual a través de un host bastion, asegúrate de haber creado el host bastion e iniciado un túnel SSH en el puerto 8118 antes de esta configuración. A continuación, antepón HTTPS_PROXY=http://localhost:8118 a los comandos kubectl cuando sigas esta guía. Si has usado otro puerto al iniciar el túnel SSH, sustituye 8118 por el puerto que hayas seleccionado.

Configurar clústeres

Para configurar tus clústeres de forma que usen el proveedor que elijas, GKE Identity Service necesita que especifiques detalles sobre el proveedor de identidades, la información de los tokens JWT que proporciona para identificar a los usuarios y otra información que se proporciona al registrar GKE Identity Service como aplicación cliente.

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

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['[e-mail]', '[e-mail]']
  ...
}

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

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

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

El servicio de identidad de GKE 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 el servicio de identidad de GKE para interactuar con el proveedor de identidades. Cada clúster de GKE tiene un recurso ClientConfig llamado default en el espacio de nombres kube-public que debes actualizar con los detalles de tu configuración siguiendo las instrucciones que se indican a continuación.

Puedes ver algunas configuraciones de ejemplo específicas para proveedores populares en Configuraciones específicas de proveedores.

kubectl

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

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

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

Un editor de texto carga el recurso ClientConfig de tu clúster. Añade 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.
...

Nota: GKE Identity Service te permite configurar varios proveedores de identidades OIDC, LDAP y SAML en un solo ClientConfig recurso personalizado (CRD) para la autenticación de clientes. GKE Identity Service intenta autenticarse con cada CRD en el orden en que se definen y se detiene después de la primera autenticación correcta.

Puedes configurar varios proveedores de identidades en tu ClientConfig según tus requisitos. De esta forma, se simplifica la gestión y se ofrece flexibilidad, ya que puedes configurar diversos métodos de autenticación en un recurso de configuración unificado. En el siguiente ejemplo ClientConfig se definen varios proveedores de identidad en el orden de precedencia de autenticación requerido.

apiVersion: v1
items:
- apiVersion: authentication.gke.io/v2alpha1
  kind: ClientConfig
...
  spec:
    authentication:
    - aws:
        region: us-west-2
      name: AWS Login
    - ldap:
    ...
    - saml:
      ...
    - azureAD:
      ...
    - oidc:
      name: Okta OIDC
      ...
    -oidc:
      name: Google OIDC
      ...

En la siguiente tabla se describen los campos del objeto ClientConfig oidc. La mayoría de los campos son opcionales. Los campos que debes añadir dependen de tu proveedor de identidades y de las opciones de configuración que haya elegido el administrador de tu plataforma al configurar el proveedor para el servicio de identidad de GKE.

Campo	Obligatorio	Descripción	Formato
name	yes	El nombre que quieras usar para identificar esta configuración, normalmente el nombre del proveedor de identidades. El nombre de una configuración debe empezar por una letra, seguida de un máximo de 39 letras minúsculas, números o guiones, y no puede acabar en guion.	Cadena
certificateAuthorityData	No	Si el administrador de la plataforma lo proporciona, una cadena de certificado codificada en PEM para el proveedor de identidades. Incluye la cadena resultante en certificateAuthorityData como una sola línea.	Cadena
clientID	Sí	El ID de cliente devuelto al registrar Identity Service para GKE con tu proveedor de OIDC.	Cadena
clientSecret	No	Secreto compartido entre la aplicación cliente de OIDC y el proveedor de OIDC.	Cadena
deployCloudConsoleProxy	No	Especifica si se ha implementado un proxy que permite que la consola se conecte a un proveedor de identidades local al que no se puede acceder públicamente a través de Internet. Google Cloud De forma predeterminada, esta opción está definida en false.	Booleano
extraParams	No	Parámetros clave=valor adicionales que se envían al proveedor de identidades, especificados como una lista separada por comas (por ejemplo, `prompt=consent,access_type=offline`).	Lista delimitada por comas
groupsClaim	No	La reclamación JWT (nombre del campo) que usa tu proveedor para devolver los grupos de seguridad de una cuenta.	Cadena
groupPrefix	No	El prefijo que quieres añadir a los nombres de los grupos de seguridad para evitar conflictos con los nombres de las reglas de control de acceso si tienes configuraciones para varios proveedores de identidades (normalmente, el nombre del proveedor).	Cadena
issuerURI	Sí	El URI en el que se realizan las solicitudes de autorización a tu proveedor de identidades. El URI debe usar HTTPS y no debe terminar con una barra inclinada.	URL String
kubectlRedirectURI	Sí	La URL de redirección y el puerto que usa gcloud CLI y que especifica el administrador de tu plataforma durante el registro. Normalmente, tiene el formato http://localhost:PORT/callback.	URL String
permisos	Sí	Permisos adicionales que se enviarán al proveedor de OpenID. Por ejemplo, Microsoft Azure y Okta requieren el ámbito offline_access.	Lista delimitada por comas
userClaim	No	La reclamación JWT (nombre del campo) que usa tu proveedor para identificar una cuenta de usuario. Si no especificas ningún valor, GKE Identity Service usará "sub", que es la reclamación de ID de usuario que usan muchos proveedores. Puedes elegir otras reclamaciones, como "email" o "name", en función del proveedor de OpenID. Las reclamaciones que no sean "email" tienen el prefijo de la URL del emisor para evitar conflictos de nombres.	Cadena
userPrefix	No	El prefijo que quieres que se añada a las reclamaciones de usuario para evitar conflictos con los nombres ya existentes, si no quieres usar el prefijo predeterminado.	Cadena
enableAccessToken	No	Si está habilitado, el servicio de identidad de GKE puede usar el endpoint userinfo del proveedor de identidades para obtener información de los grupos cuando un usuario inicia sesión desde la línea de comandos. De esta forma, puedes usar grupos de seguridad para la autorización si tienes un proveedor (como Okta) que proporcione reclamaciones de grupos desde este endpoint. Si no se define, se considera que es false.	Booleano
proxy	No	Dirección del servidor proxy que se va a usar para conectarse al proveedor de identidades, si procede. Puede que tengas que definirlo si, por ejemplo, tu clúster está en una red privada y necesita conectarse a un proveedor de identidades público. Por ejemplo: http://user:password@10.10.10.10:8888.	Cadena

Una vez que hayas completado el archivo ClientConfig, guárdalo para que se actualice en tu clúster. Si cometes algún error de sintaxis, se te pedirá que vuelvas a editar la configuración para corregirlo.

Configuraciones específicas de proveedores

En esta sección se ofrecen directrices de configuración para algunos proveedores de OIDC populares, incluidas configuraciones de ejemplo que puede copiar y editar con sus propios detalles.

Precaución: Debes usar el método OIDC estándar o el de Azure AD (avanzado). No apliques ambos. Estas configuraciones se excluyen mutuamente. Si se intenta usar ambos simultáneamente, el complemento estándar de OIDC anulará el complemento de Azure AD (avanzado), lo que provocará errores de autenticación para los usuarios con más de 200 suscripciones a grupos.

Azure AD

Esta es la configuración predeterminada para configurar GKE Identity Service con Azure AD. Con esta configuración, GKE Identity Service puede obtener información sobre la pertenencia de usuarios y grupos de Azure AD, y puedes configurar el control de acceso basado en roles (RBAC) de Kubernetes en función de los grupos. Sin embargo, si usas esta configuración, solo podrás recuperar unos 200 grupos por usuario.

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

...
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.
...

Haz los cambios siguientes:

• CLIENT_ID: el ID de cliente devuelto al registrar el servicio de identidad de GKE 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 va a autenticar. Los valores admitidos son el ID de arrendatario o el nombre de arrendatario de las cuentas que pertenecen a un arrendatario específico. El nombre de inquilino también se conoce como dominio principal. Para obtener información sobre cómo encontrar estos valores, consulta Buscar el ID de cliente y el nombre de dominio principal de Microsoft Azure AD.
• PORT: el número de puerto elegido para la URL de redirección que usa la CLI de gcloud, especificado por el administrador de tu plataforma durante el registro.

Azure AD (avanzado)

Esta configuración opcional de Azure AD permite que GKE Identity Service obtenga información de usuarios y grupos sin límite en el número de grupos por usuario mediante la API Microsoft Graph.

Para obtener información sobre las plataformas que admiten esta configuración, consulta Configuración avanzada de Azure AD.

Si necesitas recuperar menos de 200 grupos por usuario, te recomendamos que uses la configuración predeterminada con un oidc en tu ClientConfig. Para obtener más información, consulta las instrucciones de 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.
...

Haz los cambios siguientes:

• NAME: el nombre que quieras usar para identificar esta configuración, normalmente el nombre del proveedor de identidades. El nombre de una configuración debe empezar por una letra, seguida de un máximo de 39 letras minúsculas, números o guiones, y no puede acabar en guion.
• PROXY_URL: dirección del servidor proxy que se usará para conectarse al proveedor de identidades, si procede. Puede que tengas que definirlo si, por ejemplo, tu clúster está en una red privada y necesita conectarse a un proveedor de identidades público. Por ejemplo: http://user:password@10.10.10.10:8888.
• CLIENT_ID: el ID de cliente devuelto al registrar el servicio de identidad de GKE 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 va a autenticar. Los valores admitidos son el ID de arrendatario o el nombre de arrendatario de las cuentas que pertenecen a un arrendatario específico. El nombre del arrendatario también se conoce como dominio principal. Para obtener información sobre cómo encontrar estos valores, consulta Buscar el ID de cliente y el nombre de dominio principal de Microsoft Azure AD.
• PORT: el número de puerto elegido para la URL de redirección que usa la CLI de gcloud, especificado por el administrador de tu plataforma durante el registro.
• GROUP_FORMAT: el formato en el que quieres obtener la información del grupo. Este campo puede tomar valores correspondientes a ID o NAME de los grupos de usuarios. Ten en cuenta que este ajuste solo está disponible para clústeres en implementaciones de Google Distributed Cloud en hardware desnudo.
• USER_CLAIM (Opcional): la reclamación JWT (nombre del campo) que usa tu proveedor para identificar una cuenta. Si no especifica ningún valor, GKE Identity Service usará un valor en el orden "email", "preferred_username" o "sub" para obtener los detalles del usuario. Este atributo se puede usar a partir de la versión 1.28 de GKE Enterprise.

Okta

A continuación, se explica cómo configurar la autenticación con usuarios y grupos mediante Okta como proveedor de identidades. Esta configuración permite que Anthos Identity Service recupere las reclamaciones de usuarios y grupos mediante un token de acceso y el endpoint userinfo de Okta.

Nota: Aunque esta configuración es para Okta, también puede obtener información de usuarios y grupos de cualquier otro proveedor de identidades que admita un endpoint userinfo. En tu archivo de configuración, especifica enableAccessToken: true para usar esta función.

...
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 a grupos

En el caso de los usuarios de Okta, Anthos Identity Service puede obtener información de los grupos de usuarios cuyos nombres de grupo, si se concatenan, tengan una longitud inferior a 170.000 caracteres. Esto corresponde a una pertenencia de aproximadamente 650 grupos, dada la longitud máxima de los grupos de Okta. Si el usuario pertenece a demasiados grupos, la llamada de autenticación falla.

Siguientes pasos

Una vez que se haya aplicado la configuración, configura el acceso de los usuarios a los clústeres.