Autentica 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 aprender a usar OIDC con AD FS, consulta Autentica con OIDC y AD FS.

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

Descripción general

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 la creación, inhabilitación y habilitación de cuentas de empleado.

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

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

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

En este ejercicio, configurarás ambas opciones: kubectl y la consola de Google Cloud.

Antes de comenzar

En este tema suponemos que estás familiarizado con OAuth 2.0 y OpenID Connect. En este tema suponemos que estás familiarizado con los alcances de OpenID y las reclamaciones.

Elige un proveedor de OpenID

Esta sección está destinada a los administradores.

Puedes usar el proveedor de OpenID que desees. Para ver una lista de proveedores certificados, consulta OpenID Certification (Certificación de OpenID).

Una posibilidad es usar Active Directory Federated Services (AD FS) (Servicios federados de Active Directory) 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 Autenticar con OIDC y AD FS.

Descarga el complemento de Kubectl para OIDC

Esta sección es para administradores y empleados que desean 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.

Crea una URL de redireccionamiento del complemento de Kubectl para OIDC

Esta sección está destinada a los 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 a fin de mostrar tokens de ID al complemento de Kubectl para OIDC. El complemento de Kubectl para OIDC se ejecuta en la máquina local de cada empleado y escucha en el puerto que elijas. Elige un número de puerto mayor que 1,024 que sea adecuado para este propósito. A continuación, se muestra la URL de redireccionamiento:

http://localhost:[PORT]/callback

en el que [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 del proveedor.

Configura una URL de redireccionamiento para la consola de Google Cloud

Esta sección está destinada a los administradores.

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

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

Registra las aplicaciones clientes con el proveedor de OpenID

Esta sección está destinada a los administradores.

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

  • Obtén más información sobre el URI de la entidad emisora del proveedor. Aquí es donde el complemento Kubectl para OIDC o la consola de Google Cloud 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 la consola de Google Cloud. Esta es https://console.cloud.google.com/kubernetes/oidc

  • Establece un ID de cliente. Este es el ID que el proveedor usa a fin de identificar el complemento de Kubectl para OIDC y la consola de Google Cloud.

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

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

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

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

Propaga la especificación oidc en el archivo de configuración de GKE On-Prem

Esta sección está destinada a los empleados que quieran crear un clúster configurado para usar OIDC.

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

oidc:
  issuerurl:
  clientid:
  clientsecret:
  username:
  usernameprefix:
  group:
  groupprefix:
  scopes:
  extraparams:
  usehttpproxy:
  capath:
  • issuerurl: obligatorio. Es la URL del proveedor de OpenID, como https://example.com/adfs. Las aplicaciones cliente, como el complemento de Kubectl para OIDC y la consola de Google Cloud, 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 la verificación de tokens. Debe usar HTTPS.
  • clientid: obligatorio. Es el ID de la aplicación cliente que realiza solicitudes de autenticación al proveedor de OpenID. El complemento de Kubectl para OIDC y la consola de Google Cloud usan este ID.
  • clientsecret: Opcional. Es el secreto de la aplicación cliente. El complemento de Kubectl para OIDC y la consola de Google Cloud usan este secreto.
  • username: Opcional. Es la reclamación de JWT que se debe usar como nombre de usuario. El valor predeterminado es sub, que se espera que sea un identificador único del usuario final. Puedes elegir otras reclamaciones, como email o name, en función del proveedor de OpenID. Sin embargo, a las reclamaciones que no sean email se les agrega el prefijo de la URL de la entidad emisora para evitar conflictos de nombres con otros complementos.
  • usernameprefix: Opcional. Es el prefijo que se antepone a las reclamaciones de nombre de usuario para evitar conflictos con los nombres existentes. Si no proporcionas este campo y username es un valor distinto de email, el prefijo se configurará de forma predeterminada como issuerurl#. Puedes usar el valor - para inhabilitar todos los prefijos.
  • group: Opcional. Es la reclamación de JWT que el proveedor usará para mostrar los grupos de seguridad.
  • groupprefix: Opcional. Es el prefijo que se antepone a las reclamaciones de grupos para evitar conflictos con los 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 Son los parámetros adicionales de clave-valor que se deben enviar al proveedor de OpenID como una lista separada 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 a fin de autenticar usuarios. El valor debe ser una string: "true" o "false".
  • capath: Opcional. Es la ruta al certificado de la autoridad certificada (CA) que emitió el certificado web del proveedor de identidad. Es posible que este valor no sea necesario. Por ejemplo, si el certificado de tu proveedor de identidad lo emitió 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 de los usuarios, como el correo electrónico y los ID 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 dificultar la lectura y la auditoría de las políticas.
  • Los correos electrónicos pueden generar un riesgo de disponibilidad (si un usuario cambia su correo electrónico principal) y un posible riesgo de seguridad (si se puede reasignar un correo electrónico).

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

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

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

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

El clúster de usuarios tiene un servidor de API de Kubernetes. Y el archivo kubeconfig del 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 Base64 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 de la entidad emisora.
  • [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 del certificado que creaste en la sección anterior.
  • [PROVIDER_CA_CERT] es la ruta de acceso al certificado de la CA que firma 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 permisos 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 incluyen 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 de la entidad emisora.
  • [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 del certificado que creaste en la sección anterior.
  • [PROVIDER_CA_CERT] es la ruta de acceso al certificado de la CA que firma 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 permisos 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 incluyen en las solicitudes de autorización al proveedor de OpenID.

Con este comando se produce un archivo de configuración de autenticación de cliente llamado client-config.yaml. No edites este archivo de forma manual.

Autentica 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 mediante 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 de acceso al archivo kubeconfig en el que el complemento Kubectl para OIDC almacenará las credenciales.

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

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

  2. Verifica que la autenticación se ejecute de forma correcta mediante la ejecución de cualquier comando de kubectl. Por ejemplo:

    kubectl get nodes --kubeconfig [KUBECONFIG_OUTPUT_PATH]

Usa OIDC con Google Cloud Console

Esta sección es para los empleados que crearon un clúster de usuarios y ahora desean usar Google Cloud Console a fin de 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 la consola de Google Cloud.

    Visitar la página Clústeres de Kubernetes

  4. En la lista de clústeres, ubica tu clúster de GKE local 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á al proveedor de identidad, en el que es posible que debas acceder u otorgar consentimiento a la consola de Google Cloud para que acceda a tu cuenta. Luego, se te redireccionará a la página Clústeres de Kubernetes en la consola de Google Cloud.

Soluciona problemas de OIDC en GKE On-Prem

La configuración no es válida

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

Los permisos no son válidos

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

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

Es posible que se genere 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 en el 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.