En esta página
4 min de lectura

Día 15 - Registro OpenCloud: token Graph caducado y renovación automática

Un token Graph caducado bloqueó el registro por email en KM0 Cloud; documentamos la causa, la rotación segura del token register-api y los fallos que encontramos al automatizar la renovación.

Introducción

El día 15 volvemos a infraestructura operativa en el proyecto hermano km0-opencloud. El 4 de julio de 2026 un usuario intentó registrarse con email y contraseña en KM0 Cloud y vio un error genérico. Google OAuth seguía funcionando. La causa: el token Graph de register-api había caducado.

En el issue #17 implementamos rotación manual, renovación automática segura y corregimos dos defectos que el tester encontró al validar el script. Este artículo explica qué pasó, por qué importa y qué quedó automatizado.

Incidente

Qué vio el usuario

El formulario mostró el mensaje genérico «No se pudo crear la cuenta. Inténtalo de nuevo más tarde.» sin indicar que el servicio estaba temporalmente caído. Más tarde el mismo usuario entró con Google OAuth sin problema.

  • Causa raíz: GRAPH_SERVICE_APP_TOKEN de register-api caducado o inválido; Graph rechazaba las credenciales.
  • Evidencia: GET /health devolvía graph_auth_ok: false; POST /api/register respondía HTTP 503.
  • OAuth intacto: el login con Google usa Dex + OIDC, no register-api; por eso un camino funcionaba y el otro no.
  • Contexto previo: el issue #16 ya había mejorado los mensajes de error del formulario; este día atacamos la causa operativa del 503.

Motivo

Por qué register-api necesita un token

El registro email/contraseña en KM0 Cloud pasa por un sidecar, register-api, que crea usuarios vía OpenCloud Graph (POST /graph/v1.0/users). En producción Graph no acepta Basic auth con contraseña; register-api debe autenticarse con un Graph App Token dedicado.

Secreto operativo

Ese token es un secreto con fecha de caducidad. Si expira y nadie lo renueva, el registro manual se cae en silencio mientras OAuth sigue vivo. Hay que tratarlo como credencial de infraestructura, no como configuración «poner una vez y olvidar».

Implementación

Rotación y auto-renovación (issue #17)

  • Política: token dedicado solo para register-api, caducidad de 3 meses, renovación automática cuando queden menos de 14 días.
  • setup-register-api-graph-token.sh: crea el token con --expires-in 90d, escribe GRAPH_SERVICE_APP_TOKEN y GRAPH_SERVICE_APP_TOKEN_EXPIRES_AT en register-api/.env.
  • renew-register-api-graph-token.sh: comprueba salud y fecha; renueva si graph_auth_ok es false o falta margen; reinicia solo register-api; verifica /health.
  • Cron: plantilla semanal (lunes 03:00 UTC) en register-api-token-renewal.cron.
  • Seguridad: el proceso nunca toca usuarios, volúmenes, Dex/OIDC, bases de datos ni el resto del .env de OpenCloud.

Errores encontrados

Lo que falló al probar la automatización

La primera versión del script de renovación pasó las pruebas manuales básicas, pero el tester encontró dos defectos al ejecutar escenarios reales de cron y renovación forzada.

  • Usuario Graph incorrecto: el script de renovación no propagaba GRAPH_SERVICE_USER desde register-api/.env. El setup generaba el token para el usuario por defecto (admin) en lugar del operador configurado. Fix: leer GRAPH_SERVICE_USER del .env y pasarlo con --user al setup.
  • Carrera tras el reinicio: verify-register-api.sh se ejecutaba inmediatamente después de docker compose up y fallaba porque register-api aún no había arrancado del todo. Fix: espera activa hasta 30 s (REGISTER_API_HEALTH_WAIT_SEC) comprobando graph_auth_ok: true antes de verificar.

Tras estos cambios, los escenarios de «skip», renovación forzada y umbral de 7 días salieron con exit code 0 y graph_auth_ok: true.

Límites

Qué nunca debe hacer la renovación

Documentamos límites explícitos en el runbook de km0-opencloud para que un script automatizado no pueda dañar producción.

  • No ejecutar docker compose down -v, docker volume rm ni comandos de reset de usuarios OpenCloud.
  • No modificar Dex, OIDC, almacenamiento, bases de datos ni grupos existentes.
  • Solo actualizar el token de register-api, reiniciar ese contenedor y comprobar salud.
  • Si la renovación falla, Google OAuth y los datos de usuarios existentes quedan intactos.

KM0

Por qué lo contamos en el blog

KM0 promete servicios cercanos y operables: cloud, mail y web bajo tu control. Un token caducado es un recordatorio de que la operación importa tanto como el despliegue.

  • Transparencia: si el registro email falla, ahora hay mensajes tipados (issue #16) y procedimiento de rotación documentado.
  • Automatización segura: renovación semanal con alcance mínimo, no «scripts heroicos» que reinician todo el stack.
  • Serie: el día 14 hablaba de IA y burocracia; aquí la burocracia es un token con fecha de caducidad y un cron que la renueva antes de que el usuario lo note.

Verificación

Comprobar el registro

  1. Salud: operadores pueden ejecutar ./scripts/verify-register-api.sh en km0-opencloud y confirmar graph_auth_ok: true.
  2. Registro: probar registro email/contraseña o entrar con Google si ya tienes cuenta.
  3. Serie: leer el día 14 (Harari e IA) y el día 11 (KM0 Mail).
  4. Ideas: cuéntanos por formulario de ideas o contacto si quieres más entradas sobre operación de KM0 Cloud.

Serie

Días anteriores

El día 14 resumió el vídeo de Harari sobre IA y civilización; el día 13 el meet 6 sobre visibilidad; el día 11 documentó KM0 Mail. El día 16 anuncia el encuentro en Masnou sobre IA, burocracia y Palantir. Sigue la serie y prueba KM0 Cloud cuando quieras.