Segundo factor solo para lo delicado (step-up)

Pedir un código a cada cliente para comprar una taza es excesivo; no pedirlo para gestionar todos los pedidos, imprudente. Con step-up, carlos entra con su contraseña y solo cuando abre Admin se le pide el código de su móvil. La API decide cuándo hace falta; Keycloak, cómo se consigue.

1. El recorrido

2. Niveles de autenticación en Keycloak

cd tienda/pasos/paso-14/infra && docker compose down -v
cd ../../paso-15/infra && docker compose up -d

Un nivel (Level of Authentication, LoA) es un número; el claim acr del token lo nombra. El realm del paso define dos, con el atributo acr.loa.map: basico = 1 (contraseña) y reforzado = 2 (contraseña + código). El flujo de login del navegador se sustituye por uno con un subflujo por nivel:

{
  "alias": "nivel 2 - código",
  "description": "reforzado (LoA 2): además, un código de un solo uso (TOTP)",
  "providerId": "basic-flow",
  "topLevel": false,
  "builtIn": false,
  "authenticationExecutions": [
    {
      "requirement": "REQUIRED",
      "priority": 10,
      "autheticatorFlow": false,
      "userSetupAllowed": false,
      "authenticator": "conditional-level-of-authentication",
      "authenticatorConfig": "nivel 2"
    },
    {
      "requirement": "REQUIRED",
      "priority": 20,
      "autheticatorFlow": false,
      "userSetupAllowed": false,
      "authenticator": "auth-otp-form"
    }
  ]
}

{
  "alias": "nivel 2",
  "config": {
    "loa-condition-level": "2",
    "loa-max-age": "300"
  }
}

Para que carlos tenga ya un código, el realm le importa una credencial OTP (solo para el curso: en un sistema real cada persona la configura escaneando un QR). Puedes añadirla a tu app de autenticación como clave manual, de tipo «basada en tiempo»: MNQXE3DPOMWW65DQFVRXK4TTN4WTEMBSGY.

3. La API decide cuándo hace falta

«Gestionar pedidos de otros exige verificar la identidad hace poco» es una regla de la tienda, así que va en el dominio, y sin mencionar Keycloak: el Actor trae StrongAuth y el servicio devuelve un error nuevo, ErrStepUp.

// All devuelve todos los pedidos. Gestionar pedidos de otros exige una
// autenticación reforzada.
func (s *Service) All(ctx context.Context, a Actor) ([]Order, error) {
	if !a.Can(PermManage) {
		return nil, ErrForbidden
	}
	if !a.StrongAuth {
		return nil, ErrStepUp
	}
	return s.repo.List(ctx, Filter{})
}

Qué es «reforzado» lo decide el adaptador de Keycloak, y cómo se pide al cliente también: un 401 con error="insufficient_user_authentication" y acr_values, el reto de la RFC 9470 (OAuth 2.0 Step-Up Authentication Challenge).

// Package keycloak es el adaptador de identidad de api-pedidos: valida el
// access token (con apiauth) y traduce lo que dice Keycloak (roles de realm,
// roles de client, scopes) a lo que entiende el dominio (pedidos.Actor).
//
// Es el único sitio de api-pedidos que conoce los nombres de los roles. Si
// mañana el rol «admin» se llama «tienda-admin», o los permisos vienen de
// otro proveedor, solo cambia este archivo.
package keycloak

import (
	"fmt"
	"net/http"
	"time"

	"tienda/internal/apiauth"
	"tienda/internal/pedidos"
)

// StrongACR es el nivel de autenticación (claim acr) que el realm emite tras
// contraseña + código (acr.loa.map: "reforzado" = nivel 2, lección 15).
const StrongACR = "reforzado"

// StrongMaxAge es cuánto vale el segundo factor: igual que el Max Age del
// nivel 2 en el realm. Hace falta comprobarlo aquí porque los tokens
// renovados (refresh) conservan acr="reforzado" toda la sesión.
const StrongMaxAge = 5 * time.Minute

// Identity implementa rest.Identity con access tokens de Keycloak.
type Identity struct {
	Verifier *apiauth.Verifier
}

// Middleware exige un access token válido (401 si no lo hay).
func (i Identity) Middleware(next http.Handler) http.Handler { return i.Verifier.Middleware(next) }

// RequireScope exige un scope en el token (403 insufficient_scope si falta).
func (Identity) RequireScope(scope string) func(http.Handler) http.Handler {
	return apiauth.RequireScope(scope)
}

// StepUp responde 401 con el reto de RFC 9470: el token es válido, pero la
// operación necesita un login más fuerte; acr_values dice cuál pedir.
func (Identity) StepUp(w http.ResponseWriter) {
	w.Header().Set("WWW-Authenticate", fmt.Sprintf(
		`Bearer realm="api-pedidos", error="insufficient_user_authentication", `+
			`error_description="hace falta un segundo factor", acr_values=%q`, StrongACR))
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusUnauthorized)
	fmt.Fprintf(w, `{"error":"insufficient_user_authentication","error_description":"hace falta un segundo factor","acr_values":%q}`+"\n", StrongACR)
}

// Actor devuelve quién llama, ya en términos del dominio.
func (Identity) Actor(r *http.Request) pedidos.Actor {
	p := apiauth.FromContext(r.Context())
	if p == nil {
		return pedidos.Actor{}
	}
	return ActorFrom(p)
}

// ActorFrom traduce un token verificado a un Actor del dominio.
func ActorFrom(p *apiauth.Principal) pedidos.Actor {
	a := pedidos.Actor{
		ID:   p.Subject,
		Name: p.Username,
		// Reforzado = login con segundo factor y además reciente.
		StrongAuth: p.ACR == StrongACR && time.Since(p.AuthTime) <= StrongMaxAge,
	}
	if p.HasRole("cliente") || p.HasRole("admin") {
		a.Permissions = append(a.Permissions, pedidos.PermBuy)
	}
	if p.HasRole("admin") {
		a.Permissions = append(a.Permissions, pedidos.PermManage)
	}
	for _, r := range p.APIRoles { // roles de client de api-pedidos (servicios)
		if r == "facturar" {
			a.Permissions = append(a.Permissions, pedidos.PermInvoice)
		}
	}
	return a
}

REST solo añade una línea a su traducción de errores: ErrStepUp → h.id.StepUp(w). El puerto Identity gana el método StepUp, y el doble de los tests de la lección 14 también.

// writeError traduce los errores del dominio a respuestas HTTP.
func (h *handlers) writeError(w http.ResponseWriter, err error) {
	switch {
	case errors.Is(err, pedidos.ErrStepUp):
		h.id.StepUp(w) // 401 con el reto: cómo se pide lo sabe el adaptador de identidad
	case errors.Is(err, pedidos.ErrNotFound):
		jsonhttp.Error(w, http.StatusNotFound, "not_found", "pedido no encontrado")
	case errors.Is(err, pedidos.ErrForbidden):
		jsonhttp.Error(w, http.StatusForbidden, "forbidden", "no tienes permiso para esto")
	case errors.Is(err, pedidos.ErrInvalid):
		jsonhttp.Error(w, http.StatusBadRequest, "invalid_request", err.Error())
	default:
		jsonhttp.Error(w, http.StatusInternalServerError, "server_error", "error interno")
	}
}

4. tienda-web reacciona

El cliente de la API reconoce el reto y lo convierte en un error con nombre:

case http.StatusUnauthorized:
	if e.Code == "insufficient_user_authentication" {
		return fmt.Errorf("%w (acr_values=%s)", ErrStepUpRequired, e.ACR)
	}
	return fmt.Errorf("%w: %s", ErrUnauthorized, e.Description)

Y la página Admin, al recibirlo, manda a carlos a pedir ese nivel:

// admin lista todos los pedidos. No comprobamos aquí el rol: si el usuario no
// es admin, api-pedidos responde 403 y lo mostramos. El enlace del menú solo
// se ve para admins, pero quien decide de verdad es la API.
func (h *handlers) admin(w http.ResponseWriter, r *http.Request) {
	sess, tok, ok := h.apiToken(w, r, "%2Fadmin")
	if !ok {
		return
	}
	data := pageData{Active: "admin", Session: sess, Statuses: pedidos.Statuses}
	if id := r.URL.Query().Get("ok"); id != "" {
		data.Flash = "Pedido #" + id + " actualizado."
	}
	data.Error = errorMessage(r.URL.Query().Get("error"))
	orders, err := h.api.AllOrders(r.Context(), tok)
	if errors.Is(err, pedidosclient.ErrStepUpRequired) {
		// La API quiere un segundo factor: volvemos a Keycloak pidiéndolo.
		http.Redirect(w, r, "/login?acr=reforzado&next=%2Fadmin", http.StatusSeeOther)
		return
	}
	if err != nil {
		log.Printf("admin: %v", err)
		data.Error = errorMessage(errorCode(err))
	} else {
		data.Orders = orders
	}
	h.render(w, "admin.html", data)
}

/login?acr=reforzado añade acr_values a la petición de autorización (solo valores de una lista permitida, OIDC_ACR_VALUES, como en la lección 12). La parte importante está en el callback: acr_values viaja por el navegador y cualquiera puede quitarlo de la URL. La documentación de Keycloak recomienda comprobar el resultado, y lo hacemos:

// acr_values viaja por el navegador y alguien podría quitarlo de la URL:
// si pedimos un nivel, el ID token tiene que confirmarlo.
if p.acr != "" {
	var c struct {
		ACR string `json:"acr"`
	}
	if err := idToken.Claims(&c); err != nil || c.ACR != p.acr {
		log.Printf("login sin el nivel pedido: acr=%q, se esperaba %q", c.ACR, p.acr)
		http.Error(w, "el login no alcanzó el nivel de autenticación pedido", http.StatusUnauthorized)
		return
	}
}

Probado: seguimos la redirección de tienda-web a Keycloak quitando acr_values. Como carlos ya tenía sesión, Keycloak devolvió un código al momento… y tienda-web respondió 401 el login no alcanzó el nivel de autenticación pedido. Aunque se colara, la API seguiría diciendo que no: comprobar en los dos sitios no sobra.

5. Probarlo

Arranca api, web y facturacion del paso 15. Entra como carlos (carlos123) y abre Admin:

Durante los 5 minutos siguientes, Admin funciona sin más preguntas; después, la API vuelve a lanzar el reto y Keycloak vuelve a pedir el código. Comprar sigue como siempre: el dominio no pide segundo factor para los pedidos propios.

6. Lo que vimos probando

Ejercicios

func TestCambiarEstadoExigeSegundoFactor(t *testing.T) {
	sinFactor := carlos
	sinFactor.StrongAuth = false
	_, err := newService().SetStatus(context.Background(), sinFactor, 1002, "Enviado")
	if !errors.Is(err, pedidos.ErrStepUp) {
		t.Fatalf("err = %v, want ErrStepUp", err)
	}
}

Errores comunes