Authentifizierung mit Keycloak

Wie Agent-Lab Keycloak verwendet

Keycloak verwaltet Authentifizierung und Autorisierung über OpenID Connect. Wenn auth.enabled auf true steht (siehe die Konfigurationsreferenz):

• validiert die FastAPI-Middleware bei jedem Request Bearer-Tokens gegen die JWKS des Realms, mit den üblichen Ausnahmen (/auth/*, /status/*, /docs, /openapi.json, /mcp, /static);
• stellt der /auth-Router Endpoints für Login, Erneuerung, Profil und einen Token-Austausch mit Microsoft Entra ID bereit;
• authentifiziert der MCP-Server Clients über einen OAuth-Proxy, der auf demselben Realm basiert, und veröffentlicht die standardmäßigen .well-known-Metadaten-Endpoints.

Realm, Client und Service-Account konfigurieren

Die folgenden Schritte verwenden die Keycloak Admin API. Legen Sie zunächst Ihre Admin-Zugangsdaten und den Endpoint fest:

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

Einen Realm erstellen (ersetzen Sie <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}'

Einen Client für Agent-Lab erstellen:

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

Das Client-Secret abrufen:

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

Diese Werte entsprechen den Konfigurationsschlüsseln auth.* (auth.url, auth.realm, auth.client_id, auth.client_secret) – speichern Sie sie gemäß der Konfigurationsreferenz in der Vault-Payload.

Einen Service-Account-Benutzer erstellen:

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

Rollen und Mapper können Sie bei Bedarf in der Keycloak-UI feinjustieren.

Tokens ausstellen und prüfen

Ein Benutzer-Token abrufen (Password Grant – derselbe Flow, den POST /auth/login auf Anwendungsseite ausführt):

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

Tokens werden über POST /auth/renew erneuert, und für Benutzer, die in Microsoft Entra ID authentifiziert sind, können über POST /auth/exchange App-Tokens eingetauscht werden (PKCE-Authorization-Code-Flow, gestützt auf die Entra-ID-Zugangsdaten in der Konfiguration).

Automatisierte Bereitstellung

Das Terraform-Modul terraform/12_agent-lab-auth-realm/ (Teil des Deployment-Guides) stellt Realm, Client und Service-Account für das Referenz-Deployment bereit – verwenden Sie es in echten Umgebungen anstelle der manuellen Schritte.