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 por defecto los clusters como user:<login>, no cambia.
• Las contraseñas dejan de valer, salvo las de las cuentas break-glass, 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.

Si tu organización entra con Google Workspace, Microsoft Entra ID, Okta u otro proveedor OpenID Connect, mira Login con OIDC (SSO). Los dos pueden estar activos a la vez: ver GitHub y OIDC a la vez.

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).
• El 2FA obligatorio para toda la organización en GitHub: Settings → Authentication security → Require two-factor authentication for everyone in the organization. kubelatch no tiene doble factor propio (El doble factor).
• 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 break-glass¶

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

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

La CLI funciona con o sin las variables GITHUB_* y nunca habla con GitHub. Las cuentas break-glass 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:

1. Pon los secretos en un Secret:

   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>'
   

   O añade esas claves a kubelatch-secrets, que ya se carga entero.

2. En tus values, carga el Secret con extraEnvFrom: [{secretRef: {name: kubelatch-github}}] y pon config.github.org (y config.github.requireOrg2FA, config.github.url y config.github.apiURL si los necesitas). Haz las dos cosas en el mismo helm upgrade: por sí sola, GITHUB_ORG activa el login con GitHub y kubelatch no arranca sin las otras cuatro.

3. Ejecuta helm upgrade con los mismos values. Un cambio posterior en cualquiera de los dos Secrets no redespliega solo: reinicia con kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch rollout restart deploy/kubelatch.
4. Mira el log: la línea listening lleva github_login en true (y github_webhook en true si hay secreto). Si ningún admin puede entrar, kubelatch arranca igualmente pero registra el error … but no admin can log in: …, que nombra los logins activos y el comando que lo arregla.

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 una cuenta» → «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» → la ficha de la cuenta → «Enlace de vinculación», en su menú (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 break-glass) va a «Mi cuenta» → «Identidades» → «Vincular con GitHub».

Una cuenta ya vinculada no se puede volver a vincular desde «Mi cuenta». Un admin la desvincula antes con «Usuarios» → la ficha de la cuenta → «Desvincular GitHub», en su menú. 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 «Esa cuenta de GitHub no está vinculada a ninguna cuenta de kubelatch. Pide a un administrador un enlace de vinculación.»: 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 break-glass sin vincular quedan fuera, a propósito. Una break-glass 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.

Si la App se desinstala o se suspende, el webhook lo registra en el log y 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).

GitHub y OIDC a la vez¶

El login con GitHub y el login con OIDC pueden estar activos al mismo tiempo. La página de login ofrece entonces los dos botones, primero el del proveedor OIDC, y cada persona puede tener una identidad de GitHub, una de OIDC o las dos: cualquiera de ellas abre la misma cuenta de kubelatch, con el mismo login y los mismos permisos.

• Los enlaces de invitación y de vinculación ofrecen las dos formas de vincular, y «Mi cuenta» muestra las dos en su tarjeta «Identidades».
• La sincronización de miembros y el webhook member_removed siguen funcionando como arriba: quien sale de la organización queda deshabilitado, aunque también entre por el proveedor OIDC.
• El proveedor OIDC no le da a kubelatch ninguna lista de miembros. Una cuenta que solo tiene identidad OIDC nunca se deshabilita sola: deshabilítala en «Usuarios».
• Las contraseñas siguen reservadas a las cuentas break-glass.

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. «Avisos», la campana de la barra superior, dice «kubelatch no puede comprobar si la organización de GitHub exige 2FA: mira la última sincronización en Usuarios.»

Cuando kubelatch sí sabe que la organización no exige 2FA, «Avisos» lo advierte: «La organización de GitHub no exige 2FA: (...)». Los dos avisos llevan a «Usuarios», y «Salud de la instalación» en «Edición» muestra la misma comprobación (Ediciones y licencia).

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 con "password": false, "github": true y "org": "<org>" (la respuesta completa, con oidc, oidc_name y access_contact, está en API HTTP), y el login muestra «Entrar con GitHub».
• Como admin break-glass, genera un «Enlace de vinculación» desde la ficha de tu cuenta en «Usuarios» (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 «Tu cuenta de GitHub no es miembro activo de la organización.»; una no vinculada, «Esa cuenta de GitHub no está vinculada a ninguna cuenta de kubelatch. Pide a un administrador un enlace de vinculación.».
• La contraseña de una cuenta vinculada que no es break-glass ya no entra (401 genérico y login.failure con reason: password_disabled). La break-glass sí, desde «Entrar con 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.