كيفية تثبيت شهادة SSL في Tomcat

في هذا الدرس، ستتعلم كيفية تثبيت شهادة SSL على Apache Tomcat باستخدام أداة Java keytool، ثم تكوين موصل HTTPS في server.xml. إذا لم تكن قد أنشأت طلب CSR بعد، فإن القسم الأول يوضح لك كيفية القيام بذلك.

لقد سجلنا أيضًا فيديو يشرح لك العملية بأكملها خطوة بخطوة. يمكنك مشاهدة الفيديو أو قراءة التعليمات أو كليهما معًا. يمكنك مشاهدة الفيديو أدناه.

إنشاء رمز CSR لـ Tomcat

يشير مصطلح CSR إلى طلب توقيع الشهادة (Certificate Signing Request)، وهو كتلة نصية تحتوي على البيانات الحالية لنطاقك ومؤسستك. يجب على كل مشترٍ لشهادة SSL تجارية تقديم طلب CSR إلى الجهة المصدرة للشهادات (مزود SSL) لاجتياز عملية التحقق والحصول على الشهادة. إذا كان طلب CSR يحتوي على بيانات غير صحيحة، فلن توقعه الجهة المصدرة CA.

في Tomcat، يتم إنشاء طلب CSR باستخدام keytool من مخزن مفاتيح Java (keystore)، ويحتفظ هذا المخزن نفسه بالمفتاح الخاص الذي ستعيد استخدامه أثناء التثبيت. لديك خياران:

• استخدم أداة إنشاء CSR الخاصة بنا لإنشاء طلب CSR تلقائيًا.
• اتبع درسنا التفصيلي حول كيفية إنشاء طلب CSR على Tomcat.

مهم: احتفظ بمعلومات ملف مخزن المفاتيح والاسم المستعار (alias) الذي استخدمته عند إنشاء طلب CSR. ستقوم لاحقًا باستيراد شهادتك الموقّعة إلى نفس هذا الاسم المستعار بالضبط، لأنه يحتفظ بالمفتاح الخاص المطابق لها.

بعد أن تتحقق الجهة المصدرة للشهادات من طلبك وترسل لك ملفات SSL، تابع خطوات التثبيت أدناه.

تثبيت شهادة SSL على Tomcat

يتكون تثبيت Tomcat من مرحلتين: أولاً تقوم باستيراد سلسلة الشهادات وشهادتك الموقّعة إلى مخزن المفاتيح الذي يحتوي بالفعل على مفتاحك الخاص، ثم تقوم بتكوين موصل HTTPS في server.xml لاستخدام مخزن المفاتيح هذا.

الخطوة 1: تحضير ملفات شهادة SSL الخاصة بك

ترسل الجهة المصدرة للشهادات (CA) الملفات عبر البريد الإلكتروني إلى العنوان الذي قدمته، وعادةً ما تكون على شكل أرشيف ZIP. قم باستخراجه. وبحسب الجهة المصدرة، ستصلك الملفات بإحدى الصيغتين التاليتين:

• PKCS#7: ملف واحد بامتداد .p7b (أو .cer) يجمع بالفعل شهادتك مع الشهادات الجذرية والوسيطة.
• PEM: ملفات منفصلة، عادةً ملف .crt لشهادة الخادم الخاص بك بالإضافة إلى ملفات منفصلة root.crt وintermediate.crt.

قم برفع الملفات المستخرجة إلى الخادم، إلى نفس المجلد الذي يحتوي على مخزن المفاتيح الذي أنشأت منه طلب CSR (يُشار إليه أدناه باسم example.jks). حدد الصيغة الخاصة بك واتبع التعليمات المطابقة لها.

هل أنشأت طلب CSR في مكان آخر، بحيث يكون مفتاحك الخاص ملفًا منفصلاً بدلاً من أن يكون إدخالاً ضمن example.jks؟ تخطَّ استخدام keytool: حوّل PEM إلى PKCS#12 لدمج الشهادة والسلسلة والمفتاح في ملف .p12 واحد، ثم أشر إلى هذا الملف في الخطوة 3 باستخدام certificateKeystoreType=”PKCS12″.

الخطوة 2: استيراد الشهادة إلى مخزن المفاتيح الخاص بك

صيغة PKCS#7. نظرًا لأن ملف .p7b يحتوي بالفعل على السلسلة الكاملة، فإن أمرًا واحدًا يقوم باستيراد كل شيء دفعة واحدة، إلى الاسم المستعار الحالي لمفتاحك الخاص:

keytool -import -trustcacerts -alias ssldragon -keystore example.jks -file example.p7b

استبدل ssldragon باسمك المستعار الخاص، وexample بأسماء ملفاتك. يجب أن يكون الاسم المستعار هو نفسه الذي يحتفظ بمفتاحك الخاص بالفعل (الاسم المستعار من خطوة CSR). عندما ترى الرسالة Certificate reply was installed in keystore، يكون الاستيراد قد نجح. تحقق من محتويات مخزن المفاتيح باستخدام:

keytool -list -v -keystore example.jks

ابحث عن إدخال يكون نوعه PrivateKeyEntry بطول سلسلة شهادات أكبر من 1. هذا يؤكد أن الشهادة الموقّعة مرتبطة الآن بمفتاحك الخاص.

صيغة PEM. قم باستيراد الشهادات كل على حدة، بترتيب السلسلة: الجذر أولاً، ثم أي شهادات وسيطة، وأخيرًا شهادة نطاقك. استيراد السلسلة أولاً يسمح لأداة keytool ببناء مسار ثقة كامل قبل ربط الرد بمفتاحك. استورد الشهادة الجذرية:

keytool -import -trustcacerts -alias root -keystore example.jks -file root.crt

ثم استورد الشهادة الوسيطة:

keytool -import -trustcacerts -alias intermediate -keystore example.jks -file intermediate.crt

إذا كانت الجهة المصدرة للشهادات (CA) توفر عدة شهادات وسيطة، فقم باستيراد كل واحدة تحت اسم مستعار موثوق خاص بها، باتباع الترتيب الذي توقّع به إحداها الأخرى (من الجذر وصولاً إلى شهادة نطاقك). على سبيل المثال، تأتي شهادة Sectigo PositiveSSL مع أكثر من شهادة وسيطة واحدة، لذا قم باستيرادها بالتسلسل قبل شهادة النطاق.

أخيرًا، استورد شهادتك الأساسية (الصادرة لنطاقك) إلى الاسم المستعار الحالي لمفتاحك الخاص، وهو نفس الاسم المستعار الذي استخدمته عند إنشاء طلب CSR:

keytool -import -trustcacerts -alias ssldragon -keystore example.jks -file example.crt

هنا، يجب أن يكون ssldragon هو اسمك المستعار الحالي لمفتاحك الخاص. ونظرًا لأن هذا الاسم المستعار يحتوي بالفعل على مفتاح، فإن أداة keytool تتعامل مع هذا الاستيراد كـرد شهادة (certificate reply) وتربط الشهادة الموقّعة بالمفتاح. هذه هي الخطوة التي تجعل HTTPS يعمل.

خطأ حرج يجب تجنبه: لا تستورد الشهادة الموقّعة تحت اسم مستعار جديد تمامًا. إذا لم يكن للاسم المستعار مفتاح خاص موجود مسبقًا، فإن keytool يخزّن الشهادة كإدخال موثوق مستقل بدون مفتاح مرتبط بها، وسيفشل TLS. إذا لم تكن متأكدًا من الاسم المستعار الذي يحتفظ بمفتاحك، فشغّل keytool -list -v -keystore example.jks واستخدم الاسم المستعار الذي يكون نوعه PrivateKeyEntry.

الخطوة 3: تكوين موصل HTTPS في server.xml

بعد وضع الشهادة في مخزن مفاتيحك، وجّه موصل HTTPS في Tomcat إليه. يتم تعريف الموصل في server.xml، الموجود في مجلد conf ضمن تثبيت Tomcat الخاص بك (على سبيل المثال $CATALINA_HOME/conf/server.xml). افتح الملف في محرر نصوص.

في إصدارات Tomcat الحالية (9 و10 و11)، تتضمن الصيغة الموصى بها عنصر SSLHostConfig متداخلاً، والذي يحتوي بدوره على عنصر Certificate يشير إلى مخزن مفاتيحك. أضف أو حدّث الموصل الآمن ليصبح على هذا النحو:

<Connector
    port="443"
    protocol="org.apache.coyote.http11.Http11NioProtocol"
    maxThreads="150"
    SSLEnabled="true"
    scheme="https"
    secure="true">
  <SSLHostConfig>
    <Certificate
        certificateKeystoreFile="/your_path/example.jks"
        certificateKeystorePassword="your_keystore_password"
        certificateKeystoreType="JKS"
        certificateKeyAlias="ssldragon"
        type="RSA" />
  </SSLHostConfig>
</Connector>

• certificateKeystoreFile: المسار الكامل لملف مخزن المفاتيح الخاص بك.
• certificateKeystorePassword: كلمة مرور مخزن المفاتيح.
• certificateKeystoreType: JKS لمخزن مفاتيح بامتداد .jks، أو PKCS12 لمخزن مفاتيح بامتداد .p12 / .pfx.
• certificateKeyAlias: الاسم المستعار الذي يحتفظ بمفتاحك الخاص وشهادتك الموقّعة (هنا، ssldragon). هذا يخبر Tomcat بأي إدخال يجب تقديمه عندما يحتوي مخزن المفاتيح على أكثر من إدخال واحد.

ملاحظة: المنفذ 443 هو منفذ HTTPS القياسي المستخدم أعلاه؛ أما أمثلة Tomcat نفسها فتستخدم افتراضيًا المنفذ 8443، لذا استخدم المنفذ الذي تتوقعه بيئتك. إذا كان هذا هو إعدادك الأول لـ HTTPS، فقد يكون الموصل الآمن معلّقًا (مُعطّلاً كتعليق) في server.xml. أزل علامات التعليق المحيطة به لتفعيل الموصل، وتأكد من عدم ربط أي موصل آخر بنفس المنفذ بالفعل.

الصيغة القديمة (إصدارات Tomcat الأقدم). تضع الأدلة القديمة تفاصيل مخزن المفاتيح مباشرة على الموصل كسمات keystoreFile وkeystorePass. وقد حل محل هذا الأسلوب عنصرا SSLHostConfig وCertificate الموضحان أعلاه، وهو النمط الذي يجب استخدامه في إصدارات Tomcat المدعومة.

الخطوة 4: احفظ server.xml وأعد تشغيل Tomcat

احفظ server.xml، ثم أعد تشغيل Tomcat حتى يعيد تحميل التكوين. على نظام Linux، استخدم النصوص البرمجية المرفقة:

$CATALINA_HOME/bin/shutdown.sh
$CATALINA_HOME/bin/startup.sh

إذا كان Tomcat يعمل كخدمة، فأعد تشغيله من خلال مدير الخدمات لديك بدلاً من ذلك (على سبيل المثال systemctl restart tomcat على Linux، أو لوحة الخدمات (Services) على Windows). تهانينا، شهادة SSL الخاصة بك مثبتة الآن على خادم Tomcat لديك.

اختبار تثبيت SSL على Tomcat

بعد تثبيت الشهادة، يمكن أن تتسلل أخطاء صغيرة دون ملاحظة وتؤثر على كيفية تعامل المتصفحات مع موقعك. اجعل من التحقق من التثبيت عادة راسخة. شغّل أداة SSL Checker الخاصة بنا للحصول على فحص فوري يكشف مشكلات مثل غياب شهادة وسيطة أو سلسلة غير موثوقة.

الأسئلة الشائعة