OAuth2 y OIDC desde cero

Antes de escribir una línea de Go necesitas el vocabulario: quién participa, qué tokens existen, qué contiene un JWT y por qué el flujo de login tiene tantos pasos.

El problema que resuelve Keycloak

Imagina que cada programa de la tienda gestionara sus propios usuarios: tienda-web con su tabla de contraseñas, api-pedidos con otra, y el panel de administración con una tercera. Tendrías contraseñas repetidas, tres sitios que asegurar, tres formularios de login y ninguna forma sencilla de dar o quitar permisos.

La alternativa es delegar la identidad en un único servicio especializado, un proveedor de identidad (IdP). Keycloak es ese IdP: guarda usuarios y roles, muestra el formulario de login y entrega a las aplicaciones tokens firmados que dicen quién es el usuario y qué puede hacer. Las aplicaciones nunca ven la contraseña.

OAuth2 en una página

OAuth2 (RFC 6749) define cómo una aplicación obtiene un access token para llamar a una API en nombre de alguien. Participan cuatro roles; así se llaman en nuestra tienda:

Un mismo programa puede tener dos papeles: facturacion es client cuando pide pedidos a la API, y podría ser resource server de su propia API.

Qué añade OpenID Connect

OAuth2 por sí solo no dice quién es el usuario; solo entrega un permiso. OpenID Connect (OIDC) es una capa encima que estandariza la identidad:

• ID token: un JWT para la aplicación con la identidad del usuario (sub, nombre, email…).
• Scope openid: pedirlo convierte una petición OAuth2 en un login OIDC. Otros scopes estándar: profile, email.
• Endpoint userinfo: devuelve los datos del usuario a cambio de un access token.
• Descubrimiento: un documento JSON en /.well-known/openid-configuration con todas las URLs y capacidades del servidor. Las librerías de Go lo leen solas a partir de la URL del issuer.

Los tres tokens

En Keycloak los tres son JWT, pero el refresh token está firmado con una clave que solo conoce Keycloak: trátalo como un valor opaco, no lo leas ni lo valides tú.

Anatomía de un JWT

Un JWT (RFC 7519) son tres trozos en base64url separados por puntos: header.payload.firma. Este es un access token de ejemplo con exactamente los mismos claims que Keycloak 26.8 emite para ana en el realm tienda (IDs y firma inventados):

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlhxM20tZGVtbyJ9.eyJleHAiOjE3OTE1NDAzMDAsImlhdCI6MTc5MTU0MDAwMCwianRpIjoib25ydGFjOjJmNmIxYzBlLWRlbW8iLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvcmVhbG1zL3RpZW5kYSIsImF1ZCI6ImFjY291bnQiLCJzdWIiOiI3YzFkNWMyZS0xYjdlLTRiOGEtOWQzZS01ZjZhN2I4YzlkMGUiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJ0aWVuZGEtd2ViIiwic2lkIjoiYTFiMmMzZDQtZGVtbyIsImFjciI6IjEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiY2xpZW50ZSIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJkZWZhdWx0LXJvbGVzLXRpZW5kYSJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoib3BlbmlkIGVtYWlsIHByb2ZpbGUiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwibmFtZSI6IkFuYSBDbGllbnRlIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiYW5hIiwiZ2l2ZW5fbmFtZSI6IkFuYSIsImZhbWlseV9uYW1lIjoiQ2xpZW50ZSIsImVtYWlsIjoiYW5hQHRpZW5kYS50ZXN0In0.ZmlybWEtZGUtZWplbXBsby1uby12YWxpZGE

Decodificado, el header dice cómo está firmado y con qué clave:

{ "alg": "RS256", "typ": "JWT", "kid": "Xq3m-demo" }

Y el payload contiene los claims:

{
  "exp": 1791540300,
  "iat": 1791540000,
  "jti": "onrtac:2f6b1c0e-demo",
  "iss": "http://localhost:8080/realms/tienda",
  "aud": "account",
  "sub": "7c1d5c2e-1b7e-4b8a-9d3e-5f6a7b8c9d0e",
  "typ": "Bearer",
  "azp": "tienda-web",
  "sid": "a1b2c3d4-demo",
  "acr": "1",
  "realm_access": { "roles": ["cliente", "offline_access", "uma_authorization", "default-roles-tienda"] },
  "resource_access": { "account": { "roles": ["manage-account", "manage-account-links", "view-profile"] } },
  "scope": "openid email profile",
  "email_verified": true,
  "name": "Ana Cliente",
  "preferred_username": "ana",
  "given_name": "Ana",
  "family_name": "Cliente",
  "email": "ana@tienda.test"
}

Firma y JWKS

Keycloak firma con una clave privada del realm (por defecto RSA, RS256). Publica las claves públicas correspondientes en el endpoint JWKS (…/protocol/openid-connect/certs). El kid del header indica cuál de ellas usar. Validar un access token significa, como mínimo:

1. Buscar en el JWKS la clave con ese kid y verificar la firma.
2. Comprobar que alg es uno de los esperados (nunca none).
3. Comprobar iss (exacto), aud (contiene tu API) y exp (no caducado).
4. Solo entonces, leer roles y scopes para autorizar.

No lo programarás a mano: en la lección 5 go-oidc hará los pasos 1 a 3, incluida la caché de claves y su rotación.

Los flujos (grant types)

Un flujo es la forma de conseguir un token. Cada parte de la tienda usa uno distinto:

Authorization Code + PKCE, paso a paso

Es el flujo que hará tienda-web cuando ana pulse «Entrar». Parece largo, pero cada paso tiene un motivo:

El code viaja por el navegador (canal frontal) pero no sirve de nada sin el code_verifier y el secreto, que solo conoce el servidor de tienda-web. Los tokens llegan por el canal trasero (pasos 9–10) y nunca pasan por el navegador: este solo recibe una cookie de sesión.

Los endpoints de un realm de Keycloak

Todas las URLs cuelgan del issuer http://localhost:8080/realms/tienda:

En la lección 2 escribirás un programa Go que lee el documento de descubrimiento y muestra estas URLs.

Scopes y roles: no son lo mismo

• Un scope lo pide el client y limita lo que el token permite: «esta app quiere leer pedidos» (pedidos:leer).
• Un rol lo tiene el usuario y dice qué puede hacer él: «ana es cliente», «carlos es admin».

Lo que alguien puede hacer de verdad es la intersección: carlos es admin, pero si la app que usa solo obtuvo el scope de lectura, la API no debería dejarle borrar. Lo pondrás en práctica en la lección 6.

Ejercicios

package main

import (
	"encoding/base64"
	"encoding/json"
	"fmt"
	"log"
	"os"
	"strings"
)

// Uso: go run . <token>
// OJO: solo DECODIFICA; no verifica la firma. Nunca confíes en un token así.
func main() {
	if len(os.Args) != 2 {
		log.Fatal("uso: go run . <token>")
	}
	parts := strings.Split(os.Args[1], ".")
	if len(parts) != 3 {
		log.Fatalf("un JWT tiene 3 partes, este tiene %d", len(parts))
	}
	for i, name := range []string{"header", "payload"} {
		raw, err := base64.RawURLEncoding.DecodeString(parts[i])
		if err != nil {
			log.Fatalf("%s: %v", name, err)
		}
		var v map[string]any
		if err := json.Unmarshal(raw, &v); err != nil {
			log.Fatalf("%s: %v", name, err)
		}
		pretty, _ := json.MarshalIndent(v, "", "  ")
		fmt.Printf("== %s ==\n%s\n", name, pretty)
	}
}

package main

import (
	"crypto/rand"
	"crypto/sha256"
	"encoding/base64"
	"fmt"
)

func main() {
	// 1. code_verifier: 32 bytes aleatorios en base64url sin relleno = 43 caracteres.
	b := make([]byte, 32)
	rand.Read(b) // desde Go 1.24 nunca devuelve error
	verifier := base64.RawURLEncoding.EncodeToString(b)

	// 2. code_challenge = BASE64URL(SHA256(verifier))
	sum := sha256.Sum256([]byte(verifier))
	challenge := base64.RawURLEncoding.EncodeToString(sum[:])

	fmt.Println("code_verifier: ", verifier, len(verifier))
	fmt.Println("code_challenge:", challenge)
}

{"error":"invalid_grant","error_description":"PKCE code verifier not specified"}

Errores comunes