Taller OpenID Connect con Keycloak y Python (Flask)

Este proyecto es un ejemplo completo y didáctico de cómo implementar autenticación OpenID Connect (OIDC) usando:

• Keycloak como Proveedor de Identidad (IdP)
• Python + Flask como aplicación cliente (Relying Party)
• Authorization Code Flow + PKCE
• Logout local y logout completo (Front-channel logout)

Está pensado para talleres formativos, laboratorios o pruebas de concepto.

---

🧱 Arquitectura

┌──────────┐        ┌──────────────┐        ┌──────────────┐
│ Usuario  │───────▶│ Flask Server │───────▶│  Keycloak    │
│ Browser  │◀───────│  (RP)        │◀───────│  (OIDC IdP)  │
└──────────┘        └──────────────┘        └──────────────┘

Componentes:

• Keycloak: gestiona identidad, login y emisión de tokens
• Flask app: aplicación protegida por OIDC
• OIDCClient: librería Python que encapsula la lógica OIDC

---

📁 Estructura del proyecto

.
├── app/
│   └── server.py          # Aplicación Flask (Relying Party)
├── client.py              # Cliente OIDC (Authlib)
├── docker-compose.yml     # Keycloak
├── .env                   # Variables de entorno (NO commitear)
└── README.md

---

🚀 1. Levantar Keycloak

docker compose up -d

Acceso:

• URL: http://localhost:8080
• Usuario: admin
• Password: admin

---

🏗 2. Configurar Keycloak

2.1 Crear Realm

• Nombre: master (o uno nuevo si lo prefieres)

2.2 Crear cliente OIDC

• Client ID: python-app
• Client type: OpenID Connect
• Client authentication: Enabled
• Authorization Code Flow: Enabled
• PKCE: Required

URLs

• Redirect URI:

  http://localhost:5002/callback
  

• Post logout redirect URI:

  http://localhost:5002/
  

• Web origins:

  http://localhost:5002
  

2.3 Obtener credenciales

Desde la pestaña Credentials:

• CLIENT_ID
• CLIENT_SECRET

---

👤 3. Crear usuario de prueba

• Username: demo
• Password: demo123
• Password temporal: ❌

---

🔐 4. Configurar variables de entorno

Crear fichero .env:

ISSUER=http://localhost:8080/realms/master
CLIENT_ID=python-app
CLIENT_SECRET=PEGA_AQUI_EL_SECRET

---

🐍 5. Ejecutar la aplicación Python

5.1 Crear entorno virtual

python3 -m venv venv
source venv/bin/activate
pip install flask authlib requests python-dotenv

5.2 Ejecutar

python app/server.py

Acceder a:

http://localhost:5002

---

🔄 6. Flujo de autenticación

1. Usuario accede a /login
2. Redirección a Keycloak
3. Login del usuario
4. Keycloak devuelve authorization_code
5. Flask intercambia el código por tokens
6. Se valida el ID Token (JWT)
7. Se crea sesión local

---

🔍 7. Tokens utilizados

• ID Token

  • Identidad del usuario
  • Firmado por Keycloak
  • Validado con JWKS

• Access Token

  • Usado para /userinfo

---

🚪 8. Logout

8.1 Logout local

Endpoint:

/logout

• Limpia la sesión Flask
• ❌ No cierra sesión en Keycloak

---

8.2 Logout completo (Front-channel)

Endpoint:

/logout_full

Flujo:

1. Se obtiene id_token de la sesión
2. Se limpia sesión local
3. Redirección al endpoint de logout de Keycloak:

/protocol/openid-connect/logout

Parámetros usados:

• id_token_hint
• client_id
• post_logout_redirect_uri

Esto cierra la sesión del usuario tanto en la app como en Keycloak.

---

🔐 9. Seguridad destacada

✔ Authorization Code Flow
✔ PKCE
✔ Validación de firma JWT
✔ Validación de aud, exp
✔ Protección CSRF con state
✔ Separación cliente OIDC / aplicación

---

🧪 10. Casos de uso para talleres

• Explicar OAuth2 vs OIDC
• Analizar JWTs en vivo
• Mostrar JWKS y validación de firma
• Comparar logout local vs global
• Introducir conceptos enterprise (back-channel logout)

---