Consulta la documentación de una versión anterior de GKE On-Prem. Consulta la documentación más reciente.

Autenticación 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 obtener información sobre cómo usar OIDC con AD FS, consulta Cómo autenticar con OIDC y AD FS.

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

Resumen

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 crear, inhabilitar y habilitar cuentas de empleados.

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

  • Un empleado puede usar kubectl para iniciar un flujo OIDC. Para que este flujo sea automático, GKE On-Prem proporciona el complemento Kubectl para OIDC, un complemento kubectl.

  • Un empleado puede usar Google Cloud Console para iniciar un flujo de autenticación OIDC.

En este ejercicio, configurarás ambas opciones: kubectl y Cloud Console.

Antes de comenzar

En este tema, se supone que estás familiarizado con OAuth 2.0 y OpenID Connect. En este tema, se supone que estás familiarizado con los permisos y las reclamaciones de OpenID.

Elige un proveedor de OpenID

Esta sección es para administradores.

Puedes usar cualquier proveedor de OpenID que prefieras. Para obtener una lista de proveedores certificados, consulta Certificación de OpenID.

Una posibilidad es usar Servicios federados de Active Directory (AD FS) 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 Cómo autenticar con OIDC y AD FS.

Cómo descargar el complemento de Kubectl para OIDC

Esta sección está destinada a administradores y empleados que deseen usar el complemento de Kubectl para OIDC.

Descarga el complemento y configura los permisos de acceso:

Linux

gsutil cp gs://gke-on-prem-release/oidc-plugin/v1.1alpha/linux_amd64/kubectl-oidc .
chmod +x kubectl-oidc

Windows

gsutil cp gs://gke-on-prem-release/oidc-plugin/v1.1alpha/windows_amd64/kubectl-oidc .

macOS

gsutil cp gs://gke-on-prem-release/oidc-plugin/v1.1alpha/darwin_amd64/kubectl-oidc .
chmod +x kubectl-oidc

Instala el complemento

Para instalar el complemento, mueve el archivo ejecutable a cualquier ubicación en tu PATH. El archivo ejecutable debe llamarse kubectl-oidc. Para obtener más información, consulta Instala complementos de kubectl.

Cómo crear una URL de redireccionamiento para el complemento Kubectl para OIDC

Esta sección es para administradores.

Como parte del establecimiento de una relación con tu proveedor de OpenID, debes especificar una URL de redireccionamiento que el proveedor pueda usar para mostrar tokens de ID al complemento Kubectl para OIDC. El complemento de Kubectl para OIDC se ejecuta en la máquina local de cada empleado y escucha en un puerto de tu elección. Elige un número de puerto superior a 1024 que sea adecuado para este propósito. Luego, la URL de redireccionamiento es:

http://localhost:[PORT]/callback

donde [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 de tu proveedor.

Configura una URL de redireccionamiento para Cloud Console

Esta sección es para administradores.

Además de tener una URL de redireccionamiento para kubectl, necesitas una URL de redireccionamiento para Cloud Console. La URL de redireccionamiento de Cloud Console es:

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 de tu proveedor.

Registra las aplicaciones clientes con el proveedor de OpenID

Esta sección es para administradores.

Para que tus empleados puedan usar el complemento de Kubectl para OIDC o Cloud Console con tu proveedor de OpenID, debes registrar esos dos clientes con el proveedor de OpenID. El registro incluye estos pasos:

  • Saber el URI del emisor del proveedor. Aquí es donde el complemento de Kubectl para OIDC o Cloud Console envía solicitudes de autenticación.

  • Proporcionar al proveedor la URL de redireccionamiento del complemento de Kubectl para OIDC.

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

  • Establece un único ID de cliente. Este es el ID que el proveedor usa para identificar el complemento de Kubectl para OIDC y Cloud Console.

  • Establece un único secreto del cliente. El complemento de Kubectl para OIDC y Cloud Console usa este secreto para autenticarse en el proveedor de OpenID.

  • Establece un alcance personalizado que el complemento de Kubectl para OIDC o Cloud Console pueda usar a fin de solicitar los grupos de seguridad del usuario.

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

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

Cómo completar la especificación oidc en el archivo de configuración de GKE On-Prem

Esta sección es para los empleados que desean crear un clúster que esté configurado para usar OIDC.

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

oidc:
  issuerurl:
  clientid:
  clientsecret:
  username:
  usernameprefix:
  group:
  groupprefix:
  scopes:
  extraparams:
  usehttpproxy:
  capath:
  • issuerurl: obligatorio. URL de tu proveedor de OpenID, como https://example.com/adfs. Las aplicaciones cliente, como el complemento de Kubectl para OIDC y Cloud Console, 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 verificar tokens. Debes usar HTTPS.
  • clientid: obligatorio. ID de la aplicación cliente que realiza solicitudes de autenticación al proveedor de OpenID. El complemento Kubectl para OIDC y Cloud Console usa este ID.
  • clientsecret: Opcional Secreto para la aplicación cliente. El complemento Kubectl para OIDC y Cloud Console usa este secreto.
  • username: Opcional Reclamo de JWT para usar como nombre de usuario. El valor predeterminado es sub, que se espera que sea un identificador único del usuario final. Puedes elegir otros reclamos, como email o name, según el proveedor de OpenID. Sin embargo, los reclamos que no sean email tienen el prefijo de la URL del emisor para evitar conflictos de nombres con otros complementos.
  • usernameprefix: Opcional Prefijo de reclamaciones de nombre de usuario para evitar conflictos con nombres existentes. Si no proporcionas este campo y username es un valor distinto de email, el prefijo predeterminado es issuerurl#. Puedes usar el valor - para inhabilitar todos los prefijos.
  • group: Opcional Reclamación de JWT que el proveedor usará para mostrar tus grupos de seguridad.
  • groupprefix: Opcional Prefijo para agrupar reclamaciones a fin de evitar conflictos con nombres existentes. Por ejemplo, con un grupo foobar y un prefijo gid-, gid-foobar.
  • scopes: Opcional Alcances adicionales para enviar al proveedor de OpenID como una lista delimitada por comas.
  • extraparams: Opcional Parámetros de clave-valor adicionales para enviar al proveedor de OpenID como una lista delimitada por comas.
  • usehttpproxy: Opcional Especifica si se debe implementar un proxy inverso en el clúster para permitir que el agente de Connect acceda al proveedor de OIDC local para autenticar usuarios. El valor debe ser una string: "true" o "false".
  • capath: Opcional Ruta de acceso al certificado de la autoridad certificada (CA) que emitió el certificado web de tu proveedor de identidad. Es posible que este valor no sea necesario. Por ejemplo, si el certificado de tu proveedor de identidad fue emitido por una CA pública conocida, entonces no deberías proporcionar un valor aquí.

Ejemplo: Autorización de usuarios y grupos

Muchos proveedores codifican las propiedades de identificación del usuario, como los ID de correo electrónico y 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 hacer que las políticas sean difíciles de leer y auditar.
  • Los correos electrónicos pueden crear un riesgo de disponibilidad (si un usuario cambia su correo electrónico principal) y, potencialmente, un riesgo de seguridad (si se puede reasignar un correo electrónico).

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

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

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList: ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  ...
}
Dado este formato de token, propagarías la especificación oidc de tu 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 usuario, puedes usar el control de acceso basado en funciones (RBAC) de Kubernetes para otorgar acceso con privilegios a los usuarios autenticados. Por ejemplo, puedes 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

Cómo guardar el certificado de la CA del servidor de la API de Kubernetes

Esta sección es para los empleados que crearon un clúster de usuarios y ahora quieren usar el complemento Kubectl para OIDC.

Tu clúster de usuario tiene un servidor de API de Kubernetes. Y el archivo kubeconfig de tu clúster de usuario almacena el certificado de la CA que emitió un certificado al servidor de la API de Kubernetes. El certificado de CA es el valor codificado en base 64 del campo certificate-authority-data. Debes decodificar este valor y almacenarlo en un archivo local, como server-ca-cert:

cat [USER_CLUSTER_KUBECONFIG]  | grep certificate-authority-data | awk '{ print $2}' | base64 --decode > server-ca-cert

Genera el archivo de configuración de autenticación del cliente

Esta sección es para los empleados que crearon un clúster de usuarios y ahora quieren usar el complemento Kubectl para OIDC.

Para generar un archivo de configuración de autenticación de cliente, ingresa el siguiente comando:

Linux

kubectl oidc client-config \
--issuer-uri [ISSUER_URI] \
--redirect-uri [REDIRECT_URL] \
--client-id [CLIENT_ID] \
--client-secret [CLIENT_SECRET] \
--scopes "[CUSTOM_SCOPES]" \
--cluster-name [USER_CLUSTER_NAME] \
--server [CLUSTER_URL] \
--server-ca-file [SERVER_CA_CERT] \
--issuer-ca-file [PROVIDER_CA_CERT] \
--extra-params [KEY]=[VALUE], ... # e.g. --extra-params "resource=token-groups-claim"
> client-config.yaml

Donde:

  • [ISSUER_URI] es el URI del emisor.
  • [REDIRECT_URL] es la URL de redireccionamiento del complemento de Kubectl para OIDC.
  • [CLIENT_ID] es el ID de cliente del complemento de Kubectl para OIDC.
  • [CLIENT_SECRET] es el secreto del cliente para el complemento de Kubectl para OIDC.
  • [USER_CLUSTER_NAME] es el nombre de tu clúster de usuario.
  • [CLUSTER_URL] es la URL del servidor de la API de Kubernetes del clúster de usuario.
  • [SERVER_CA_FILE] es la ruta al certificado de la CA que emitió un certificado al servidor de la API de Kubernetes. Este es el archivo de certificado que creaste en la sección anterior.
  • [PROVIDER_CA_CERT] es la ruta de acceso al certificado de la CA que firmó el certificado del proveedor de OpenID. Esto es lo mismo que el valor de oidc:cacert en el archivo de configuración del clúster.
  • [CUSTOM_SCOPES] es la lista separada por comas de tus alcances personalizados para grupos de seguridad. Esto es lo mismo que el valor de oidc:scopes en el archivo de configuración del clúster.
  • --extra-params [KEY]=[VALUE], ... es una lista de pares clave-valor delimitados por comas que se incluirán en las solicitudes de autorización al proveedor de OpenID.

PowerShell

kubectl oidc client-config `
--issuer-uri [ISSUER_URI] `
--redirect-uri [REDIRECT_URL] `
--client-id [CLIENT_ID] `
--client-secret [CLIENT_SECRET] `
--scopes "[CUSTOM_SCOPES]" `
--cluster-name [USER_CLUSTER_NAME] `
--server [CLUSTER_URL] `
--server-ca-file [SERVER_CA_CERT] `
--issuer-ca-file [PROVIDER_CA_CERT] `
--extra-params [KEY]=[VALUE]
> client-config.yaml

Donde:

  • [ISSUER_URI] es el URI del emisor.
  • [REDIRECT_URL] es la URL de redireccionamiento del complemento de Kubectl para OIDC.
  • [CLIENT_ID] es el ID de cliente del complemento de Kubectl para OIDC.
  • [CLIENT_SECRET] es el secreto del cliente para el complemento de Kubectl para OIDC.
  • [USER_CLUSTER_NAME] es el nombre de tu clúster de usuario.
  • [CLUSTER_URL] es la URL del servidor de la API de Kubernetes del clúster de usuario.
  • [SERVER_CA_FILE] es la ruta al certificado de la CA que emitió un certificado al servidor de la API de Kubernetes. Este es el archivo de certificado que creaste en la sección anterior.
  • [PROVIDER_CA_CERT] es la ruta de acceso al certificado de la CA que firmó el certificado del proveedor de OpenID. Esto es lo mismo que el valor de oidc:cacert en el archivo de configuración del clúster.
  • [CUSTOM_SCOPES] es la lista separada por comas de tus alcances personalizados para grupos de seguridad. Esto es lo mismo que el valor de oidc:scopes en el archivo de configuración del clúster.
  • --extra-params [KEY]=[VALUE], ... es una lista de pares clave-valor delimitados por comas que se incluirán en las solicitudes de autorización al proveedor de OpenID.

Este comando produce un archivo de configuración de autenticación de cliente llamado client-config.yaml. No edites este archivo manualmente.

Autenticación en un clúster de usuario con el complemento de Kubectl para OIDC

Esta sección es para los empleados que crearon un clúster de usuarios y ahora quieren usar el complemento Kubectl para OIDC.

  1. Inicializa el complemento con el archivo client-config.yaml:

    kubectl oidc login --clientconfig-file=client-config.yaml --user [NAME] \
        --kubeconfig [KUBECONFIG_OUTPUT_PATH]

    Donde:

    • [NAME] es tu nombre de usuario.
    • [KUBECONFIG_OUTPUT_PATH] es la ruta al archivo kubeconfig donde almacenará las credenciales el complemento Kubectl para OIDC.

    kubectl oidc 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 del usuario.

    Nota: Es posible que los usuarios de Windows tengan que ejecutar el comando como kubectl-oidc.exe en lugar de kubectl oidc login.

  2. Ejecuta cualquier comando kubectl para verificar que la autenticación se realizó correctamente. Por ejemplo:

    kubectl get nodes --kubeconfig [KUBECONFIG_OUTPUT_PATH]

Cómo usar OIDC con Google Cloud Console

Esta sección es para los empleados que crearon un clúster de usuarios y ahora quieren usar Google Cloud Console para autenticarse en el clúster.

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

    Visitar la página Clústeres de Kubernetes

  4. En la lista de clústeres, ubica tu clúster de GKE On-Prem 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á a tu proveedor de identidad, donde es posible que debas acceder a tu cuenta o dar consentimiento a Cloud Console para que acceda a esta. Luego, se lo redireccionará a la página de clústeres de Kubernetes en Cloud Console.

Solución de problemas de OIDC en GKE On-Prem

La configuración no es válida

Si Cloud Console no puede leer la configuración de OIDC de tu 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 de tu proveedor de identidad después de hacer clic en ACCEDER. Sigue las instrucciones específicas del proveedor para configurar correctamente el proveedor o tu clúster.

Permisos no válidos

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

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

Es posible que aparezca 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 al 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.