Saltar al contenido
devjose↗FRONTEND ENGINEER · LIMA, PE
TrabajoSobre míExperienciaBlogHablemos
Inicio/Blog

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.

Por José Manrique · 26 de agosto de 2026

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ónLo que hicimosPor qué
Roles en el realmSolo "alumno" y "docente"Los roles finos (puede calificar, puede ver reportes) cambian más seguido que el ciclo de despliegue de Keycloak
Permisos finosSe resuelven en el backend con esos dos roles como baseEvita 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é:

  • Adaptador JavaScript oficial de Keycloak
  • Middleware en Next.js App Router

Sigue leyendo

Construir un asistente educativo con AWS Bedrock Agents: lo que aprendí con Unibot ↗Arquitectura por eventos en AWS: lo que aprendí armando un sistema de agendamiento ↗Todos los artículos
devjose↗

© 2026 José Manrique

BlogGitHub LinkedIn PrivacidadTérminosArriba ↑