DESARROLLO FRONTEND
Integrar Keycloak en un LMS con React y Next.js: guía desde la trinchera
Cómo integré Keycloak en el LMS de UTP con React y Next.js, y cómo resolví el refresh de token que fallaba en silencio y dejaba sesiones de alumno zombie.
TL;DR
Integré Keycloak en el LMS de UTP, construido con React y Next.js. La parte que casi nadie documenta bien es qué pasa con el refresh del token cuando mezclas Server Components con lógica que corre solo en el cliente, y cómo evitar que un alumno quede "logueado" en la UI pero con llamadas a la API fallando en silencio.
El caso: no es un SPA simple
La mayoría de tutoriales de Keycloak con React asumen un SPA puro, donde keycloak-js vive en el cliente de principio a fin. El LMS de UTP usa Next.js con partes en Server Components, así que necesitaba dos cosas resueltas por separado: el login interactivo en el navegador, y la validación del token en cada request al servidor para las rutas que sí necesitan datos en el servidor.
Inicialización en el cliente
'use client'
import Keycloak from 'keycloak-js'
import { createContext, useContext, useEffect, useState } from 'react'
const KeycloakContext = createContext<Keycloak | null>(null)
export function KeycloakProvider({ children }: { children: React.ReactNode }) {
const [keycloak, setKeycloak] = useState<Keycloak | null>(null)
useEffect(() => {
const kc = new Keycloak({
url: process.env.NEXT_PUBLIC_KEYCLOAK_URL,
realm: 'utp-class',
clientId: 'lms-frontend',
})
kc.init({ onLoad: 'check-sso', pkceMethod: 'S256' }).then(() => {
setKeycloak(kc)
})
}, [])
return <KeycloakContext.Provider value={keycloak}>{children}</KeycloakContext.Provider>
}
export const useKeycloak = () => useContext(KeycloakContext)
El refresh "silencioso" que falla callado
Keycloak renueva el token automáticamente si configuras onTokenExpired, pero si esa renovación falla (por ejemplo, la sesión en el servidor de Keycloak ya expiró), el callback simplemente no hace nada visible para el usuario. El alumno seguía viendo la interfaz del LMS como si estuviera dentro, pero cada llamada a la API devolvía 401. Lo resolví forzando un logout explícito cuando el refresh falla, en vez de dejarlo fallar en silencio:
kc.onTokenExpired = () => {
kc.updateToken(30).catch(() => {
kc.login() // fuerza reautenticación en vez de dejar la sesión "zombie"
})
}
Proteger rutas que corren en el servidor
Para las páginas que hacen fetch de datos en el servidor no puedo depender de keycloak-js, así que valido el token en el middleware antes de que la request llegue al Server Component:
export async function middleware(request: NextRequest) {
const token = request.cookies.get('kc_token')?.value
if (!token) {
return NextResponse.redirect(new URL('/login', request.url))
}
try {
await verifyKeycloakToken(token) // valida firma contra las JWKS del realm
return NextResponse.next()
} catch {
return NextResponse.redirect(new URL('/login', request.url))
}
}
export const config = { matcher: ['/curso/:path*', '/notas/:path*'] }
Roles de Keycloak vs roles de negocio
| Decisión | Lo que hicimos | Por qué |
|---|---|---|
| Roles en el realm | Solo "alumno" y "docente" | Los roles finos (puede calificar, puede ver reportes) cambian más seguido que el ciclo de despliegue de Keycloak |
| Permisos finos | Se resuelven en el backend con esos dos roles como base | Evita reconfigurar el realm cada vez que cambia una regla de producto |
Lo que le diría a alguien que empieza esto
No trates el token expirado como un evento raro: en un LMS donde los alumnos dejan una pestaña abierta toda una clase, va a pasar todo el tiempo. Diseña el flujo de renovación (y su fallo) antes de construir el resto de la integración.
¿Integraste Keycloak con App Router y tuviste que resolver el mismo problema del refresh silencioso? Cuéntame cómo lo hiciste tú.
Recursos que usé: