Go + Keycloak

Aprende a proteger aplicaciones Go con Keycloak construyendo, lección a lección, una tienda con login, una API protegida con JWT, un servicio interno y una herramienta de administración. Después la conectas a directorios corporativos, la reorganizas para probarla, le añades un segundo factor y la despliegas como en producción.

De qué trata el curso

El problema: cada aplicación con su propio login

Casi toda aplicación necesita saber quién la usa y qué puede hacer cada persona. La forma ingenua es que cada una lo resuelva por su cuenta: su tabla de usuarios, sus contraseñas (bien guardadas, con hash), su pantalla de login, su «olvidé mi contraseña», su bloqueo tras varios intentos fallidos… Y luego llegan las peticiones de verdad: un segundo factor para los administradores, que los empleados entren con su cuenta de la empresa, que quien inicia sesión en una aplicación no tenga que volver a hacerlo en la siguiente, que al dar de baja a alguien pierda el acceso a todo a la vez.

Hacer todo eso bien es mucho trabajo, es fácil equivocarse y es exactamente igual en todas las aplicaciones. Por eso existe un tipo de programa dedicado solo a ello: el servidor de identidad.

Keycloak: el que decide quién es quién

Keycloak es un servidor de identidad de código abierto. Se instala una vez y todas tus aplicaciones lo usan: él muestra la pantalla de login, guarda las contraseñas, pide el segundo factor, gestiona usuarios, grupos y roles, y se conecta a lo que ya tenga la empresa (Active Directory, Microsoft Entra ID, Google…). Cuando alguien demuestra quién es, Keycloak le entrega un token: un documento firmado digitalmente que dice quién es, qué roles tiene y hasta cuándo vale.

Una forma sencilla de imaginarlo es un hotel. Keycloak es la recepción: comprueba tu identidad una vez y te da una tarjeta. Tus aplicaciones son las puertas: no te vuelven a pedir el pasaporte, solo leen la tarjeta y comprueban tres cosas: que es auténtica (la firma), que no ha caducado y que es para esa puerta. Si pierdes el derecho a entrar, recepción deja de renovarte la tarjeta.

Para que recepción y puertas se entiendan, Keycloak usa dos estándares abiertos: OAuth 2.0 (cómo se piden y se usan los tokens) y OpenID Connect (cómo se identifica a la persona). Al ser estándares, lo que aprendas aquí te sirve también con otros proveedores, como Entra ID, Auth0 u Okta.

Go: las puertas

Tus programas en Go no gestionan contraseñas ni usuarios: hablan con Keycloak y confían en sus tokens. El trabajo se reparte así:

Go encaja muy bien en este papel. La biblioteca estándar (net/http) basta para escribir webs y APIs; dos librerías pequeñas y muy usadas, go-oidc y golang.org/x/oauth2, resuelven el protocolo; y validar un token es una operación local y rápida, así que tu API no depende de Keycloak en cada petición. El resultado son programas sencillos de leer y de desplegar.

Cómo lo vas a aprender

No es un catálogo de opciones de Keycloak, sino un proyecto que crece: una pequeña tienda online escrita en Go. Empiezas con lo mínimo (un Keycloak en Docker y un programa que lo consulta) y en cada lección añades una pieza real: el login de la web, una API protegida, un servicio interno que factura, una herramienta de administración, los usuarios del Active Directory de una empresa, un segundo factor para lo delicado… hasta desplegarla con HTTPS como en producción.

Todo lo que ves está probado: el código compila, los comandos se han ejecutado y las salidas son reales. Cuando algo no funcionaba como esperábamos, la lección lo cuenta, porque esas trampas son justo las que te encontrarás en un proyecto de verdad. Al terminar sabrás tanto el cómo como el por qué de cada pieza.

Lo que no es: un curso de Go desde cero (se asume lo básico) ni de administración avanzada de Keycloak (clústeres, temas visuales, ajuste fino del servidor). Es lo que necesita quien programa en Go para integrar Keycloak bien.

Qué vas a construir

Una pequeña tienda online formada por varios programas Go que confían en Keycloak para saber quién es cada usuario o servicio y qué puede hacer:

Mapa del curso

Cómo usar el curso

El código vive junto a este sitio, en la carpeta tienda/. Es un único proyecto que crece: cada lección indica en qué carpeta pasos/paso-NN está su estado final, que es una copia completa y compilable, con su propio infra/ (Keycloak y el realm de ese paso).

course/
├─ site/                  ← este sitio (ábrelo con doble clic en index.html)
└─ tienda/
   └─ pasos/
      ├─ paso-02/         ← Keycloak + realm + primer programa Go
      │  ├─ go.mod
      │  ├─ cmd/discover/
      │  └─ infra/        ← docker-compose.yml y realm/tienda-realm.json
      ├─ paso-03/         ← tienda-web: login con PKCE
      ├─ paso-04/         ← tienda-web: refresh y logout
      ├─ paso-05/         ← api-pedidos: middleware JWT
      ├─ paso-06/         ← roles y scopes
      ├─ paso-07/         ← facturacion: Client Credentials
      ├─ paso-08/         ← Token Exchange
      ├─ paso-09/         ← CLI de administración (gocloak)
      ├─ paso-10/         ← aprovisionador del realm
      ├─ paso-11/         ← usuarios de Active Directory (AD de prueba incluido)
      ├─ paso-12/         ← entrar con la cuenta de la empresa (brokering)
      ├─ paso-13/         ← api-pedidos en arquitectura hexagonal
      ├─ paso-14/         ← tests (y uno con Keycloak real)
      ├─ paso-15/         ← segundo factor para gestionar (step-up)
      ├─ paso-16/         ← lo mismo, más infra/produccion (TLS, imagen optimizada)
      └─ anexo-a/         ← el login con zitadel/oidc (módulo aparte)

Para leer con más espacio, oculta el índice con el botón ☰ de la barra superior o con la tecla [; el curso recuerda tu elección.

Cada lección sigue la misma estructura:

1. En este capítulo y objetivos: qué vas a tocar y qué sabrás al terminar.
2. Teoría justa con un diagrama del flujo.
3. Práctica paso a paso, con el código completo.
4. Ejercicios con la solución desplegable (intenta resolverlos antes de abrirla).
5. Errores comunes: el mensaje que verás, por qué ocurre y cómo arreglarlo.

Requisitos

Convenciones del curso

Puertos

Usuarios de prueba