Cuentas y recuperación¶
Qué hacer cuando alguien se queda fuera de kubelatch, y cuando se queda fuera todo el mundo. Incluye las cuentas break-glass y el acceso nativo a los clusters cuando kubelatch no está.
Cómo entran las personas¶
| Sin login externo | Con GitHub App (Login con GitHub) | Con un proveedor OIDC (Login con OIDC (SSO)) | |
|---|---|---|---|
| Personas | Usuario y contraseña. | «Entrar con GitHub». Solo miembros activos de la organización, con el 2FA que esta impone. | «Entrar con {name}». Solo direcciones de correo que el proveedor verifica, de los dominios permitidos, con el 2FA que imponga el proveedor. |
| Contraseñas | Todas valen. | Solo las de las cuentas break-glass. Las demás siguen en la base de datos, pero no sirven para entrar. | Solo las de las cuentas break-glass, como con GitHub. |
| Alta | «Crear e invitar»: la persona fija su contraseña. | «Crear e invitar»: la persona vincula su cuenta de GitHub. | «Crear e invitar»: el primer acceso de la persona vincula la cuenta por su dirección de correo, o la persona usa el enlace de invitación. |
| Bajas | Manuales: «Deshabilitar». | Automáticas al salir de la organización, o «Deshabilitar». | Manuales: «Deshabilitar». El proveedor no da lista de miembros. |
| Mi cuenta (pulsa tu nombre al pie de la barra lateral) | Cambiar contraseña. | «Vincular con GitHub», en «Identidades». Cambiar contraseña, solo las cuentas break-glass. | «Vincular con {name}», en «Identidades». Cambiar contraseña, solo las cuentas break-glass. |
En esta página, {name} es el nombre del proveedor, OIDC_DISPLAY_NAME (SSO por defecto). GitHub y OIDC pueden estar activos a la vez: la página de login ofrece los dos y cada persona puede tener cualquiera de las dos identidades, o las dos (GitHub y OIDC a la vez).
Cambiar de modo no toca las cuentas. Con GitHub, se vinculan una a una con enlaces de vinculación; con un proveedor OIDC, la mayoría se vinculan solas en su primer acceso. Los bots no entran nunca: solo tienen credenciales (Usuarios y bots).
Sin login externo no hay doble factor ni bajas automáticas, y de los dos logins externos solo GitHub da de baja a la gente por sí solo: ver Modelo de seguridad.
Reglas de las cuentas¶
- Contraseñas: de 12 a 128 caracteres, distinta del login, sin reglas de composición. Cada persona cambia la suya en «Mi cuenta» dando la actual; eso cierra sus otras sesiones. El cambio está limitado a 10 intentos por minuto por cuenta.
- Sesiones: cookie firmada de 12 h. Se cierran todas al instante al salir, cambiar la contraseña, usar un enlace de restablecimiento o de vinculación, desvincular GitHub o la identidad OIDC, deshabilitar la cuenta o pulsar «Cerrar las sesiones web» en la ficha de la cuenta. Ese botón cierra solo las sesiones web: una sesión de la CLI es una credencial, y se revoca en «Credenciales».
- Bloqueo: 5 fallos seguidos bloquean la cuenta 15 minutos (el quinto ya responde
429). Además, cada IP (o cada /64 en IPv6) tiene 10 intentos por minuto. Todo intento queda en el plano de control con la IP. - Último administrador: kubelatch no deja quitar el rol, deshabilitar, desvincular ni desmarcar como break-glass al último admin que puede entrar.
Cuentas break-glass¶
Una cuenta break-glass conserva la contraseña cuando el login con GitHub o con OIDC está activado. Sirve para entrar si GitHub o el proveedor de identidad están caídos, si la App se ha desinstalado o si un error de configuración (un dominio mal escrito, un claim equivocado) deja fuera a todos los demás. Solo se marca desde la CLI. Los comandos usan $MGMT_KUBECONFIG, la ruta al kubeconfig del cluster de gestión (ver Instalar).
# marcar una cuenta existente
kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -it deploy/kubelatch -- /kubelatch-server user set-break-glass <login>
# quitar la marca
kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -it deploy/kubelatch -- /kubelatch-server user set-break-glass <login> --off
# crear una cuenta de emergencia nueva
kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -it deploy/kubelatch -- /kubelatch-server user create rescate --admin --break-glass
Ten al menos una, con la contraseña en el gestor de secretos de la organización. No la uses en el día a día: no tiene doble factor. En «Usuarios», su «Entrada» dice «Contraseña · break-glass», en ámbar, y el chip «break-glass» la cuenta. Entra desde «Entrar con contraseña», al pie de la página de login. Si la vinculas a GitHub y la persona sale de la organización, pierde el acceso como cualquier otra. Vinculada al proveedor OIDC, conserva la contraseña.
Cuando una persona se queda fuera¶
| Situación | Qué hacer | Quién |
|---|---|---|
| Contraseña olvidada | «Usuarios» → la ficha de la cuenta → «Restablecer acceso» (un enlace de restablecimiento, 24 h, un solo uso). Compártelo por un canal seguro. Con GitHub u OIDC, solo aplica a cuentas break-glass. | Un admin |
| Cuenta bloqueada por intentos | «Usuarios» dice «Bloqueada hasta …». Esperar 15 minutos, o «Restablecer acceso», cuyo enlace la desbloquea. | La persona / un admin |
| Cuenta de GitHub cambiada, perdida o vinculada por error | «Usuarios» → la ficha de la cuenta → «Enlace de vinculación» (24 h). Si sale github_taken, esa cuenta de GitHub ya está vinculada a otra persona: «Desvincular GitHub» en la otra primero. |
Un admin |
| Vinculada a una identidad OIDC equivocada, o se volvió a crear la cuenta de la persona en el proveedor | «Usuarios» → la ficha de la cuenta → «Desvincular {name}». El siguiente acceso con {name} vuelve a vincular una identidad por correo si la política de vinculación lo permite; si no, genera un «Enlace de vinculación». oidc_taken significa que esa identidad ya abre otra cuenta: «Desvincular {name}» en aquella primero. |
Un admin |
Una dirección de correo que ha pasado a otra persona cuando su dueño se fue (la persona nueva ve identity_mismatch) |
No desvincules: esa cuenta sigue siendo de su dueño anterior. Deshabilítala («Deshabilitar») y crea otra para la persona nueva, que se vincula en su primer acceso. | Un admin |
| No puede entrar con GitHub | Lee el mensaje del login. «Tu cuenta de GitHub no es miembro activo de la organización.»: falta en la organización o la invitación está pendiente. «Esa cuenta de GitHub no está vinculada a ninguna cuenta de kubelatch. Pide a un administrador un enlace de vinculación.»: hace falta un enlace de vinculación. «La organización de GitHub no exige doble factor; un administrador de la organización debe activarlo antes de que kubelatch acepte accesos con GitHub.»: activar el 2FA en la organización. «Tu cuenta está deshabilitada.»: un admin la rehabilita. | La persona / un admin |
| No puede entrar con el proveedor OIDC | Lee el mensaje del login; cada uno, con qué hacer, está en Cuando un acceso falla. Los habituales: «Ninguna cuenta de kubelatch tiene la dirección de correo de esa cuenta de {name}.» (crea la cuenta, rellena su correo o, si la política de vinculación no la cubre, genera un «Enlace de vinculación») y «Esa cuenta de {name} no es de un dominio que este kubelatch acepte. ¿Has elegido una cuenta personal?» («Probar con otra cuenta», o añade el dominio a OIDC_ALLOWED_DOMAINS). «Tu cuenta está deshabilitada.»: un admin la rehabilita. |
La persona / un admin |
| Enlace caducado o ya usado | La persona ve «Enlace caducado o ya usado» (410 en la API). Genera otro («Generar otro enlace», en la tarjeta «Entrada» de la cuenta): anula los pendientes. |
Un admin |
| Persona que deja la empresa | Con GitHub, sacarla de la organización basta. Solo con OIDC, o para adelantarse: «Deshabilitar»; deshabilitarla en el proveedor solo impide su siguiente acceso. Nada la rehabilita solo aunque vuelva. | Un admin / GitHub |
| Credencial perdida o filtrada | «Revocar» en «Inicio» (la propia persona) o en «Credenciales» (un admin). Si solo tienes el token, pégalo entero en «Credenciales» (Localizar un token filtrado): abre esa credencial, con «Revocar» al pie. La siguiente petición recibe 401 y los streams abiertos se cortan en menos de 10 s. Emitir otra. |
La persona / un admin |
| Bot comprometido | Revocar sus credenciales o deshabilitar el bot. | Un admin |
Cuando nadie puede entrar¶
La CLI kubelatch-server user es la vía de rescate. Se ejecuta con la misma configuración que el servidor, aplica las migraciones pendientes y registra lo que hace en el plano de control sin actor. Úsala siempre con el kubeconfig explícito del cluster de gestión.
-
Contraseña nueva para un admin existente. También lo desbloquea, cierra sus sesiones y anula sus enlaces pendientes. No rehabilita una cuenta deshabilitada.
kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -it deploy/kubelatch -- /kubelatch-server user set-password admin -
Con GitHub u OIDC activado, esa contraseña solo vale si la cuenta es break-glass. La CLI avisa si no lo es. Márcala:
kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -it deploy/kubelatch -- /kubelatch-server user set-break-glass admin -
Si el único admin está deshabilitado, o no hay ninguno, crea otro y rehabilita al primero desde «Usuarios»:
kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -it deploy/kubelatch -- /kubelatch-server user create rescate --admin --break-glass
Sin terminal (un runner, un script), usa --password-stdin con kubectl exec -i. Se quita exactamente un salto de línea final: una contraseña que termina en salto de línea se pasa con dos.
printf '%s' '<contraseña larga>' | kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -i deploy/kubelatch -- /kubelatch-server user set-password admin --password-stdin
Con dos réplicas da igual en cuál se ejecute: la CLI va directamente a Postgres y no hace falta parar el servidor.
Si el pod no arranca (Postgres caído, configuración rota), el problema no es de cuentas. Mira los logs y el estado del pod:
kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch logs deploy/kubelatch
kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch describe pod
Acceso nativo de emergencia¶
kubelatch está en el camino de cada petición de las personas, pero nunca es la única vía a un cluster, y las cargas de trabajo no dependen de él. Antes de ir a producción, deja preparado y probado el acceso nativo de administrador:
- Clusters gestionados: la identidad cloud del proveedor (
aws eks update-kubeconfig,gcloud container clusters get-credentials,az aks get-credentials) con el rol de administrador de la plataforma, en el gestor de identidades de la organización y con MFA. - Autogestionados: el kubeconfig de administrador (kubeadm:
/etc/kubernetes/admin.conf; k3s:/etc/rancher/k3s/k3s.yaml; Talos:talosctl kubeconfig) en un vault con acceso auditado, o SSH a un nodo del plano de control.
Ese acceso sirve para reparar kubelatch (por ejemplo, volver a aplicar el bootstrap), actuar cuando kubelatch está caído y hacer lo que kubelatch no permite: namespaces protegidos, nodos, --as. Su uso queda en la auditoría nativa del cluster, no en la de kubelatch: revísalo con la misma disciplina.
Cuando kubelatch funciona, prefiere un permiso cluster-admin de 8 h como máximo, que sí queda auditado: Conceder permisos.
Si se pierde la clave de cifrado¶
Sin KUBELATCH_ENCRYPTION_KEY, todo el mundo vuelve a iniciar sesión y hay que rotar los tokens de cada cluster. Las contraseñas, las credenciales klt_, los permisos y la auditoría no se ven afectados. El procedimiento está en Actualizar y copias de seguridad.