Autenticación con Keycloak

Cómo usa Agent-Lab Keycloak

Keycloak gestiona la autenticación y la autorización mediante OpenID Connect. Cuando auth.enabled vale true (consulta la Referencia de configuración):

• el middleware de FastAPI valida los tokens bearer contra el JWKS del realm en cada petición, con las exclusiones estándar (/auth/*, /status/*, /docs, /openapi.json, /mcp, /static);
• el router /auth expone endpoints de inicio de sesión, renovación, perfil y un endpoint de intercambio de Microsoft Entra ID;
• el servidor MCP autentica a los clientes mediante un proxy OAuth respaldado por el mismo realm y publica los endpoints de metadatos .well-known estándar.

Configurar un realm, un cliente y una cuenta de servicio

Los pasos siguientes utilizan la Admin API de Keycloak. Define primero tus credenciales de administrador y el endpoint:

export ADMIN_USER=<admin_username>
export ADMIN_PASS=<admin_password>
export ADMIN_TOKEN=$(curl -s -X POST "https://<auth_fqdn>/realms/master/protocol/openid-connect/token" \
    -d "username=${ADMIN_USER}&password=${ADMIN_PASS}&grant_type=password&client_id=admin-cli" | jq -r '.access_token')

Crea un realm (sustituye <realm_name>):

curl -X POST https://<auth_fqdn>/admin/realms \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -d '{"realm": "<realm_name>", "enabled": true}'

Crea un cliente para Agent-Lab:

curl -X POST https://<auth_fqdn>/admin/realms/<realm_name>/clients \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -d '{
    "clientId": "<client_name>",
    "enabled": true,
    "protocol": "openid-connect",
    "publicClient": false,
    "redirectUris": ["https://<agent_lab_fqdn>/*"],
    "standardFlowEnabled": true,
    "clientAuthenticatorType": "client-secret"
  }'

Obtén el secreto del cliente:

export CLIENT_ID=$(curl -X GET "https://<auth_fqdn>/admin/realms/<realm_name>/clients?clientId=<client_name>" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" | jq -r '.[0].id')

export CLIENT_SECRET=$(curl -X GET "https://<auth_fqdn>/admin/realms/<realm_name>/clients/${CLIENT_ID}/client-secret" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" | jq -r '.value')

Estos valores corresponden a las claves de configuración auth.* (auth.url, auth.realm, auth.client_id, auth.client_secret); guárdalos en la carga de Vault tal como se indica en la Referencia de configuración.

Crea un usuario de cuenta de servicio:

curl -X POST https://<auth_fqdn>/admin/realms/<realm_name>/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -d '{
    "username": "<username>",
    "enabled": true,
    "email": "<username>@example.com",
    "credentials": [{"type": "password", "value": "<user_password>", "temporary": false}]
  }'

Si es necesario, ajusta los roles y los mappers en la interfaz de Keycloak.

Emitir y verificar tokens

Obtén un token de usuario (password grant, el mismo flujo que POST /auth/login ejecuta en el lado de la aplicación):

export USER_TOKEN=$(curl -s -X POST https://<auth_fqdn>/realms/<realm_name>/protocol/openid-connect/token \
  -d "grant_type=password" \
  -d "client_id=<client_name>" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "username=<username>" \
  -d "password=<user_password>" | jq -r '.access_token')

curl -s https://<agent_lab_fqdn>/agents/list -H "Authorization: Bearer $USER_TOKEN" | jq

Los tokens se renuevan mediante POST /auth/renew, y los usuarios autenticados en Microsoft Entra ID pueden intercambiarse por tokens de la aplicación mediante POST /auth/exchange (flujo de código de autorización con PKCE, respaldado por las credenciales de Entra ID de la configuración).

Aprovisionamiento automatizado

El módulo de Terraform terraform/12_agent-lab-auth-realm/ (parte de la guía de despliegue) aprovisiona el realm, el cliente y la cuenta de servicio para el despliegue de referencia; úsalo en entornos reales en lugar de los pasos manuales.