En aquesta pàgina
4 min de lectura

Dia 15 - Registre OpenCloud: token Graph caducat i renovació automàtica

Un token Graph caducat va bloquejar el registre per email a KM0 Cloud; documentem la causa, la rotació segura del token register-api i els errors trobats en automatitzar la renovació.

Introducció

El dia 15 tornem a infraestructura operativa al projecte germà km0-opencloud. El 4 de juliol de 2026 un usuari va intentar registrar-se amb email i contrasenya a KM0 Cloud i va veure un error genèric. Google OAuth seguia funcionant. La causa: el token Graph de register-api havia caducat.

Al issue #17 vam implementar rotació manual, renovació automàtica segura i vam corregir dos defectes que el tester va trobar en validar l'script. Aquest article explica què va passar, per què importa i què ha quedat automatitzat.

Incident

Què va veure l'usuari

El formulari va mostrar el missatge genèric «No s'ha pogut crear el compte. Torna-ho a provar més tard.» sense indicar que el servei estava temporalment caigut. Més tard el mateix usuari va entrar amb Google OAuth sense problema.

  • Causa arrel: GRAPH_SERVICE_APP_TOKEN de register-api caducat o invàlid; Graph rebutjava les credencials.
  • Evidència: GET /health retornava graph_auth_ok: false; POST /api/register responia HTTP 503.
  • OAuth intacte: l'accés amb Google usa Dex + OIDC, no register-api; un camí funcionava i l'altre no.
  • Context previ: l'issue #16 ja havia millorat els missatges d'error del formulari; aquest dia ataquem la causa operativa del 503.

Motiu

Per què register-api necessita un token

El registre email/contrasenya a KM0 Cloud passa per un sidecar, register-api, que crea usuaris via OpenCloud Graph (POST /graph/v1.0/users). En producció Graph no accepta Basic auth amb contrasenya; register-api s'ha d'autenticar amb un Graph App Token dedicat.

Secret operatiu

Aquest token és un secret amb data de caducitat. Si caduca i ningú el renova, el registre manual cau en silenci mentre OAuth segueix viu. Cal tractar-lo com a credencial d'infraestructura, no com a configuració «posar una vegada i oblidar».

Implementació

Rotació i auto-renovació (issue #17)

  • Política: token dedicat només per a register-api, caducitat de 3 mesos, renovació automàtica quan quedin menys de 14 dies.
  • setup-register-api-graph-token.sh: crea el token amb --expires-in 90d, escriu GRAPH_SERVICE_APP_TOKEN i GRAPH_SERVICE_APP_TOKEN_EXPIRES_AT a register-api/.env.
  • renew-register-api-graph-token.sh: comprova salut i data; renova si graph_auth_ok és false o falta marge; reinicia només register-api; verifica /health.
  • Cron: plantilla setmanal (dilluns 03:00 UTC) a register-api-token-renewal.cron.
  • Seguretat: el procés mai toca usuaris, volums, Dex/OIDC, bases de dades ni la resta del .env d'OpenCloud.

Errors trobats

El que va fallar en provar l'automatització

La primera versió de l'script de renovació va passar proves manuals bàsiques, però el tester va trobar dos defectes en executar escenaris reals de cron i renovació forçada.

  • Usuari Graph incorrecte: l'script de renovació no propagava GRAPH_SERVICE_USER des de register-api/.env. El setup generava el token per a l'usuari per defecte (admin) en lloc de l'operador configurat. Fix: llegir GRAPH_SERVICE_USER del .env i passar-lo amb --user al setup.
  • Carrera després del reinici: verify-register-api.sh s'executava immediatament després de docker compose up i fallava perquè register-api encara no havia arrencat del tot. Fix: espera activa fins a 30 s (REGISTER_API_HEALTH_WAIT_SEC) comprovant graph_auth_ok: true abans de verificar.

Després d'aquests canvis, els escenaris de «skip», renovació forçada i llindar de 7 dies van sortir amb exit code 0 i graph_auth_ok: true.

Límits

Què mai ha de fer la renovació

Documentem límits explícits al runbook de km0-opencloud perquè un script automatitzat no pugui danyar producció.

  • No executar docker compose down -v, docker volume rm ni comandes de reset d'usuaris OpenCloud.
  • No modificar Dex, OIDC, emmagatzematge, bases de dades ni grups existents.
  • Només actualitzar el token de register-api, reiniciar aquest contenidor i comprovar salut.
  • Si la renovació falla, Google OAuth i les dades d'usuaris existents queden intactes.

KM0

Per què ho expliquem al blog

KM0 promet serveis propers i operables: cloud, correu i web sota el teu control. Un token caducat és un recordatori que l'operació importa tant com el desplegament.

  • Transparència: si el registre email falla, ara hi ha missatges tipats (issue #16) i procediment de rotació documentat.
  • Automatització segura: renovació setmanal amb abast mínim, no «scripts heroics» que reinicien tot el stack.
  • Sèrie: el dia 14 parlava d'IA i burocràcia; aquí la burocràcia és un token amb data de caducitat i un cron que el renova abans que l'usuari ho noti.

Verificació

Comprovar el registre

  1. Salut: els operadors poden executar ./scripts/verify-register-api.sh a km0-opencloud i confirmar graph_auth_ok: true.
  2. Registre: provar registre email/contrasenya o entrar amb Google si ja tens compte.
  3. Sèrie: llegir el dia 14 (Harari i IA) i el dia 11 (KM0 Mail).
  4. Idees: explica'ns per formulari d'idees o contacte si vols més entrades sobre operació de KM0 Cloud.

Sèrie

Dies anteriors

El dia 14 va resumir el vídeo de Harari sobre IA i civilització; el dia 13 el meet 6 sobre visibilitat; el dia 11 va documentar KM0 Mail. El dia 16 anuncia la trobada a El Masnou sobre IA, burocràcia i Palantir. Segueix la sèrie i prova KM0 Cloud quan vulguis.