تكوين Keycloak v26 باستخدام Nginx Reverse Proxy في Docker: حل مشكلات وحدة التحكم في المجالات المختلفة

التغلب على أخطاء وحدة تحكم Keycloak باستخدام Nginx وDocker

يمكن أن يكون إعداد Keycloak في Docker Container باستخدام Nginx Reverse Proxy تكوينًا قويًا لإدارة الوصول الآمن، لكنه لا يخلو من التحديات. 🐳 عند ترحيل قواعد بيانات Keycloak أو التعامل مع مجالات متعددة، غالبًا ما تظهر أخطاء غير متوقعة، مما يؤدي إلى حدوث ارتباك للمسؤولين.

يصف هذا السيناريو عملية الترحيل من Keycloak v19.0.2 إلى Keycloak v26، والتي ظهرت خلالها رسالة "تعذر تحديد رسالة الخطأ" في جميع المجالات بعد تسجيل الدخول. أظهر تتبع المشكلة من خلال سجلات Nginx وسجلات الأخطاء Keycloak فشل طلب HTTP.

في إعدادات مماثلة، يمكن أن يؤدي وكيل أو طبقة شبكة تم تكوينها بشكل خاطئ إلى ظهور أخطاء "502 بوابة سيئة"، عادةً بسبب مشكلات في كيفية توجيه Nginx أو Docker للطلبات إلى Keycloak. قد تتطلب هذه المشكلة إجراء تعديلات في إعدادات الوكيل أو متغيرات البيئة أو تكوينات SSL لضمان عمل Keycloak بسلاسة.

في هذا الدليل، سنتعرف على الحلول المحتملة لاستكشاف هذه المشكلة وإصلاحها في Keycloak. سنراجع التكوينات الرئيسية، ونحلل سجلات الأخطاء، ونستكشف إعدادات محددة يمكن أن تساعد في استقرار Keycloak داخل إعداد Docker-Nginx. وفي النهاية، سيكون لديك رؤى حول حل مثل هذه المشكلات وضمان الوصول السلس وغير المنقطع إلى وحدة تحكم المشرف.

تفصيل تفصيلي لتكوين Keycloak وNginx

تلعب البرامج النصية التي قمنا بتطويرها لتكوين Keycloak خلف وكيل Nginx العكسي دورًا حاسمًا في توجيه وإدارة الوصول الآمن إلى وحدة تحكم مسؤول Keycloak. على سبيل المثال، يحدد ملف التكوين Nginx ملفًا المنبع الكتلة التي تحدد عنوان IP الخلفي لـ Keycloak والمنفذ، مما يسمح لـ Nginx بتوجيه الطلبات بدقة. يعد هذا ضروريًا للسيناريوهات التي تعمل فيها خدمة Keycloak في قطاع شبكة مختلف أو حاوية Docker. باستخدام توجيهات الوكيل مثل proxy_pass، نحن نمكن Nginx من العمل كوسيط، للتعامل مع الطلبات الخارجية وإعادة توجيهها إلى نقطة نهاية الخدمة الداخلية لـ Keycloak. يُرى هذا الإعداد بشكل شائع في بيئات الإنتاج حيث يكون الوكلاء العكسيون ضروريين لموازنة التحميل والوصول الآمن.

ضمن إعدادات Nginx، يتم تعيين رؤوس متعددة proxy_set_header أوامر للتأكد من أن Keycloak يتلقى جميع معلومات العميل بدقة. على سبيل المثال، X-ريال-IP و X-Forwarded-Proto يتم استخدامها لتمرير عنوان IP الخاص بالعميل وبروتوكول الطلب الأصلي. تعتبر هذه المعلومات ضرورية لأن Keycloak يستخدمها لإنشاء عناوين URL دقيقة لإعادة التوجيه وإدارة سياسات الأمان. هناك مشكلة شائعة في مثل هذه الإعدادات وهي عدم وجود رؤوس، مما قد يؤدي إلى حدوث أخطاء عندما يحاول Keycloak مصادقة المستخدمين أو التحقق من صحة النطاقات. من خلال تحديد هذه الرؤوس بشكل صريح، يضمن المسؤولون أن Keycloak يتلقى السياق الذي يحتاجه لمعالجة الطلبات بشكل صحيح. يعزز هذا الأسلوب الأمان والاتساق في كيفية إدارة الطلبات.

يعمل ملف Docker Compose الذي أنشأناه لـ Keycloak على تبسيط عملية النشر باستخدام ملف env_file لجميع متغيرات البيئة. يتيح ذلك لحاوية Docker تحميل التكوينات مثل بيانات اعتماد قاعدة البيانات واسم مضيف Keycloak والمسارات النسبية، مما يجعلها أكثر أمانًا وقابلية للتكيف. يعد استخدام ملف البيئة أمرًا عمليًا أيضًا لأنه يفصل المعلومات الحساسة عن ملف Docker Compose، ويتجنب القيم ذات الترميز الثابت. ونتيجة لذلك، يصبح تبديل قواعد البيانات أو تعديل بيانات اعتماد الوصول سلسًا، وهو أمر مفيد بشكل خاص في البيئات الديناميكية حيث يتم تحديث الخدمات بشكل متكرر. في المثال، يضمن متغير البيئة KC_PROXY_HEADERS الذي تم تعيينه على "xforwarded" أن Keycloak يفهم أنه خلف وكيل، مما يؤدي إلى إجراء تعديلات في إنشاء عنوان URL وإدارة الجلسة وفقًا لذلك.

بالإضافة إلى التكوين، قدمنا سحق البرنامج النصي الذي يعمل بمثابة فحص صحي بسيط للتحقق من توفر Keycloak. يستخدم البرنامج النصي حليقة لتنفيذ طلب HTTP إلى نقطة نهاية Keycloak والتحقق مما إذا كان رمز الحالة يساوي 200، مما يشير إلى أن الخدمة قيد التشغيل. في حالة الفشل، يقوم البرنامج النصي بإعادة تشغيل حاوية Nginx، مما يوفر شكلاً من أشكال الاسترداد التلقائي. يعد هذا الإعداد مثاليًا لبيئات الإنتاج التي يكون فيها وقت التشغيل أمرًا بالغ الأهمية، لأنه يمكّن الخدمة من الإصلاح الذاتي في حالة حدوث مشكلات في الاتصال. يؤدي اختبار البرامج النصية مثل هذه، جنبًا إلى جنب مع اختبار الوحدة المستندة إلى Python لإمكانية الوصول إلى نقطة النهاية، إلى تعزيز استقرار النظام، مما يمنح المسؤولين راحة البال عندما يعلمون أن الإعداد سوف يقوم بإخطار المشكلات أو تصحيحها بشكل استباقي. يعد هذا النهج الاستباقي للإدارة أمرًا حيويًا في تقليل وقت التوقف عن العمل وضمان الوصول السلس إلى Keycloak وحدة تحكم المشرف.

upstream sso-mydomain-com {
    server 10.10.0.89:8080;
}
server {
    listen 443 ssl;
    server_name sso.mydomain.com;
    location / {
        proxy_pass http://sso-mydomain-com/;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
    }
    ssl_certificate /etc/nginx/ssl/sso.mydomain.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/sso.mydomain.com/privkey.pem;
}
server {
    listen 8443 ssl;
    server_name sso.mydomain.com;
    error_log /usr/local/nginx/logs/sso_err.log debug;
    location / {
        proxy_pass http://sso-mydomain-com/;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
    }
    ssl_certificate /etc/nginx/ssl/sso.mydomain.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/sso.mydomain.com/privkey.pem;
}

version: '3.9'
services:
  keycloak:
    container_name: keycloak
    image: quay.io/keycloak/keycloak:26.0
    env_file:
      - .env
    ports:
      - "8080:8080"
    volumes:
      - /opt/keycloak/themes:/opt/keycloak/themes
      - /etc/localtime:/etc/localtime
    privileged: true
    command: start

import requests
def test_whoami_endpoint():
    url = "https://sso.mydomain.com:8443/auth/admin/master/console/whoami?currentRealm=master"
    headers = {"Content-Type": "application/json"}
    try:
        response = requests.get(url, headers=headers, verify=True)
        assert response.status_code == 200, "Expected 200 OK, got {}".format(response.status_code)
        print("Test passed: whoami endpoint accessible")
    except requests.ConnectionError:
        print("Connection error: Check Nginx reverse proxy and Keycloak availability")
    except AssertionError as e:
        print("Assertion error:", e)
# Run the test
test_whoami_endpoint()

#!/bin/bash
# Check if Keycloak is reachable via the /whoami endpoint
URL="http://10.10.0.89:8080/auth/admin/master/console/whoami"
STATUS_CODE=$(curl -s -o /dev/null -w "%{http_code}" $URL)
if [ "$STATUS_CODE" -ne 200 ]; then
    echo "Keycloak endpoint unavailable, restarting Nginx..."
    docker restart nginx
else
    echo "Keycloak endpoint is healthy."
fi

تحسين Keycloak لعمليات الوكيل العكسي الآمنة والسلسة

عند تكوين Keycloak خلف وكيل عكسي مثل نجينكس، هناك العديد من الاعتبارات الإضافية التي يمكن أن تساعد في ضمان أن الإعداد آمن وفعال ومستقر. أحد الجوانب الحاسمة هو إنهاء SSL — التعامل مع HTTPS في طبقة Nginx. نظرًا لأن Keycloak يستمع عادةً إلى HTTP داخل Docker، يمكن أن يعمل Nginx كنقطة نهاية SSL، مما يؤدي إلى إلغاء تحميل التشفير وتقليل تحميل الموارد على Keycloak. يسمح هذا الإعداد لـ Nginx بالتواصل مع Keycloak عبر HTTP مع الحفاظ على وصول HTTPS آمن للمستخدمين النهائيين. بالإضافة إلى ذلك، يتم تخزين شهادات SSL فقط على Nginx، مما يبسط إدارة الشهادات. يمكن للأدوات الآلية مثل Let’s Encrypt أن تسهل عملية التجديد، خاصة مع البرامج النصية التي تعيد تحميل Nginx مع تحديث الشهادات.

عامل مهم آخر هو موازنة التحميل والقياس. على سبيل المثال، باستخدام تكوينات شبكة Docker، يمكن للمسؤولين إنشاء تجمع خادم رئيسي في Nginx يتضمن العديد من حاويات Keycloak، مما يعزز توزيع التحميل والتوافر. ال proxy_pass يشير التوجيه إلى هذا التجمع، مما يمكّن Nginx من توجيه الطلبات عبر مثيلات Keycloak المتعددة. يعد هذا الأسلوب مفيدًا في البيئات ذات حركة المرور العالية، حيث أنه يمنع أي مثيل منفرد من التعرض للضغط. بالإضافة إلى ذلك، تضمن استمرارية الجلسة، والتي تسمى أيضًا بالجلسات الثابتة، بقاء المستخدمين على اتصال بنفس المثيل، وتجنب مشكلات المصادقة. يمكن إجراء عمليات التحقق من السلامة تلقائيًا باستخدام البرامج النصية Nginx أو Docker، ومراقبة توفر Keycloak وإعادة تشغيل المثيلات في حالة حدوث فشل. 🛠️

أخيرًا، يعد الاستفادة من المقاييس والسجلات المضمنة في Keycloak أمرًا حيويًا لصيانة النظام واستكشاف أخطائه وإصلاحها. يمكن لـ Keycloak إنشاء سجلات تفصيلية لكل طلب، والتي، عند إقرانها بسجلات الوصول الخاصة بـ Nginx، تنشئ مسار تدقيق كامل. يمكن لأدوات المراقبة مثل Prometheus وGrafana تصور مقاييس أداء Keycloak، وتنبيه المسؤولين عن الحالات الشاذة قبل أن تؤثر على المستخدمين. في Nginx، الإعداد error_log ل debug يلتقط المستوى أثناء الإعداد معلومات تفصيلية لتشخيص مشكلات التكوين أو الشبكة. تضمن هذه الاستراتيجيات معًا نشر Keycloak أكثر مرونة وأمانًا، مما يجعله حلاً مثاليًا للمصادقة على مستوى المؤسسة خلف وكيل عكسي.