Authentification avec Keycloak

Comment Agent-Lab utilise Keycloak

Keycloak gère l'authentification et l'autorisation via OpenID Connect. Lorsque auth.enabled vaut true (voir la Référence de configuration) :

• le middleware FastAPI valide les jetons bearer à l'aide du JWKS du realm à chaque requête, avec les exclusions habituelles (/auth/*, /status/*, /docs, /openapi.json, /mcp, /static) ;
• le routeur /auth expose la connexion, le renouvellement, le profil ainsi qu'un point de terminaison d'échange Microsoft Entra ID ;
• le serveur MCP authentifie les clients via un proxy OAuth adossé au même realm, en publiant les points de terminaison de métadonnées .well-known standard.

Configurer un realm, un client et un compte de service

Les étapes ci-dessous utilisent l'API d'administration de Keycloak. Définissez d'abord vos identifiants administrateur et le point de terminaison :

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')

Créez un realm (remplacez <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}'

Créez un client pour 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"
  }'

Récupérez le secret du client :

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')

Ces valeurs correspondent aux clés de configuration auth.* (auth.url, auth.realm, auth.client_id, auth.client_secret) — stockez-les dans la charge utile Vault conformément à la Référence de configuration.

Créez un utilisateur de compte de service :

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}]
  }'

Affinez les rôles et les mappers dans l'interface de Keycloak si nécessaire.

Émettre et vérifier des jetons

Obtenez un jeton utilisateur (password grant — le même flux que celui exécuté par POST /auth/login côté application) :

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

Les jetons se renouvellent via POST /auth/renew, et les utilisateurs authentifiés dans Microsoft Entra ID peuvent être échangés contre des jetons de l'application via POST /auth/exchange (flux authorization code avec PKCE, s'appuyant sur les identifiants Entra ID définis dans la configuration).

Provisionnement automatisé

Le module Terraform terraform/12_agent-lab-auth-realm/ (qui fait partie du guide de déploiement) provisionne le realm, le client et le compte de service pour le déploiement de référence — utilisez-le dans les environnements réels plutôt que les étapes manuelles.