Login con GitHub¶

Con una GitHub App de tu organización, las personas entran en kubelatch con su cuenta de GitHub y se dan de baja solas al salir de la organización. Esta guía la crea, la instala y la conecta con kubelatch.

Qué cambia al activarla:

• Solo entran los miembros activos de la organización. Una invitación pendiente no vale.
• Cada cuenta de kubelatch queda vinculada al id numérico de una cuenta de GitHub. Su login de kubelatch, el que ven los clusters como user:<login>, no cambia.
• Las contraseñas dejan de valer, salvo las de las cuentas de emergencia, que se marcan desde la CLI.
• El doble factor lo impone la organización de GitHub, no kubelatch.

El porqué de este modelo está en Identidad y en Modelo de seguridad.

Antes de empezar¶

• Permisos de propietario en la organización de GitHub. Todo lo de GitHub se hace una sola vez.
• kubelatch instalado y un administrador que entra con contraseña (Instalar).
• Activa en GitHub el 2FA obligatorio para toda la organización: Settings → Authentication security → Require two-factor authentication for everyone in the organization.
• Los comandos usan $MGMT_KUBECONFIG, la ruta al kubeconfig del cluster de gestión (ver Instalar).

1. Crea la GitHub App¶

En la organización: Settings → Developer settings → GitHub Apps → New GitHub App (https://github.com/organizations/<org>/settings/apps/new).

No hace falta ningún permiso de repositorio ni de cuenta de usuario. Las GitHub Apps no usan scopes: al autorizar, la persona ve exactamente estos permisos.

En la configuración del webhook, elige Content type: application/json. Con cualquier otro tipo, kubelatch responde 415.

Tras crear la App, en su página:

1. Apunta el App ID (GITHUB_APP_ID) y el Client ID (GITHUB_APP_CLIENT_ID).
2. Pulsa Generate a new client secret: es GITHUB_APP_CLIENT_SECRET y solo se muestra una vez.
3. En Private keys → Generate a private key, descarga el .pem: es GITHUB_APP_PRIVATE_KEY, el fichero completo con sus cabeceras.

2. Instálala en la organización¶

En la página de la App: Install App → tu organización → Install. Da igual si eliges «All repositories» u «Only select repositories» sin ninguno: los permisos que usa son de organización.

Sin instalación, kubelatch no puede comprobar la pertenencia de quien entra ni leer la lista de miembros. La sincronización falla con app not installed in the organization y no deshabilita a nadie.

3. Prepara una cuenta de emergencia¶

Marca tu administrador actual, o crea una cuenta solo para emergencias:

kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -it deploy/kubelatch -- /kubelatch user set-break-glass admin
# o una cuenta nueva:
kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -it deploy/kubelatch -- /kubelatch user create rescate --admin --break-glass

La CLI funciona con o sin las variables GITHUB_* y nunca habla con GitHub. Las cuentas de emergencia no tienen doble factor: que sean pocas, con contraseñas largas en el gestor de secretos, y solo para cuando GitHub no está. Más en Cuentas y recuperación.

4. Configura kubelatch¶

Las cinco primeras van juntas. Si hay cualquiera de ellas (o GITHUB_WEBHOOK_SECRET), kubelatch exige las cinco y no arranca si falta alguna. Así un despliegue a medias no deja las contraseñas activas sin querer. Todas están en Configuración.

En Kubernetes, pon los secretos en un Secret y deja GITHUB_ORG, GITHUB_REQUIRE_ORG_2FA y las URL en config.env:

kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch create secret generic kubelatch-github \
  --from-literal=GITHUB_APP_ID=<app-id> \
  --from-literal=GITHUB_APP_CLIENT_ID=<client-id> \
  --from-literal=GITHUB_APP_CLIENT_SECRET='<client-secret>' \
  --from-file=GITHUB_APP_PRIVATE_KEY=<fichero>.private-key.pem \
  --from-literal=GITHUB_WEBHOOK_SECRET='<secreto-del-webhook>'

Añade ese Secret al envFrom del Deployment, o mete las claves en kubelatch-secrets, que ya se carga entero. En el segundo caso reinicia con kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch rollout restart deploy/kubelatch: el cambio de un Secret no redespliega solo. Al arrancar, el log muestra github_login=true (y github_webhook=true si hay secreto). Si ningún admin puede entrar, el log lo dice con un error al arrancar.

5. Vincula las cuentas existentes¶

Las cuentas de kubelatch no cambian: mismo login, permisos y credenciales. Solo hay que vincular cada una a su cuenta de GitHub. Hay tres caminos:

• Cuentas nuevas: «Usuarios» → «Crear e invitar». El enlace de invitación (72 h) lleva a «Vincular con GitHub y entrar». La persona autoriza la App, kubelatch comprueba que es miembro activo y la cuenta queda vinculada y con sesión.
• Cuentas existentes: «Usuarios» → «Enlace de vinculación» (24 h). Sirve también para cambiar la cuenta de GitHub de alguien, y cierra sus sesiones.
• Desde la propia cuenta: quien ya puede entrar (por ejemplo, una cuenta de emergencia) va a «Mi cuenta» → «Vincular con GitHub».

Una cuenta ya vinculada no se puede volver a vincular desde «Mi cuenta». Un admin la desvincula antes con «Usuarios» → «Desvincular GitHub». Si al vincular sale github_taken, esa cuenta de GitHub ya está vinculada a otra persona: desvincula aquella primero.

No hay alta automática. Una cuenta de GitHub sin vincular se rechaza con «no está vinculada a ninguna cuenta de kubelatch»: un admin crea la cuenta e invita.

En cada login con GitHub, kubelatch comprueba que la persona es miembro activo de la organización. La vinculación guarda el id numérico, que GitHub nunca recicla; el login de GitHub es informativo y se refresca si la persona se renombra. El detalle del flujo está en Identidad.

Cómo funcionan las bajas¶

Solo afectan a cuentas vinculadas a GitHub. Las de emergencia sin vincular quedan fuera, a propósito. Una de emergencia vinculada pierde el acceso igual que cualquier otra si la persona sale de la organización.

• Sincronización horaria. La primera pasada es un minuto después de arrancar. Lista los miembros de la organización y deshabilita a quien ya no está, con los mismos efectos que «Deshabilitar»: sesiones cerradas, credenciales revocadas y fuera del RBAC del proxy en la siguiente reconciliación. También refresca los logins de GitHub renombrados.
• Webhook member_removed. La baja es inmediata. Va firmado con HMAC-SHA256 en X-Hub-Signature-256. Sin GITHUB_WEBHOOK_SECRET el endpoint responde 404.

La sincronización nunca deshabilita ante un error: un 5xx, un timeout, una página que falla, la App desinstalada o una respuesta con cero miembros abortan la pasada entera. El error aparece en el log y en «Usuarios». Tampoco rehabilita: si alguien vuelve a la organización, un admin lo rehabilita a mano.

La sincronización usa un token de instalación de la App. Solo deshabilita una cuenta si sigue vinculada al mismo id de GitHub que observó, y no evalúa las cuentas vinculadas durante la propia pasada. El webhook solo registra en el log los eventos installation deleted o suspend: desde ese momento todos los logins con GitHub fallan. Cualquier otro evento se acepta y se ignora.

El último administrador que puede entrar nunca se deshabilita por estas vías. Queda un error en el log (el webhook responde 200 igualmente, para que GitHub no reintente): revísalo.

En «Auditoría» → «Plano de control», cada baja es un user.disable sin actor, con via: github-sync o github-webhook.

El webhook no deduplica entregas: una repetida puede volver a deshabilitar a alguien que rehabilitaste (ver Modelo de seguridad).

El doble factor¶

kubelatch no tiene segundo factor propio: se apoya en el 2FA obligatorio de la organización. Solo puede comprobarlo si la App tiene Organization → Administration: read:

• Con el permiso y GITHUB_REQUIRE_ORG_2FA=true: rechaza los logins con GitHub mientras la organización no exija 2FA (no_2fa en el login) y lo escribe como error en cada sincronización.
• Sin el permiso: no puede distinguir «no exige 2FA» de «no lo sé». Deja entrar y avisa en cada pasada. «Usuarios» muestra «no se puede comprobar el 2FA de la organización».

kubelatch guarda en caché la respuesta hasta 10 minutos.

Comprueba que funciona¶

Con la App creada e instalada y kubelatch reiniciado con las variables:

• GET /api/auth/methods responde {"github":true,"org":"<org>"} y el login muestra «Entrar con GitHub».
• Como admin de emergencia, genera en «Usuarios» un «Enlace de vinculación» para tu cuenta (o crea un usuario). Ábrelo en una ventana privada, pulsa «Vincular con GitHub y entrar» y autoriza. Acabas en «Inicio» con sesión.
• En «Usuarios», la columna GitHub muestra login (id). En «Auditoría» → «Plano de control» hay un link.complete y un login.success con via: github.
• Cierra sesión y entra con «Entrar con GitHub»: sesión directa. Una cuenta que no es miembro (o con invitación pendiente) ve «no es miembro activo de la organización»; una no vinculada, «no está vinculada a ninguna cuenta de kubelatch».
• La contraseña de una cuenta vinculada que no es de emergencia ya no entra (401 genérico y login.failure con reason: password_disabled). La de emergencia sí, desde «Cuenta de emergencia (contraseña)».
• Un minuto después del arranque, el log muestra membership sync: done con members=… y «Usuarios» resume la última pasada.
• Saca de la organización a una cuenta de prueba: con webhook se deshabilita al momento; sin él, en la siguiente pasada. Rehabilitarla en «Usuarios» y volver a añadirla a la organización la deja entrar de nuevo.
• GET /api/github/status (admin) muestra configured, org, webhook, require_org_2fa y last_sync con two_factor_required (null si la App no puede leerlo).

Si algo falla (redirect_uri, not_member, no_2fa, webhook con 401, 413 o 415), mira Solución de problemas.