كيفية إنشاء CSR على Heroku

يوضح لك هذا الدليل كيفية إنشاء طلب توقيع شهادة (CSR) لخدمة Heroku باستخدام OpenSSL وكيفية رفع الشهادة الصادرة باستخدام واجهة سطر أوامر Heroku (Heroku CLI).

لا تحتوي منصة Heroku على نموذج CSR مدمج بها، لذا يتم إنشاء الطلب والمفتاح الخاص المطابق له خارج المنصة (على جهازك المحلي سواء كان يعمل بنظام Linux أو macOS أو Windows، أو في أي واجهة أوامر (shell) يتوفر بها OpenSSL). بمجرد أن تصدر جهة إصدار الشهادات (CA) الشهادة، تقوم بدمجها مع سلسلة الشهادات الوسيطة ورفعها باستخدام الأمر heroku certs:add.

هل تحتاج فعلًا إلى CSR على Heroku؟

بالنسبة لمعظم تطبيقات Heroku، الإجابة هي لا. تقوم ميزة إدارة الشهادات الآلية (Automated Certificate Management – ACM) الخاصة بـ Heroku بتوفير شهادة Let’s Encrypt مجانية وتجديدها تلقائيًا لكل نطاق مخصص على التطبيق، دون الحاجة إلى إنشاء CSR أو متابعة تقويم للتجديد. تتوفر ميزة ACM على خطط Eco وBasic وStandard وPerformance dynos. إذا كانت ميزة ACM تناسب احتياجاتك، فقم بتفعيلها بأمر واحد فقط من واجهة سطر الأوامر:

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

قم بإنشاء CSR واستخدم شهادة ذاتية الإدارة (من طرف ثالث) فقط في إحدى الحالات التالية:

• تحتاج إلى شهادة Wildcard. تصدر ميزة ACM فقط شهادات Let’s Encrypt أحادية الاسم لكل نطاق مخصص، وليس شهادات من نوع *.example.com.
• تحتاج إلى التحقق من نوع OV أو EV. حيث إن ميزة ACM تدعم فقط التحقق من نوع DV.
• تتطلب سياستك أو عقدك جهة إصدار شهادات معينة غير Let’s Encrypt.
• لديك بالفعل شهادة صالحة وتريد إعادة نشرها على Heroku دون إعادة إصدارها.
• تحتاج إلى شهادة متعددة النطاقات (SAN) تغطي أسماء مضيفين لا تنتمي جميعها إلى هذا التطبيق على Heroku.

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

أساسيات SSL على Heroku يجب معرفتها قبل إنشاء CSR

هناك بعض قيود المنصة التي تحدد شكل CSR والمفتاح المطلوب:

• SNI هو الوضع الافتراضي. يستخدم كل تطبيق جديد Heroku SSL، الذي يعتمد على تقنية Server Name Indication، بحيث يمكن لنقطة نهاية واحدة على Heroku خدمة عدة أسماء مضيفين عبر HTTPS بشهاداتهم الخاصة. تم إيقاف الإضافة القديمة SSL Endpoint عام 2021 (توقف التزويد الجديد في 14 مايو 2021، وانتهى عمرها الافتراضي تمامًا في 18 أكتوبر 2021) ولم تعد متاحة للتطبيقات الجديدة.
• مفاتيح RSA فقط. تقبل بنية SSL في Heroku مفاتيح RSA الخاصة (بحجم 2048 بت أو أكبر). لا تدعم Heroku مفاتيح ECDSA لعمليات رفع الشهادات اليدوية، لذا قم بإنشاء CSR باستخدام -newkey rsa:2048 (أو rsa:3072 / rsa:4096 إذا كانت سياستك تتطلب مفتاحًا أكبر).
• ملف PEM الكامل (Fullchain) مطلوب. تتوقع Heroku ملف PEM واحدًا يحتوي على شهادة الكيان النهائي أولًا ثم حزمة شهادات CA الوسيطة متبوعة بها. سيتم رفض أي شهادة تحتوي فقط على الشهادة النهائية (leaf) أثناء الرفع.
• مفتاح خاص غير مشفر. لا يمكن أن يكون المفتاح المرفوع مع الشهادة محميًا بعبارة مرور. يستخدم أمر OpenSSL أدناه الخيار -nodes لكتابة المفتاح بصيغة PEM غير مشفرة.
• اشتراط وجود نطاق مخصص. لن تربط Heroku أي شهادة (سواء ACM أو يدوية) قبل تسجيل النطاق المخصص لدى التطبيق عبر الأمر heroku domains:add وتوجيهه إلى هدف DNS الخاص بكل نطاق *.herokudns.com.

إنشاء CSR لـ Heroku باستخدام OpenSSL

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

• استخدام أداة إنشاء CSR الخاصة بـ SSL Dragon: تقوم هذه الأداة بإنشاء كل من CSR والمفتاح الخاص RSA المطابق له مباشرة في متصفحك من خلال نموذج بسيط، ثم تلصق CSR أثناء طلب شهادة SSL الخاصة بك.
• إنشاء CSR بنفسك باستخدام OpenSSL، سواء على جهازك المحلي أو في أي واجهة أوامر (shell) مثبت بها OpenSSL. الخطوات أدناه تغطي هذا المسار.

الخطوة 1: افتح واجهة أوامر (shell) بها OpenSSL

يأتي OpenSSL مثبتًا مسبقًا على كل توزيعات Linux الحديثة وعلى macOS. أما على Windows، فقم بتثبيته (راجع دليلنا حول تثبيت OpenSSL على Windows) وقم بتشغيل الأمر في PowerShell أو موجه الأوامر (Command Prompt). افتح طرفية (terminal) في أي مجلد لديك صلاحية الكتابة فيه: سيقوم OpenSSL بإنشاء ملفات CSR والمفتاح هناك كملفات نصية عادية، بحيث يمكنك نقلها خارج الجهاز عند الانتهاء.

الخطوة 2: تشغيل أمر OpenSSL

قم بتشغيل الأمر التالي في واجهة الأوامر الخاصة بك. استبدل yourdomain بنطاقك الفعلي (على سبيل المثال، example.com):

openssl req -new -newkey rsa:2048 -nodes 
  -keyout yourdomain.key -out yourdomain.csr 
  -addext "subjectAltName = DNS:yourdomain.com,DNS:www.yourdomain.com"

وظيفة كل خيار:

• -new ينشئ CSR جديدًا.
• -newkey rsa:2048 ينشئ مفتاح RSA خاص جديد بحجم 2048 بت جنبًا إلى جنب مع CSR. استخدم rsa:3072 أو rsa:4096 إذا كانت سياستك تتطلب مفتاحًا أكبر. لا تنتقل إلى ECDSA: حيث ترفض Heroku مفاتيح ECC في عمليات الرفع اليدوية.
• -nodes يكتب المفتاح دون عبارة مرور (في إصدار OpenSSL 3.x، الخيار المعادل هو -noenc؛ وكلاهما يعمل). سترفض Heroku أي مفتاح خاص مشفر أثناء تنفيذ الأمر heroku certs:add.
• -keyout و-out هما مساري الإخراج للمفتاح وCSR.
• -addext “subjectAltName=DNS:…” يضمّن الأسماء البديلة للموضوع (SANs) مباشرة (يتطلب OpenSSL 1.1.1 أو أحدث). يشترط كل متصفح حديث وكل جهة إصدار شهادات وجود امتداد SAN، حتى بالنسبة للشهادات أحادية النطاق، لذا احرص على تضمين النطاق الأساسي (yourdomain.com) وأي نسخة www تخطط لخدمتها على Heroku. بالنسبة لشهادة Wildcard، أضف أيضًا *.yourdomain.com.

الخطوة 3: تعبئة بيانات CSR

سيطلب منك OpenSSL إدخال حقول هوية الشهادة. أدخلها على النحو التالي:

• اسم الدولة (Country Name): رمز ISO المكون من حرفين للدولة التي تم فيها تسجيل مؤسستك رسميًا (على سبيل المثال، US).
• اسم الولاية أو المقاطعة (State or Province Name): الاسم الكامل للولاية أو المنطقة (على سبيل المثال، Nevada). لا تستخدم اختصارًا.
• اسم المدينة (Locality Name): المدينة (على سبيل المثال، Las Vegas).
• اسم المؤسسة (Organization Name): الاسم القانوني لمؤسستك. بالنسبة لشهادة التحقق من النطاق (Domain Validation)، لا يتم التحقق من هذا الحقل ويمكن تركه فارغًا، لكن لا تضغط فقط على مفتاح Enter: سيقوم OpenSSL حينها بملء القيمة الافتراضية الموجودة في إعداداته، والتي تأتي في الإعداد القياسي بقيمة Internet Widgits Pty Ltd، والتي ستنتهي في CSR الخاص بك. اكتب نقطة واحدة (.) لتركه فارغًا فعليًا.
• اسم الوحدة التنظيمية (Organizational Unit Name): تم إيقاف استخدام هذا الحقل من قبل منتدى CA/Browser Forum، لذا اتركه فارغًا.
• الاسم الشائع (Common Name): اسم النطاق المؤهل بالكامل (FQDN) الذي تريد تأمينه، على سبيل المثال www.yourdomain.com. بالنسبة لشهادة Wildcard، أدخل *.yourdomain.com. يجب أن يكون الاسم الشائع موجودًا أيضًا في قائمة SAN.
• عنوان البريد الإلكتروني (Email Address): بريد إلكتروني صالح للتواصل (أو اتركه فارغًا).
• عبارة تحدٍ (challenge password) واسم شركة اختياري: اترك كلا الحقلين فارغين. اضغط على Enter لتخطيهما.

يكتب OpenSSL ملفين في المجلد الحالي:

• yourdomain.csr: طلب CSR الذي ترسله إلى جهة إصدار الشهادات (CA).
• yourdomain.key: المفتاح الخاص. حافظ على خصوصية هذا الملف واحتفظ بنسخة احتياطية منه؛ ستحتاج إليه مرة أخرى عند رفع الشهادة الصادرة إلى Heroku.

الخطوة 4: إرسال CSR إلى جهة إصدار الشهادات

افتح ملف yourdomain.csr في أي محرر نصوص وانسخ الكتلة الكاملة، بما في ذلك العلامتين -----BEGIN CERTIFICATE REQUEST----- و-----END CERTIFICATE REQUEST-----. الصقها في حقل CSR أثناء طلب شهادة SSL الخاصة بك.

قبل الإرسال، يمكنك التحقق من محتويات CSR باستخدام أداة فك تشفير CSR الخاصة بنا: حيث تعرض الاسم الشائع وقائمة SAN ونوع المفتاح وطول المفتاح، بحيث يمكنك اكتشاف الأخطاء المطبعية قبل أن تكتشفها جهة إصدار الشهادات.

أكمل خطوات التحقق التي تطلبها جهة إصدار الشهادات (سواء عبر DNS أو ملف أو بريد إلكتروني). بمجرد إصدار الشهادة، ترسل لك جهة إصدار الشهادات شهادة الكيان النهائي الموقعة (عادةً ملف .crt) وحزمة CA الوسيطة (غالبًا ملف .ca-bundle). تابع عملية الرفع أدناه.

رفع الشهادة إلى Heroku

الخطوة 1: تسجيل نطاقك المخصص لدى التطبيق

لن تربط Heroku شهادة قبل تسجيل النطاق المخصص لدى التطبيق. من طرفية مسجلة الدخول إلى Heroku CLI، قم بتشغيل:

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

استبدل www.example.com بنطاقك وyour-app-name باسم تطبيقك على Heroku. كرر الأمر لأي أسماء مضيفين إضافية (على سبيل المثال نطاق جذر بدون بادئة أو نطاق فرعي ثانٍ). يعيد الأمر هدف DNS خاص بكل نطاق مثل quiet-fire-1234.herokudns.com: ستوجّه مزود DNS الخاص بك إلى هذه القيمة في الخطوة 4.

الخطوة 2: إنشاء ملف PEM الكامل (Fullchain)

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

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

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

الخطوة 3: رفع الشهادة باستخدام Heroku CLI

بالنسبة لتثبيت جديد تمامًا، قم برفع ملف PEM الكامل والمفتاح الخاص المطابق له باستخدام الأمر certs:add:

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

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

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

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

إذا ظهرت لك رسالة Internal server error أثناء الرفع، فغالبًا ما يكون السبب هو أن نسخة Heroku CLI على جهازك قديمة. قم بتشغيل الأمر heroku update وحاول مرة أخرى. إذا استمر الخطأ، تأكد من أن ملف الشهادة عبارة عن سلسلة كاملة بصيغة PEM (الشهادة النهائية أولًا، ثم الشهادات الوسيطة بعدها) وأن المفتاح الخاص هو مفتاح RSA المطابق لـ CSR الذي أرسلته.

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

اعرض قائمة نطاقاتك وانسخ هدف DNS الذي أعادته Heroku لكل منها:

heroku domains -a your-app-name

لدى مزود DNS الخاص بك، قم بإنشاء سجل واحد لكل نطاق:

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

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

التحقق من CSR ومن الشهادة المنشورة

قبل إرسال CSR، قم بفك تشفيره محليًا للتأكد من الاسم الشائع وقائمة SAN ونوع المفتاح وطول المفتاح:

openssl req -in yourdomain.csr -noout -text

أو الصق CSR في أداة فك تشفير CSR الخاصة بنا للحصول على نفس المعلومات مباشرة في متصفحك.

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

heroku certs:info -a your-app-name

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