المصادقة باستخدام Keycloak

كيف يستخدم Agent-Lab خدمة Keycloak

تتولى Keycloak إدارة المصادقة والتفويض عبر OpenID Connect. عندما تكون قيمة auth.enabled هي true (راجع مرجع الإعدادات):

• يتحقق الوسيط (middleware) في FastAPI من رموز bearer مقابل JWKS الخاص بالـ realm في كل طلب، مع الاستثناءات القياسية (/auth/*، و/status/*، و/docs، و/openapi.json، و/mcp، و/static)؛
• يوفّر الموجّه /auth تسجيل الدخول والتجديد والملف الشخصي ونقطة نهاية لتبادل الرموز مع Microsoft Entra ID؛
• يصادق خادم MCP العملاء عبر وكيل OAuth (OAuth proxy) يعتمد على الـ realm نفسه، وينشر نقاط نهاية البيانات الوصفية القياسية .well-known.

إعداد realm وعميل وحساب خدمة

تستخدم الخطوات أدناه واجهة Keycloak Admin API. اضبط أولاً بيانات اعتماد المسؤول ونقطة النهاية:

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

أنشئ realm (استبدل <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}'

أنشئ عميلاً لـ 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"
  }'

احصل على سر العميل:

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

تُربط هذه القيم بمفاتيح الإعدادات auth.* (auth.url، وauth.realm، وauth.client_id، وauth.client_secret) — خزّنها في حمولة Vault وفق مرجع الإعدادات.

أنشئ مستخدماً لحساب الخدمة:

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

اضبط الأدوار والـ mappers بدقة من واجهة Keycloak عند الحاجة.

إصدار الرموز المميزة والتحقق منها

احصل على رمز مستخدم (منح كلمة المرور password grant — وهو التدفق نفسه الذي ينفّذه POST /auth/login على جانب التطبيق):

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

تُجدَّد الرموز عبر POST /auth/renew، ويمكن مبادلة رموز المستخدمين المصادَق عليهم في Microsoft Entra ID برموز التطبيق عبر POST /auth/exchange (تدفق رمز التفويض مع PKCE، بالاعتماد على بيانات اعتماد Entra ID الموجودة في الإعدادات).

التجهيز المؤتمت

تتولى وحدة Terraform terraform/12_agent-lab-auth-realm/ (وهي جزء من دليل النشر) تجهيز الـ realm والعميل وحساب الخدمة في النشر المرجعي — استخدمها في البيئات الفعلية بدلاً من الخطوات اليدوية.