Lab 02 — Configuración de Realm y clientes¶

Objetivo: Crear y configurar los dos realms de referencia (realm-internal y realm-partners) con sus clientes OAuth2.

Duración estimada: 45-60 minutos

Prerrequisito: Lab 01 completado — plataforma instalada y verificada.

Contexto¶

La plataforma usa dos realms para aislar audiencias:

realm-internal: Empleados y sistemas internos.
realm-partners: Socios externos y sus servicios M2M.

Parte 1 — Crear realm-internal¶

Via Admin Console¶

Ir a http://localhost:8080/admin/ → Login como admin
Click en el selector de realm (esquina superior izquierda) → Create Realm

Configurar:

Realm name: realm-internal
Enabled: ✅

Click Create

Via Admin CLI¶

/opt/keycloak/bin/kcadm.sh config credentials \
  --server http://localhost:8080 \
  --realm master \
  --user admin \
  --password $KC_ADMIN_PASSWORD

/opt/keycloak/bin/kcadm.sh create realms \
  -s realm=realm-internal \
  -s enabled=true \
  -s displayName="Internal Realm" \
  -s bruteForceProtected=true \
  -s failureFactor=5 \
  -s waitIncrementSeconds=60 \
  -s accessTokenLifespan=300

Parte 2 — Crear realm-partners¶

/opt/keycloak/bin/kcadm.sh create realms \
  -s realm=realm-partners \
  -s enabled=true \
  -s displayName="Partners Realm" \
  -s bruteForceProtected=true \
  -s failureFactor=5 \
  -s accessTokenLifespan=300

Parte 3 — Crear cliente público (Authorization Code + PKCE)¶

Este cliente representa el portal web de partners (SPA o BFF).

Via Admin Console¶

En realm-partners → Clients → Create client

Configurar:

Client ID: partner-portal-app
Client type: OpenID Connect

Click Next

En Capability config:

Standard flow: ✅
Direct access grants: ❌ (deshabilitado en producción)
Client authentication: ❌ (público)

Click Next

En Login settings:

Valid redirect URIs: http://localhost:3000/callback
                     https://app.example.com/callback
Web origins: http://localhost:3000
             https://app.example.com

Click Save

Via Admin CLI¶

/opt/keycloak/bin/kcadm.sh create clients \
  -r realm-partners \
  -s clientId=partner-portal-app \
  -s name="Partner Portal App" \
  -s enabled=true \
  -s publicClient=true \
  -s standardFlowEnabled=true \
  -s directAccessGrantsEnabled=false \
  -s 'redirectUris=["http://localhost:3000/callback","https://app.example.com/callback"]' \
  -s 'webOrigins=["http://localhost:3000","https://app.example.com"]' \
  -s 'attributes={"pkce.code.challenge.method":"S256"}'

Parte 4 — Crear cliente confidencial M2M (Client Credentials)¶

/opt/keycloak/bin/kcadm.sh create clients \
  -r realm-partners \
  -s clientId=partner-service-m2m \
  -s name="Partner Service M2M" \
  -s enabled=true \
  -s publicClient=false \
  -s serviceAccountsEnabled=true \
  -s standardFlowEnabled=false \
  -s directAccessGrantsEnabled=false

# Obtener el ID del cliente para asignar roles
CLIENT_UUID=$(/opt/keycloak/bin/kcadm.sh get clients \
  -r realm-partners \
  --fields id,clientId | jq -r '.[] | select(.clientId=="partner-service-m2m") | .id')

echo "Client UUID: $CLIENT_UUID"

Parte 5 — Crear roles en realm-partners¶

# Crear roles de realm
/opt/keycloak/bin/kcadm.sh create roles \
  -r realm-partners \
  -s name=partner-admin \
  -s description="Administrador de partners"

/opt/keycloak/bin/kcadm.sh create roles \
  -r realm-partners \
  -s name=partner-reader \
  -s description="Lectura de datos de partners"

/opt/keycloak/bin/kcadm.sh create roles \
  -r realm-partners \
  -s name=api:read \
  -s description="Lectura de API"

/opt/keycloak/bin/kcadm.sh create roles \
  -r realm-partners \
  -s name=api:write \
  -s description="Escritura en API"

# Asignar roles al service account del cliente M2M
/opt/keycloak/bin/kcadm.sh add-roles \
  -r realm-partners \
  --uusername service-account-partner-service-m2m \
  --rolename api:read \
  --rolename api:write

Parte 6 — Crear usuario de prueba¶

/opt/keycloak/bin/kcadm.sh create users \
  -r realm-partners \
  -s username=test.partner \
  -s email=test.partner@example.com \
  -s firstName=Test \
  -s lastName=Partner \
  -s enabled=true \
  -s emailVerified=true

# Asignar contraseña temporal
/opt/keycloak/bin/kcadm.sh set-password \
  -r realm-partners \
  --username test.partner \
  --new-password "Test123!" \
  --temporary false

# Asignar rol
/opt/keycloak/bin/kcadm.sh add-roles \
  -r realm-partners \
  --uusername test.partner \
  --rolename partner-reader

Parte 7 — Verificar con curl¶

Verificar Client Credentials¶

# Obtener secret del cliente M2M
CLIENT_SECRET=$(/opt/keycloak/bin/kcadm.sh get clients/$CLIENT_UUID/client-secret \
  -r realm-partners | jq -r '.value')

# Obtener token
TOKEN=$(curl -s -X POST \
  http://localhost:8080/realms/realm-partners/protocol/openid-connect/token \
  -d "grant_type=client_credentials" \
  -d "client_id=partner-service-m2m" \
  -d "client_secret=${CLIENT_SECRET}" | jq -r '.access_token')

echo "Token obtenido: ${TOKEN:0:50}..."

# Decodificar roles del token
echo $TOKEN | cut -d. -f2 | base64 -d 2>/dev/null | jq '.realm_access.roles'
# Esperado: ["api:read", "api:write"]

Checklist de validación¶

realm-internal creado y habilitado
realm-partners creado y habilitado
Cliente partner-portal-app (public) creado en realm-partners
Cliente partner-service-m2m (confidential) creado en realm-partners
Roles api:read y api:write creados en realm-partners
Service account de M2M tiene los roles asignados
Usuario test.partner creado con rol partner-reader
Token M2M obtenido correctamente con curl
Token decodificado contiene los roles correctos

Siguiente paso¶

Lab 03 — Resource Server con Spring Boot 4