Usuarios y bots¶

En «Usuarios» das de alta a personas y bots, repartes el rol de administrador y deshabilitas cuentas. Cada cuenta tiene su propia ficha, donde está casi todo lo que haces con ella. Aquí tienes cada operación y lo que provoca.

Antes de empezar¶

• Eres administrador de kubelatch.
• Las cuentas se crean desde aquí, con kubelatch-server user create o, con el login con OIDC, por una regla de dominio o una solicitud de alta aprobada (Acceso por dominio y solicitudes de alta). Sin regla, un primer acceso solo vincula una cuenta que ya existe. Por defecto compartes tú los enlaces por un canal seguro; con Resend, kubelatch puede enviarlos por correo: ver Invitaciones por correo.
• Los logins son inmutables y no se reutilizan nunca, ni tras deshabilitar la cuenta. Son la identidad que ven los clusters: user:<login> para personas, salvo que la plantilla de identidad del cluster las nombre de otra forma, y bot:<nombre> para bots.

Dar de alta a una persona¶

La edición Free admite 5 personas habilitadas; la sexta invitación responde 422 edition.limit, igual que rehabilitar a alguien en el límite. Los bots nunca se limitan. Ver Ediciones y licencia.

1. En «Usuarios», pulsa «Crear una cuenta». El formulario se abre en un panel a la derecha; deja «Tipo» en «Persona».
2. Rellena «Login» (minúsculas, dígitos, ., _ o -, de 1 a 63 caracteres), «Nombre» y «Correo». Marca «Administrador» si procede.
3. Pulsa «Crear e invitar».
4. Copia el enlace del diálogo y compártelo por un canal seguro. No se vuelve a mostrar.

Con las Invitaciones por correo configuradas, el formulario pregunta cómo entregar la invitación: «Enviar por correo» (a la dirección que escribiste, sin que veas el enlace) o «Copiar el enlace», como arriba. Tras enviar, un aviso dice que salió y cuándo caduca.

El enlace tiene la forma <KUBELATCH_BASE_URL>/account-link#kli_… y vale 72 horas; el diálogo dice hasta cuándo. El token va tras #, así que nunca llega a los logs de servidores ni proxies. La página /account-link lo borra de la barra de direcciones en cuanto lo lee: si la persona recarga, verá «Enlace no válido» aunque el enlace original siga valiendo.

Lo que hace la persona con el enlace depende del modo:

• Sin login externo: fija su contraseña (de 12 a 128 caracteres, distinta del login) y entra.
• Con GitHub: pulsa «Vincular con GitHub y entrar» y autoriza la App. No fija ninguna contraseña. Ver Login con GitHub.
• Con un proveedor OIDC: pulsa «Vincular con {name} y entrar» y entra en el proveedor; {name} es OIDC_DISPLAY_NAME. No fija ninguna contraseña. A menudo ni le hace falta el enlace: su primer acceso con «Entrar con {name}» vincula la cuenta por su dirección de correo, si la política de vinculación lo permite. Ver Cómo se vinculan las cuentas.

Con GitHub y OIDC activados a la vez, el enlace ofrece los dos botones. Una cuenta break-glass recibe además el formulario de contraseña.

Después, concédele permisos en «Permisos» (Conceder permisos), o añádela a un grupo (Grupos); la tarjeta «Accesos» de su ficha hace ambas cosas. La persona emite después su credencial en «Inicio» (Obtener una credencial).

Si el enlace se pierde o caduca, reenvíalo por correo si salió así, o genera otro desde su ficha: «Generar otro enlace», en la tarjeta «Entrada», o «Restablecer acceso» (sin login externo) o «Enlace de vinculación» (con GitHub u OIDC), en su menú. Generar uno nuevo anula los pendientes de esa persona.

La lista y la ficha de la cuenta¶

«Usuarios» es el directorio. Una fila tiene la cuenta (su login, el nombre debajo y un enlace a su ficha), «Entrada», «Rol», «Acceso», «Última actividad» y un menú con «Abrir», «Permisos», «Peticiones» y «Deshabilitar» («Habilitar» en una cuenta deshabilitada). «Última actividad» es lo más reciente entre su último acceso, el último uso de una credencial y su última petición auditada. Una frase arriba cuenta todas las cuentas («9 personas y 3 bots; 3 administradores. 1 cuenta deshabilitada.»), antes de que nada acote la lista; una parte a cero no se dice. «Todos», «Personas», «Bots» y «Deshabilitados» dividen la lista, y «Filtrar» busca por login, nombre, correo, cuenta de GitHub o el correo de la identidad OIDC. Al lado, unos chips cuentan las cuentas habilitadas y filtran la lista: «3 administradores», «1 break-glass», «2 invitaciones pendientes» (un enlace de invitación que nadie ha usado aún), «2 sin acceso» (ni grupo ni permiso directo), «3 vinculadas a {name}» (una identidad del proveedor OIDC, mientras está activado), «4 vinculadas a GitHub» (con GitHub activado) y «4 con contraseña» (solo con un login externo activado: sin él, toda persona tiene contraseña). Pulsa un chip para ver esas cuentas, pulsa varios para combinarlos y comparte la dirección de la página, que los conserva. Un chip sin nada que contar no se dibuja. Pulsar un chip devuelve la lista a «Todos», y las pestañas cuentan lo que los chips dejan. «Cómo funcionan las cuentas» despliega unas líneas de ayuda y un enlace a este manual. Con OIDC activado, una línea dice si kubelatch ha podido leer el documento de descubrimiento del proveedor: «{name}: descubrimiento leído el {date}.», «{name}: descubrimiento aún sin leer.» o «{name}: la última lectura del descubrimiento falló ({error}).»

«Inicio» y «Operativa» enlazan aquí con la lista ya acotada. «Con permisos y sin actividad en 90 días» (cuentas habilitadas creadas hace más de 90 días que tienen un permiso y no han entrado ni hecho una petición en 90 días, o nunca) lo dice en una línea encima de la lista, con «Quitar filtro»; se suma a «Todos», «Personas», «Bots» o «Deshabilitados», a «Filtrar» y a los chips, que cuentan la lista acotada. La línea de invitaciones de «Pendientes» («2 invitaciones caducan esta semana») aterriza en el chip de invitaciones pendientes, pulsado, que contiene todas las pendientes.

«Entrada» dice en una sola etiqueta cómo entra la cuenta: «GitHub · alice», «{name} · ana@acme.com» (el nombre del proveedor y el correo de la identidad OIDC), «{name} · aún no ha entrado» (OIDC activado, todavía sin identidad y sin enlace pendiente), «{name} · por dominio» y «{name} · por solicitud» (una cuenta que creó una regla de dominio, o una solicitud de alta que aprobaste), «Contraseña», «Contraseña · break-glass», «Invitación · caduca en 2 d», «Invitación caducada», «Bloqueada hasta 18:30», «Deshabilitada», o «Credenciales» en un bot. Una cuenta vinculada a GitHub y al proveedor OIDC muestra su identidad OIDC. Una contraseña break-glass y una invitación pendiente se pintan en ámbar: la primera se salta GitHub y el proveedor OIDC, y la segunda es un enlace que alguien aún tiene que usar.

Pulsa el login, o «Abrir», para ir a la ficha de la cuenta. Arriba nombra la cuenta con su nombre, su tipo («Persona» o «Bot»), «Administrador» si lo es y la misma etiqueta. El botón «Deshabilitar» (o «Habilitar») y un menú guardan las operaciones de más abajo; el menú ofrece solo lo que aplica a esa cuenta. Cuatro cifras dicen qué tiene: «Permisos activos», «Credenciales activas», «Grupos» y «Última actividad». Después, las tarjetas: «Accesos», a todo el ancho (más abajo), «Entrada» (el método, cuándo se vinculó GitHub, una fila con el nombre del proveedor OIDC, el correo con el que se vinculó y cuándo, si es break-glass, cuándo cambió por última vez la contraseña, un enlace pendiente o caducado y sus sesiones), «Credenciales», en un bot también «Reglas de CI» y «Agente de IA», y «Actividad»: sus últimas 20 peticiones, con «Abrir en Auditoría» para el resto.

El correo de la cuenta¶

La tarjeta «Entrada» de la ficha enseña el correo de la cuenta y adónde van sus avisos. Van al correo de la cuenta. Si no tiene, y con el inicio de sesión OIDC activado, van al correo verificado de su identidad en el proveedor, y una línea de la tarjeta lo dice. Esa dirección solo sirve para entregar avisos: no se copia a la cuenta, así que las invitaciones y los enlaces de restablecimiento siguen necesitando un correo en la cuenta. Una cuenta que entra con GitHub recibe avisos en cuanto le pones aquí un correo.

Solo un administrador lo cambia, desde la ficha de la cuenta: «Cambiar» abre el campo y «Quitar» lo borra. Nadie cambia el suyo desde «Mi cuenta», tampoco un administrador.

• Admite una sola dirección, como ana@example.com, sin nombre ni lista; cualquier otra cosa es 400 subject.email_invalid.
• Una dirección que ya tiene otra cuenta, habilitada o no, como propia o como el correo de su identidad OIDC, se rechaza con 409 subject.email_taken: los avisos de las dos cuentas llegarían al mismo buzón, y quien entrase con ese correo acabaría en la otra cuenta. Dar de alta a una persona comprueba lo mismo.
• Con el inicio de sesión OIDC activado y la política de vinculación distinta de off, una dirección de uno de los OIDC_ALLOWED_DOMAINS permite que quien entre con ese correo verificado abra esta cuenta y tenga sus permisos en cuanto la cuenta no tenga identidad del proveedor: ahora o tras una desvinculación. kubelatch te pide que lo confirmes antes, también en una cuenta que hoy está vinculada; por la API, el cambio responde 409 subject.email_autolinks hasta que lleva "confirm_autolink": true. Dar de alta a una persona con un correo no pregunta nada: eso es invitarla.
• Una dirección fuera de esos dominios se guarda tal cual: los avisos le llegan, pero no vincula ningún inicio de sesión OIDC, y el campo lo dice.
• Cambiar o quitar la dirección anula la invitación o el enlace de restablecimiento pendiente de la cuenta que salió por correo, a la dirección anterior; un enlace copiado se queda. El aviso al guardar lo dice. La auditoría guarda user.update, con la dirección de antes y la de después, y account_link.revoke cuando anuló un enlace.

Enlaces de restablecimiento y de vinculación¶

Ambos son la misma opción del menú de la ficha de la cuenta; valen 24 horas y son de un solo uso. Generarlo ya cierra las sesiones de esa persona y anula sus enlaces pendientes; con la cuenta deshabilitada, no se puede generar:

Con las Invitaciones por correo, «Restablecer acceso» abre un diálogo con las mismas dos opciones, un correo (24 horas) o un enlace para copiar, y pide confirmación porque cierra las sesiones de la persona. Una fila con una invitación enviada por correo dice «Invitación por correo · caduca en 2 d» y su menú ofrece «Reenviar invitación por correo» y «Copiar un enlace nuevo»; cualquiera de los dos anula el anterior.

Los casos concretos (contraseña olvidada, cuenta bloqueada, GitHub cambiado, identidad OIDC equivocada) están en Cuentas y recuperación.

Acceso¶

La columna «Acceso» dice qué tiene cada cuenta: de cuántos grupos es miembro y cuántos permisos directos tiene, por ejemplo 2 grupos · 1 directo. Las pertenencias y los permisos caducados no cuentan. La celda abre «Permisos» en «Por cuenta» con esa cuenta elegida. Una cuenta sin ninguna de las dos cosas muestra «sin acceso».

La ficha de la cuenta tiene una tarjeta «Accesos». Primero van sus grupos, una línea cada uno, como «Miembro de Backend», con enlace a la ficha del grupo, la caducidad de la pertenencia y un menú con «Ampliar la pertenencia» y «Sacar de Backend». Debajo, todos sus permisos en vigor por cluster, directos o por un grupo, así que la lista coincide con la cifra «Permisos activos». Cada uno es una línea de permiso con su menú y su casilla (Leer un permiso).

Estas opciones tratan el acceso:

Una cuenta deshabilitada conserva las dos listas, sin menús ni casillas, y no tiene las dos últimas opciones. Sus permisos van atenuados y no cuentan, así que la cifra los deja fuera.

Deshabilitar y habilitar¶

«Deshabilitar», el botón de la ficha de la cuenta o la opción de su menú de fila en «Usuarios» (persona o bot), tras confirmar:

• Revoca todas sus credenciales al instante: la siguiente petición recibe 401 y los exec o watch abiertos se cortan en menos de 10 s.
• Cierra sus sesiones y anula sus enlaces pendientes.
• En la siguiente reconciliación, la saca de la lista de sujetos que el proxy puede suplantar en cada cluster.

Sus permisos y sus pertenencias a grupos se conservan, pero no cuentan mientras esté deshabilitada. «Habilitar» la devuelve a los clusters sin volver a conceder nada. No resucita las credenciales ni los enlaces: hay que emitir o generar otros.

Para deshabilitar varias a la vez, márcalas en «Usuarios» (en «Todos», «Personas» o «Bots»; tu propia cuenta y las deshabilitadas no se pueden marcar) y elige «Deshabilitar N» en la barra. La confirmación enumera cada cuenta con lo que pierde y admite un motivo opcional, que queda en el registro de control. Es todo o nada, de hasta 500 a la vez: un lote que dejaría sin ningún administrador que pueda entrar se rechaza, nombra la cuenta y no cambia nada. Una cuenta ya deshabilitada cuenta como hecha. Las plazas que cuenta la edición se liberan al momento.

La interfaz no te deja deshabilitarte a ti mismo (la API sí, salvo que seas el último administrador que puede entrar). Cuando alguien deja la empresa, deshabilítalo el mismo día. Con GitHub, sacarlo de la organización basta: ver Login con GitHub. Con OIDC, deshabilitarlo en el proveedor no basta: solo impide su siguiente acceso, y su sesión web, su sesión de la CLI y sus credenciales duran hasta que caducan (Identidad con un proveedor OIDC).

Los sujetos no se borran nunca: deshabilitar es la baja.

Administradores¶

La columna «Rol» dice «Administrador» en quienes lo son. La ficha de la cuenta da o quita el rol en su menú, con «Hacer administrador» o «Quitar administrador»; ambos piden confirmación. El menú ofrece el primero solo en una cuenta habilitada, así que un administrador deshabilitado sí se puede degradar. La interfaz no te deja cambiar tu propio rol (la API sí, salvo que seas el último administrador que puede entrar). Al crear una persona, «Administrador» dice lo que implica marcarlo: podrá conceder cualquier acceso, emitir credenciales para cualquiera y gestionar cuentas. Un administrador ve en la barra lateral «Permisos», «Usuarios», «Grupos», «Roles» y «Credenciales» en «Acceso», «Auditoría» en «Registro», y «Clusters» y «CI» en «Plataforma», y «Avisos» en la barra superior.

kubelatch impide quitar el rol, deshabilitar, desvincular de GitHub o del proveedor OIDC, o desmarcar como break-glass al último administrador que puede entrar, y responde 409. «Puede entrar» significa: con contraseña, o, con GitHub u OIDC activado, con una cuenta break-glass, con GitHub vinculado mientras GitHub está activado o con una identidad del proveedor OIDC configurado mientras OIDC está activado.

Cerrar las sesiones web¶

«Cerrar las sesiones web», en el menú de la ficha de la cuenta o en su tarjeta «Entrada», cierra al momento todas las sesiones web de esa persona, tras confirmar. No revoca sus credenciales, y deja abiertas sus sesiones de la CLI, que también son credenciales: para eso, usa «Revocar» en «Credenciales» o deshabilítala. La tarjeta «Entrada» cuenta las sesiones de la CLI abiertas; las sesiones web son cookies firmadas que el servidor no lista, así que no puede contarlas.

Desvincular GitHub¶

Con GitHub activado, «Desvincular GitHub», en el menú de la ficha de la cuenta, separa la cuenta de su cuenta de GitHub y cierra sus sesiones. Hasta vincularla de nuevo con un «Enlace de vinculación», solo podrá entrar si es cuenta break-glass, o con el proveedor OIDC si tiene una identidad allí.

Úsalo cuando alguien se equivocó de cuenta de GitHub, o cuando al vincular sale github_taken (esa cuenta de GitHub ya está vinculada a otra persona).

Desvincular la identidad OIDC¶

Con OIDC activado, «Desvincular {name}», en el menú de la ficha de la cuenta, quita la identidad OIDC de la cuenta y cierra sus sesiones, tras confirmar en «Desvincular «ana@acme.com» de «ana»». El aviso dice «{name} desvinculado de «ana».». El menú solo lo ofrece en una cuenta vinculada al proveedor configurado. Su 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».

Úsalo cuando:

• la persona de la cuenta recibe identity_mismatch porque se volvió a crear su cuenta en el proveedor. Si, en cambio, su dirección de correo es ahora de otra persona, no desvincules: la cuenta sigue siendo de su dueño anterior, así que deshabilítala y crea otra para la persona nueva (Bajas y direcciones reutilizadas);
• al vincular sale oidc_taken: esa identidad ya abre otra cuenta de kubelatch, que desvinculas primero;
• la cuenta se vinculó a la persona equivocada: comprueba el correo en «Auditoría» (oidc.link) antes de desvincular.

Desvincular no revoca credenciales ni sesiones de la CLI: para cortarlo todo, deshabilita la cuenta. Cómo se vinculan las cuentas está en Login con OIDC (SSO).

Bots¶

Un bot es un sujeto sin contraseña ni sesión: solo tiene credenciales. Sirve para CI, Argo CD y cualquier automatización.

1. En «Usuarios», pulsa «Crear una cuenta» y elige «Tipo» → «Bot (CI, Argo CD…)».
2. Pon el nombre en «Login» (minúsculas, dígitos y guiones, de 1 a 63 caracteres) y, si quieres, un «Nombre» descriptivo.
3. Pulsa «Crear bot». El aviso ofrece «Abrir la ficha».
4. Concédele permisos en «Permisos», o añádelo a un grupo, como a cualquier sujeto.

Hay dos formas de darle credenciales:

• Desde GitHub Actions, sin secretos: una regla de confianza en «CI» (CI: reglas de confianza); la tarjeta «Reglas de CI» de la ficha del bot lista sus reglas y empieza una nueva.
• A mano: en «Credenciales», o en la tarjeta «Credenciales» de la ficha del bot, pulsa «Emitir una credencial», elige el bot en «Cuenta» (ya elegido si vienes de su ficha), pon «Nombre» (obligatorio), «Duración» y, si quieres, un «Cluster» y una «Nota (opcional)», y pulsa «Emitir credencial». «Duración» empieza por la más corta de las que se ofrecen, y una línea bajo el formulario dice qué vas a emitir. El token y el kubeconfig se muestran una sola vez. Toda credencial caduca: para un bot, como mucho a los 90 días (KUBELATCH_MAX_TTL_BOT).

Guarda el kubeconfig en el gestor de secretos de la herramienta que lo use y apunta en tu calendario su caducidad. «Credenciales» lista primero la caducidad más cercana y la pinta en ámbar con 7 días o menos, y en rojo con menos de 24 horas; la barra lateral marca «Credenciales» con los mismos recuentos, como hace Permisos. Las sesiones de la CLI se sustituyen con el siguiente kubelatch login y las credenciales de GitHub Actions se emiten de nuevo en cada ejecución, así que ni las marcas ni los chips «caducan hoy» y «esta semana» las cuentan. Emitir una credencial exige que el bot tenga al menos un permiso activo.

Para un agente de IA, la ficha del bot tiene una tarjeta «Agente de IA»: el interruptor «Las escrituras piden aprobación» (si sus escrituras esperan la aprobación de un administrador; cambiarlo pide confirmación), «Conectar un agente», con los comandos para conectarlo, y «Sesiones de este bot» (Agentes de IA).

Un bot comprometido: revoca sus credenciales en «Credenciales» o deshabilítalo, que las revoca todas y lo saca de los clusters. «Restablecer acceso» y «Cerrar las sesiones web» no se aplican a bots: su ficha no tiene menú, solo «Deshabilitar».

Buscar, leer y revocar credenciales¶

«Credenciales» lista todas las credenciales emitidas, en «Activas», «Caducadas» y «Revocadas». Una frase arriba las cuenta («18 credenciales activas de 7 cuentas. 2 revocadas en los últimos 30 días.»), y unos chips cuentan las activas y filtran la lista: «1 caduca hoy» y «3 esta semana» (credenciales que terminan en menos de 24 horas o en 7 días o menos, como las cuenta la barra lateral: nunca una sesión de la CLI ni un token de CI), «5 sesiones de la CLI», «2 sin uso en 30 días» y «4 de bots». Pulsa un chip para ver lo que cuenta, pulsa varios para combinarlos y comparte la dirección de la página, que los conserva; un chip sin nada que contar no se dibuja, y pulsar uno devuelve la lista a «Activas». «Filtrar» busca por login, nombre, prefijo, cluster o un token entero. Una fila dice su cuenta, su nombre con su prefijo y su tipo («sesión de la CLI», o «token de CI · run 1234 · alice»), a qué llega, quién la emitió cuando no fue la propia cuenta, cuándo caduca y cuándo se usó por última vez. Una credencial sin cluster sigue a su cuenta: «Alcance» dice, por ejemplo, «2 clusters: kind-local · prod», o «ningún cluster todavía» mientras la cuenta no tiene permisos activos.

«Revocar» está en la fila de toda credencial activa. Pide un motivo, opcional, y corta el acceso al instante: la siguiente petición recibe 401 y los streams abiertos se cortan en menos de 10 s.

El nombre abre el detalle de la credencial en un panel: «Cuenta», «Tipo», «Estado» (en una revocada, cuándo, quién y por qué), «Emitida», «Prefijo» y «Nota»; «Alcance», con el rol y el ámbito de la cuenta en cada cluster al que llega; y «Uso», leído de la auditoría: «Último uso», «Última IP», «Último agente de usuario» y «Peticiones en 24 h». Al pie, «Revocar» (mientras está activa) y «Peticiones», que abre «Auditoría» solo con esa credencial. El menú de la fila ofrece «Ver detalle» y «Peticiones». Un enlace de otra página puede acotar la lista a una cuenta, un tipo o un cluster: una línea encima lo dice («Solo: …»), con «Ver todas». Las cifras de «Inicio» también enlazan aquí con los chips correspondientes pulsados: «Sin usar en 30 días» pulsa «sin uso en 30 días» (credenciales activas que no se han usado en los últimos 30 días, o que nunca se usaron y se crearon hace más de 30), y las credenciales de bots que acaban hoy pulsan «de bots» y «caduca hoy» a la vez (credenciales estándar con menos de 24 horas: nunca las sesiones de la CLI ni los tokens de CI, que se renuevan solos). Un chip pulsado deja la lista en «Activas», y «Limpiar» bajo un resultado vacío los levanta.

Localizar un token filtrado¶

Pega el token entero en «Filtrar». kubelatch lo busca en el servidor y abre el detalle de esa credencial, también si ya caducó o está revocada (con cuándo, quién y por qué), o responde «ninguna credencial de esta instancia coincide con ese token». Vale también para el token de una sesión de agente de IA, que ninguna lista muestra: su «Tipo» dice «Sesión de agente de IA». El token viaja en el cuerpo de una petición, nunca en una URL, y kubelatch ni lo guarda ni lo registra: el plano de control solo anota que alguien buscó uno y si coincidió (El plano de control), con un límite de 10 búsquedas por minuto e IP. Un trozo más corto, como el prefijo, solo filtra la lista.

Por API¶

Todo lo anterior existe en la API JSON, por ejemplo POST /api/subjects (con "kind":"bot" para un bot), POST /api/subjects/<id>/disable (POST /api/subjects/disable para varias), /enable, /logout y /reset-link, y DELETE /api/subjects/<id>/github u /oidc. La lista completa está en API HTTP.