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

En este documento se describe cómo pueden configurar los clústeres los administradores de clústeres o los operadores de aplicaciones para que admitan la autenticación mediante un proveedor de OpenID Connect (OIDC) de terceros.

Limitaciones

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

Antes de empezar

1. Install the Google Cloud CLI.

2. Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

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

   gcloud init

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

   gcloud components update
   gcloud components install kubectl

5. Asegúrate de que el administrador de tu plataforma te ha proporcionado toda la información que necesitas sobre el proveedor. Para obtener más información, consulta Compartir los detalles del proveedor de identidades.
6. Para autenticarte mediante la consola, registra cada clúster que quieras configurar en tu flota de proyectos. Google Cloud Para obtener más información, consulta la 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 bastion, asegúrate de haber creado el host bastion y de haber iniciado un túnel SSH en el puerto 8118. Cuando ejecutes comandos kubectl en este documento, añade HTTPS_PROXY=http://localhost:PORT delante de los comandos, donde PORT es el número de puerto que has usado al iniciar el túnel SSH.
8. En el caso de los clústeres de GKE en Google Cloud, registra los clústeres en tu flota.

Configurar clústeres

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

• Información sobre tu proveedor de identidades, como un ID de cliente y un secreto.
• Información sobre los JSON Web Tokens (JWTs) que usa tu proveedor de identidades para la autenticación.
• Cualquier ámbito o parámetro adicional que sea único para tu proveedor de identidades.

Para obtener más información sobre la información que necesitas del administrador de tu plataforma o de la persona que gestione la identidad en tu organización, consulta Compartir los detalles del proveedor de identidades.

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

Para editar el default ClientConfig, asegúrate de que puedes conectarte a tu clúster kubectl y, a continuación, 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 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 identidades, sub identifica al usuario y groupList muestra los grupos de seguridad a los que pertenece el usuario. En este ejemplo solo se muestra una muestra de los campos que puede tener el token real.

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

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

Puedes añadir varias configuraciones de proveedor de identidades 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 correcta. En el siguiente ejemplo de ClientConfig se definen 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 OIDC de ClientConfig

En la siguiente tabla se describen los campos del objeto ClientConfig oidc. Los campos que debes añadir dependen de los tokens de tu proveedor de identidades y de cómo haya configurado el proveedor el administrador de tu plataforma.

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 del proveedor de identidades.	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 enviarán 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 al registrarse, normalmente con 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 especifica ningún valor, el valor predeterminado es "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 se habilita, el clúster 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

Después de editar ClientConfig, guarda el archivo para actualizar ClientConfig en tu clúster. Si cometes algún error de sintaxis, verás un mensaje para corregirlo y guardar el archivo.

Configuraciones específicas de proveedores

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

Precaución: Debes usar el método estándar de OIDC o el de Microsoft Entra ID (avanzado). No apliques ambos. Estas configuraciones se excluyen mutuamente. Si se intenta usar ambos simultáneamente, el complemento estándar de OIDC anula el complemento de Microsoft Entra ID (avanzado), lo que provoca errores de autenticación para los usuarios con más de 200 miembros en grupos.

ID de Microsoft Entra

Esta es la configuración predeterminada para configurar un clúster para la autenticación con Microsoft Entra ID. Con esta configuración, el clúster puede obtener información sobre la pertenencia de usuarios y grupos de Microsoft Entra ID, 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 obtener más de 200 grupos por usuario, consulta las instrucciones de Microsoft Entra ID (avanzado).

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

Haz los cambios siguientes:

• CLIENT_ID: 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: el tipo de cuenta de Microsoft Entra ID 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 Entra.
• 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.

ID de Microsoft Entra (avanzado)

Esta configuración opcional de Microsoft Entra ID permite que el clúster 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 Microsoft Entra ID.

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

Todos los campos de la siguiente configuración de 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.

Haz los cambios siguientes:

• NAME: el nombre que quieras usar para identificar esta configuración. Normalmente, es 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 de Microsoft Entra ID.
• CLIENT_SECRET: secreto compartido entre la aplicación cliente de OIDC y el proveedor de OIDC.
• TENANT: el tipo de cuenta de Microsoft Entra 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 Entra.
• PORT: 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 de 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, el clúster 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.

Okta

A continuación, se muestra cómo configurar la autenticación con usuarios y grupos con Okta como proveedor de identidades. Esta configuración permite que el clúster obtenga 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.

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

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