En esta página, se muestra cómo usar OpenID Connect (OIDC) con Servicios de federación de Active Directory (AD FS) a fin de configurar la autenticación para los clústeres de usuario de GKE On-Prem.
Para obtener una descripción general del flujo de autenticación, consulta Autenticación. Para obtener información sobre el uso de proveedores de OpenID que no sean AD FS, consulta Autentica con OpenID Connect.
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. Usa un conjunto de asistentes de administración de AD FS para configurar tu servidor de AD FS y tu base de datos de empleados de AD.
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.
Este tema se aplica a las empresas que tienen la siguiente infraestructura:
- La empresa usa Active Directory (AD) para su base de datos de empleados.
- La empresa ejecuta un servidor de Active Directory Federation Services (AD FS).
- El servidor AD FS actúa como un proveedor de OpenID.
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 de la relación de tu servidor de AD FS, debes especificar una URL de redireccionamiento que el servidor AD FS puede 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 la que [PORT] es tu número de puerto.
Cuando configures tu servidor AD FS, especifica http://localhost:[PORT]/callback como una de tus URL de redireccionamiento.
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 del complemento de Kubectl para OIDC, necesitas una URL de redireccionamiento de la consola de Google Cloud. La URL de redireccionamiento de la consola de Google Cloud es la siguiente:
https://console.cloud.google.com/kubernetes/oidc
Cuando configures tu servidor de AD FS, especifica https://console.cloud.google.com/kubernetes/oidc como una de tus URL de redireccionamiento.
Configura AD FS
En las siguientes secciones, se explica cómo configurar AD FS para GKE On-Prem.
Configura las URL de redireccionamiento
Abre el panel de administración de AD FS.
Selecciona Application Groups > Acciones > Add an Application Group.
Selecciona Server Application. Ingresa el nombre y la descripción que prefieras. Luego, haz clic en Siguiente.
Ingresa las dos URL de redireccionamiento. Se te proporcionará un ID de cliente. Así es como el servidor AD FS identifica el complemento de Kubectl para OIDC y la consola de Google Cloud. Guarda el ID de cliente para usarlo más adelante.
Selecciona Generate a shared secret. Para el complemento de Kubectl para OIDC y la consola de Google Cloud, se usa este secreto a fin de autenticarse en el servidor de AD FS. Guarda el secreto para más adelante.
Configura grupos de seguridad (opcional)
En la administración de AD FS, selecciona Confianza con la parte autenticada > Agrega una nueva relación de confianza con la parte autenticada.
Selecciona Claims aware y haz clic en Iniciar.
Selecciona Enter data about relying party manually.
Ingresa un nombre visible.
Omite los siguientes dos pasos.
Ingresa el identificador de una relación de confianza con la parte autenticada. Sugerencia:
token-groups-claim
.En Access control policy, selecciona Permit everyone. Esto significa que todos los empleados comparten la información de su grupo de seguridad con el complemento de Kubectl para OIDC y la consola de Google Cloud.
Haz clic en Finalizar.
Asigna atributos LDAP a los nombres de reclamaciones
En la administración de AD FS, selecciona Confianza de la parte autenticada > Editar política de emisión de reclamos.
Selecciona Send LDAP Attributes as Claims y haz clic en Siguiente.
En Claim rule name, ingresa
groups
.En Attribute store, selecciona Active Directory.
En la tabla, en LDAP Attribute, selecciona lo siguiente:
- Para la versión 5.0 y posteriores de AD FS: Token-Groups Qualified by Domain name
- Para versiones de AD FS anteriores a 5.0: Token Groups - Qualified Names
En Outgoing Claim Type, selecciona lo siguiente:
- Para la versión 5.0 y posteriores de AD FS: Group
- Para versiones de AD FS anteriores a 5.0: groups
Haz clic en Finalizar y, luego, en Aplicar.
Registra el complemento de Kubectl para OIDC y la consola de Google Cloud con AD FS
Abre una ventana de PowerShell en modo de administrador e ingresa este comando:
Grant-AD FSApplicationPermission ` -ClientRoleIdentifier "[CLIENT_ID]" ` -ServerRoleIdentifier [SERVER_ROLE_IDENTIFIER] ` -ScopeName "allatclaims", "openid"
Donde:
[CLIENT_ID] es el ID de cliente que obtuviste antes.
[SERVER_ROLE_IDENTIFIER] es el identificador de la reclamación que ingresaste antes. Recuerda que el identificador sugerido era
token-groups-claim
.
Propaga la especificación de oidc en el archivo de configuración del clúster
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, comohttps://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 essub
, que se espera que sea un identificador único del usuario final. Puedes elegir otras reclamaciones, comoemail
oname
, en función del proveedor de OpenID. Sin embargo, a las reclamaciones que no seanemail
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 yusername
es un valor distinto deemail
, el prefijo se configurará de forma predeterminada comoissuerurl#
. 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 grupofoobar
y un prefijogid-
,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.- Para obtener una lista de los parámetros de autenticación, consulta Parámetros del URI de autenticación.
- Para obtener una lista de los parámetros de autenticación de Microsoft Azure, consulta Envía la solicitud de acceso.
- Si autorizas un grupo, pasa
resource=token-groups-claim
. - Si el servidor de autorización solicita tu consentimiento, pasa
prompt=consent
.
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.- Para obtener una lista de los parámetros de autenticación, consulta Parámetros del URI de autenticación.
- Si autorizas un grupo, pasa
resource=token-groups-claim
. - Si el servidor de autorización solicita tu consentimiento, pasa
prompt=consent
.
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.- Para obtener una lista de los parámetros de autenticación de Google, consulta Parámetros de URI de autenticación.
- Para obtener una lista de los parámetros de autenticación de Microsoft Azure, consulta Envía la solicitud de acceso.
- Si autorizas un grupo, pasa
resource=token-groups-claim
. - Si el servidor de autorización solicita tu consentimiento, pasa
prompt=consent
.
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.
-
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 dekubectl oidc login
. -
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.
-
Verifica que tu clúster esté configurado para OIDC.
-
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.
-
Visita la página Clústeres de Kubernetes en la consola de Google Cloud.
-
En la lista de clústeres, ubica tu clúster de GKE local y haz clic en Acceder.
-
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.
Resumen
Tu empresa ejecuta un servidor AD FS que actúa como tu proveedor de OpenID. Tu proveedor de OpenID conoce tus dos aplicaciones cliente: el complemento de Kubectl para OIDC y la consola de Google Cloud. Tu proveedor de OpenID sabe que tus aplicaciones cliente pueden solicitar los alcances openid
y allatclaims
.
En la versión AD FS anterior a la 5.0, el atributo LDAP Token-Groups Qualified Names
en tu base de datos de AD se mapea a la reclamación groups
en tu proveedor de OpenID. En la versión 5.0 y posterior, el atributo es Token-Groups Qualified by Domain name
. El proveedor muestra los tokens que incluyen el ID del empleado, el ID de la entidad emisora, las reclamaciones openid
y groups
. La reclamación groups
(Group
en 5.0) enumera los grupos de seguridad a los que pertenece un empleado.
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
.
¿Qué sigue?
Consulta la descripción general de la autenticación con OpenID Connect en GKE On-Prem.
Obtén más información sobre OAuth 2.0
Obtén más información sobre OpenID Connect.
Obtén más información sobre los permisos y las reclamaciones.
Obtén más información sobre las reclamaciones personalizadas en los tokens de ID.