كيفية تثبيت شهادة SSL على Heroku

يوضح لك هذا الدليل كيفية تثبيت شهادة SSL على Heroku. يغطي كلا الطريقتين التي يعتمدهما Heroku حالياً لإنهاء اتصالات TLS: إدارة الشهادات الآلية (ACM)، التي توفر وتجدد شهادات Let’s Encrypt المجانية تلقائياً، والتحميل اليدوي لشهادة من طرف ثالث عبر لوحة التحكم أو من خلال Heroku CLI.

هناك بعض الأمور التي يجب معرفتها قبل البدء. تم إيقاف إضافة SSL Endpoint القديمة (المنتج المدفوع بسعر 20 دولاراً شهرياً) في عام 2021 ولا يمكن توفيرها على التطبيقات الجديدة. تعتمد كل عملية نشر HTTPS جديدة الآن على Heroku SSL، والتي تعتمد على امتداد SNI (Server Name Indication) وتُقدَّم دون تكلفة إضافية في كل فئة دايون مدفوعة. تم إيقاف الدايون المجاني في 28 نوفمبر 2022، لذا تحتاج إلى خطة Eco أو Basic أو Standard أو Performance لإرفاق دومين مخصص وتقديم HTTPS.

إنشاء CSR (للشهادات التي يتم تحميلها يدوياً)

إذا كنت قد أنشأت طلب CSR الخاص بك مسبقاً واستلمت الشهادة الصادرة من الجهة المصدرة للشهادات، تخطَّ إلى تثبيت شهادة SSL على Heroku.

أنت بحاجة إلى CSR فقط إذا كنت تشتري شهادة من طرف ثالث لتحميلها يدوياً. إذا كنت تخطط لاستخدام ACM، يمكنك تجاوز هذا القسم بالكامل: تصدر ACM الشهادة نيابة عنك ولا يوجد CSR يجب إرساله.

طلب CSR (Certificate Signing Request) هو نص تقدمه إلى الجهة المصدرة للشهادات أثناء الطلب. يحتوي على تفاصيل دومينك ومؤسستك والمفتاح العام الذي ستُصدر الشهادة بناءً عليه. لا يقوم Heroku بإنشاء طلبات CSR على المنصة نفسها، لذا تقوم بإنشاء الطلب خارج المنصة. لديك خياران:

• استخدام أداة إنشاء CSR من SSL Dragon، التي تنتج طلب CSR والمفتاح الخاص المطابق له من نموذج قصير.
• إنشاء الطلب محلياً باستخدام OpenSSL باتباع دليلنا حول كيفية إنشاء CSR لـ Heroku.

افتح ملف .csr الناتج في أي محرر نصوص وانسخ الكتلة بأكملها، بما في ذلك العلامتين —–BEGIN CERTIFICATE REQUEST—– و—–END CERTIFICATE REQUEST—–، ثم قم بلصقها خلال طلبك على SSL Dragon. انتظر حتى تتحقق الجهة المصدرة وتصدر الشهادة (قد يستغرق ذلك من بضع دقائق لشهادات DV إلى عدة أيام عمل لشهادات OV/EV) واستمر في التثبيت أدناه.

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

يوفر Heroku مسارين للحصول على HTTPS. اختر المسار الذي يتوافق مع طريقة حصولك على الشهادة:

• ACM (موصى به لمعظم التطبيقات). يقوم Heroku بإصدار وتثبيت وتجديد شهادة Let’s Encrypt المجانية تلقائياً لكل دومين مخصص على التطبيق. لا حاجة لتحميل أي ملفات ولا لتتبع تواريخ التجديد. متوفر على فئات دايون Eco و Basic و Standard و Performance.
• التحميل اليدوي. استخدم هذا الخيار عندما تحتاج شهادة محددة من طرف ثالث (على سبيل المثال، منتج Organization Validated أو Extended Validation، أو شهادة wildcard من جهة مصدرة غير Let’s Encrypt). تقوم بتحميل الشهادة والمفتاح الخاص بنفسك عبر لوحة التحكم أو CLI.

الخطوة 1. إضافة دومينك المخصص إلى التطبيق

لن يوفر Heroku أي شهادة (ACM أو يدوية) قبل تسجيل دومينك المخصص لدى التطبيق. من محطة طرفية بصلاحيات مرتفعة، شغّل:

heroku domains:add www.example.com -a your-app-name

استبدل www.example.com بدومينك و your-app-name باسم تطبيقك على Heroku. كرر الأمر لأي أسماء مستضيفة إضافية (مثل دومين جذري بدون بادئة أو دومين فرعي ثانٍ). يمكنك أيضاً إضافة الدومين من لوحة التحكم تحت Settings > Domains and certificates > Add domain.

يُرجَع لكل دومين تضيفه هدف DNS فريد، على سبيل المثال quiet-fire-1234.herokudns.com. ستحتاج إلى هذه القيمة عند تحديث DNS في الخطوة 3.

الخطوة 2. توفير الشهادة

الخيار أ: ACM (مجاني، Let’s Encrypt يتجدد تلقائياً)

فعّل ACM للتطبيق من CLI:

heroku certs:auto:enable -a your-app-name

يبدأ Heroku بإصدار شهادة Let’s Encrypt لكل دومين مخصص على التطبيق. لمتابعة التقدم وتأكيد الحالة، شغّل:

heroku certs:auto -a your-app-name

يمكنك أيضاً تفعيل ACM من لوحة التحكم: افتح التطبيق، اذهب إلى Settings > Domains and certificates، اضغط على Configure SSL، اختر Automated Certificate Management، ثم Continue. بمجرد أن تصبح DNS جاهزة (الخطوة 3)، تكمل ACM عملية التحقق من الدومين وتصبح الشهادة نشطة. تحدث عمليات التجديد تلقائياً قبل حوالي شهر من انتهاء الصلاحية.

الخيار ب: التحميل اليدوي لشهادة من طرف ثالث

تسلمك الجهة المصدرة ثلاثة ملفات في بريدك الوارد:

• شهادة الكيان النهائي، وعادة تكون بامتداد .crt (بصيغة PEM).
• حزمة CA (الشهادات الوسيطة)، وغالباً تكون بامتداد .ca-bundle.
• المفتاح الخاص الذي تم إنشاؤه بالتزامن مع CSR (ملف .key).

يتوقع Heroku ملف PEM واحداً يحتوي على شهادة الكيان النهائي متبوعة بالشهادات الوسيطة (سلسلة كاملة أو fullchain). على Linux أو macOS، اجمعهما باستخدام cat:

cat yourcertificate.crt bundle.ca-bundle > server.crt

على Windows، افتح كلا الملفين في محرر نصوص عادي (Notepad++ أو VS Code، وليس Word) ولصق محتوى ملف .ca-bundle أسفل محتوى ملف .crt، بهذا الترتيب، دون أي سطر فارغ بين الكتلتين. احفظ الملف المجمّع باسم server.crt.

حمّل السلسلة الكاملة والمفتاح الخاص باستخدام Heroku CLI:

heroku certs:add server.crt server.key -a your-app-name

إذا كنت تستبدل شهادة موجودة على التطبيق (على سبيل المثال، أثناء التجديد)، استخدم certs:update بدلاً من ذلك حتى يحافظ Heroku على نفس هدف DNS:

heroku certs:update server.crt server.key -a your-app-name

تفضل استخدام لوحة التحكم؟ افتح التطبيق، اذهب إلى Settings > Domains and certificates، اضغط على Configure SSL، اختر Manually، ثم اسحب ملف server.crt المجمّع إلى خانة الشهادة وملف .key إلى خانة المفتاح الخاص. اضغط على Next وأكّد.

إذا ظهر لك خطأ Internal server error أثناء التحميل، فمن المرجح أن نسخة Heroku CLI المحلية لديك قديمة. حدّثها باستخدام heroku update وحاول مرة أخرى. يتطلب Heroku أيضاً مفاتيح RSA؛ مفاتيح ECDSA غير مدعومة حالياً للتحميل اليدوي.

الخطوة 3. توجيه DNS إلى هدف DNS الخاص بـ Heroku

بغض النظر عن طريقة التوفير، لا تصبح الشهادة نشطة إلا عندما تتم مطابقة DNS للدومين المخصص مع Heroku. اسرد دوميناتك وانسخ هدف DNS الذي أعاده Heroku:

heroku domains -a your-app-name

سترى قيمة مثل quiet-fire-1234.herokudns.com بجانب كل دومين. لدى مزود DNS الخاص بك، أنشئ سجلاً واحداً لكل دومين:

• دومين فرعي (مثل www.example.com): أنشئ سجل CNAME يشير إلى هدف DNS الخاص بـ Heroku.
• الدومين الجذري / الأساسي (مثل example.com): سجل CNAME غير مسموح به عند الجذر بحسب مواصفات DNS، لذا استخدم سجل ALIAS أو ANAME أو سجل CNAME مسطّح (يختلف الاسم الدقيق حسب مزود DNS الخاص بك) يشير إلى نفس هدف DNS الخاص بـ Heroku. إذا كان مزود DNS الخاص بك لا يدعم أياً من هذه الأنواع، استخدم مزوداً يدعمها (Cloudflare، DNSimple، Route 53، NS1، easyDNS، وغيرها).

لا توجّه DNS إلى your-app-name.herokuapp.com أو إلى أي اسم مستضيف *.herokussl.com: لا تستطيع ACM التحقق من الشهادة من خلال هذه العناوين، ولن يتم توجيه الربط اليدوي بشكل صحيح أيضاً. استخدم دائماً هدف DNS الخاص بكل دومين والذي عيّنه Heroku.

قد يستغرق انتشار تغييرات DNS من بضع دقائق إلى عدة ساعات. بمجرد أن يرصد Heroku السجل المحدَّث، تكمل ACM عملية التحقق تلقائياً (أو تبدأ شهادتك اليدوية في تقديم حركة المرور).

الخطوة 4. تحقق من أن الشهادة نشطة

تأكد من التثبيت من خلال CLI:

heroku certs:info -a your-app-name

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

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