Keycloak · Realm fastfood (roles, clientes y pruebas)

Servidor: srv-app-01 (Keycloak 24)
URL Admin: https://auth.erre.com/
Objetivo: Dejar listo el realm fastfood con roles, clientes (web y api) y pruebas de token.

---

1. Prerrequisitos

• Reverse proxy + HTTPS operativos para auth.erre.com.
• Acceso a la consola de administración (usuario admin ya creado).
• Para pruebas locales, /etc/hosts del cliente: auth.erre.com api.erre.com app.erre.com

---

2. Crear el realm y roles

1. Entra a Administration Console → Create realm → Name: fastfood.
2. En fastfood → Realm roles → Create role:
3. ROLE_USER
4. ROLE_ADMIN

---

3. Cliente web-fastfood (frontend)

1. Clients → Create client
   • Client type: OpenID Connect
   • Client ID: web-fastfood → Next
2. Login settings
   • Client authentication: OFF (cliente público)
   • Standard Flow: ON (Authorization Code)
   • Direct access grants: OFF
   • Implicit flow: OFF
   • PKCE: Required
   • Valid redirect URIs:
     • https://app.erre.com/*
     • http://localhost:3000/* (opcional dev)
   • Web origins:
     • https://app.erre.com
     • http://localhost:3000 (opcional dev)
   • Home URL: https://app.erre.com/

Resultado: los tokens del front incluirán aud: ["api-fastfood"], que tu API verificará.

---

4. Cliente api-fastfood (backend)

Recomendado: Confidential + Service Accounts 1. Clients → Create client
* Client ID: api-fastfood → Next
* Client authentication: ON
* Standard flow: OFF
* Direct access grants: OFF
* Service accounts: ON → Save 2. Credentials → copia el Client secret y guárdalo en secreto (no subir a repos públicos).

Nota: si tu framework no necesita “bearer-only”, no lo marques; con validar firma, iss y aud basta.

---

5. Usuario de prueba

1. Users → Add user → tester
2. Credentials → setea contraseña (sin “Change on first login” para pruebas).
3. Role mappings → asigna ROLE_USER (y ROLE_ADMIN si aplica).

---

6. Endpoints útiles

• Issuer (realm):
  https://auth.erre.com/realms/fastfood
• OpenID Configuration:
  https://auth.erre.com/realms/fastfood/.well-known/openid-configuration
• JWKS (clave pública para verificar JWT):
  https://auth.erre.com/realms/fastfood/protocol/openid-connect/certs

---

7. Pruebas rápidas

1. Token client_credentials (M2M) para api-fastfood

2. Ejecutar desde una máquina que resuelva auth.erre.com (local):

   curl -s -X POST \
   -H 'Content-Type: application/x-www-form-urlencoded' \
   -d 'grant_type=client_credentials' \
   -d 'client_id=api-fastfood' \
   -d 'client_secret=SECRETO' \
   https://auth.erre.com/realms/fastfood/protocol/openid-connect/token | jq .
   

3. Verifica que el access_token tenga:

   iss = https://auth.erre.com/realms/fastfood

   aud contenga api-fastfood

   exp válido

4. Flujo Authorization Code + PKCE (frontend) Config recomendada del front (ej. React/Vite):

   authority / issuer: https://auth.erre.com/realms/fastfood

   client_id: web-fastfood

   redirect_uri: https://app.erre.com/callback

   response_type: code

   scope: openid profile email roles

   pkce: S256

---

8. Backup del realm (versionable)

• Úsalo para migrar o recuperar configuración. No publiques secretos en repos públicos.

  • Exportar a archivo dentro del contenedor

    docker exec keycloak /opt/keycloak/bin/kc.sh export \
    --realm fastfood \
    --users realm_file \
    --file /tmp/fastfood-realm.json
    

  • Copiar al host

    docker cp keycloak:/tmp/fastfood-realm.json /tmp/fastfood-realm.json
    

  • Guarda /tmp/fastfood-realm.json en un repo privado o cifrado (ej. sops).

  • Import (referencia): kc.sh import --file /ruta/fastfood-realm.json --realm fastfood