Cara Membuat CSR di Heroku

Tutorial ini menunjukkan cara membuat CSR (Certificate Signing Request) untuk Heroku menggunakan OpenSSL dan cara mengunggah sertifikat yang diterbitkan dengan Heroku CLI.

Heroku tidak memiliki formulir CSR bawaan di platformnya sendiri, sehingga permintaan dan private key yang bersesuaian dibuat di luar platform (di mesin lokal Linux, macOS, atau Windows Anda, atau di shell mana pun yang memiliki OpenSSL). Setelah Certificate Authority menerbitkan sertifikat, Anda menggabungkannya dengan intermediate chain lalu mengunggahnya melalui heroku certs:add.

Apakah Anda benar-benar membutuhkan CSR di Heroku?

Untuk sebagian besar aplikasi Heroku, jawabannya tidak. Automated Certificate Management (ACM) milik Heroku menyediakan dan memperbarui otomatis sertifikat Let’s Encrypt gratis untuk setiap domain khusus pada aplikasi, tanpa perlu membuat CSR dan tanpa perlu memantau jadwal pembaruan. ACM tersedia pada dyno Eco, Basic, Standard, dan Performance. Jika ACM sesuai dengan kebutuhan Anda, aktifkan dengan satu perintah CLI:

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

Buat CSR dan gunakan sertifikat yang dikelola sendiri (pihak ketiga) hanya jika salah satu kondisi berikut berlaku:

• Anda memerlukan sertifikat wildcard. ACM hanya menerbitkan sertifikat Let’s Encrypt dengan satu nama per domain khusus, bukan *.example.com.
• Anda memerlukan validasi OV atau EV. ACM hanya bersifat DV.
• Kebijakan atau kontrak Anda mengharuskan Certificate Authority tertentu selain Let’s Encrypt.
• Anda sudah memiliki sertifikat yang valid dan ingin menerapkannya kembali di Heroku tanpa menerbitkan ulang.
• Anda memerlukan sertifikat multi-domain (SAN) yang mencakup hostname yang tidak semuanya berada pada aplikasi Heroku ini.

Jika tidak satu pun dari kondisi di atas berlaku, lewati proses pembuatan CSR dan gunakan ACM saja. Untuk alur instalasinya sendiri, lihat panduan kami tentang cara menginstal sertifikat SSL di Heroku.

Dasar-dasar SSL Heroku yang perlu diketahui sebelum membuat CSR

Beberapa batasan platform menentukan bagaimana CSR dan key harus dibuat:

• SNI adalah default. Setiap aplikasi baru menggunakan Heroku SSL, yang mengandalkan Server Name Indication, sehingga satu endpoint Heroku dapat melayani beberapa hostname HTTPS dengan sertifikatnya masing-masing. Add-on lama SSL Endpoint sudah dihentikan (deprecated) sejak 2021 (penyediaan baru berhenti pada 14 Mei 2021; produk ini mencapai akhir masa pakainya pada 18 Oktober 2021) dan tidak tersedia untuk aplikasi baru.
• Hanya RSA key. Stack SSL Heroku menerima private key RSA (2048 bit atau lebih besar). Key ECDSA tidak didukung untuk pengunggahan sertifikat secara manual, jadi buatlah CSR dengan -newkey rsa:2048 (atau rsa:3072 / rsa:4096 jika kebijakan Anda mengharuskan key yang lebih besar).
• Fullchain PEM diperlukan. Heroku mengharapkan satu file PEM dengan sertifikat end-entity terlebih dahulu, diikuti oleh bundle intermediate CA yang digabungkan setelahnya. Sertifikat leaf-only saja akan ditolak saat diunggah.
• Private key tidak terenkripsi. Key yang diunggah bersama sertifikat tidak boleh dilindungi passphrase. Perintah OpenSSL di bawah ini menggunakan -nodes untuk menulis key dalam bentuk PEM tanpa enkripsi.
• Prasyarat domain khusus. Heroku tidak akan mengaitkan sertifikat apa pun (ACM atau manual) sampai domain khusus tersebut didaftarkan ke aplikasi melalui heroku domains:add dan diarahkan ke target DNS *.herokudns.com per domain.

Membuat CSR untuk Heroku dengan OpenSSL

Jika Anda sudah membuat CSR dan menerima sertifikat yang ditandatangani dari Certificate Authority Anda, langsung lewati ke bagian Mengunggah sertifikat ke Heroku. Ada dua cara untuk membuat CSR untuk deployment Heroku:

• Gunakan CSR Generator dari SSL Dragon: alat ini menghasilkan CSR sekaligus private key RSA yang bersesuaian di browser Anda melalui formulir singkat, lalu Anda cukup menempelkan CSR tersebut saat melakukan pemesanan SSL.
• Buat CSR sendiri dengan OpenSSL, baik di mesin lokal Anda maupun di shell mana pun tempat OpenSSL terpasang. Langkah-langkah di bawah ini membahas cara ini.

Langkah 1: Buka shell yang memiliki OpenSSL

OpenSSL sudah tersedia di setiap distribusi Linux terbaru dan di macOS. Di Windows, instal terlebih dahulu (lihat panduan kami tentang menginstal OpenSSL di Windows) dan jalankan perintahnya di PowerShell atau Command Prompt. Buka terminal di folder mana pun yang bisa Anda tulisi: OpenSSL akan membuat file CSR dan key di sana dalam bentuk teks biasa, sehingga Anda bisa memindahkannya keluar dari mesin tersebut setelah selesai.

Langkah 2: Jalankan perintah OpenSSL

Jalankan perintah berikut di shell Anda. Ganti yourdomain dengan domain Anda yang sebenarnya (misalnya, example.com):

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

Fungsi setiap flag:

• -new membuat CSR baru.
• -newkey rsa:2048 menghasilkan private key RSA 2048-bit baru bersamaan dengan CSR. Gunakan rsa:3072 atau rsa:4096 jika kebijakan Anda mengharuskan key yang lebih besar. Jangan beralih ke ECDSA: Heroku menolak key ECC pada pengunggahan manual.
• -nodes menulis key tanpa passphrase (pada OpenSSL 3.x, flag yang setara adalah -noenc; keduanya berfungsi sama). Heroku akan menolak private key yang terenkripsi saat menjalankan heroku certs:add.
• -keyout dan -out adalah jalur output untuk key dan CSR.
• -addext “subjectAltName=DNS:…” menyematkan Subject Alternative Names (SAN) secara langsung (memerlukan OpenSSL 1.1.1 atau lebih baru). Setiap browser dan CA modern mewajibkan ekstensi SAN, bahkan untuk sertifikat satu domain, jadi sertakan baik domain utama (yourdomain.com) maupun varian www apa pun yang akan Anda layani di Heroku. Untuk wildcard, cantumkan juga *.yourdomain.com.

Langkah 3: Isi detail CSR

OpenSSL akan meminta Anda mengisi bidang identitas sertifikat. Isilah sebagai berikut:

• Country Name: kode ISO dua huruf negara tempat organisasi Anda terdaftar secara resmi (misalnya, US).
• State or Province Name: nama lengkap negara bagian atau wilayah (misalnya, Nevada). Jangan disingkat.
• Locality Name: nama kota (misalnya, Las Vegas).
• Organization Name: nama resmi organisasi Anda. Untuk sertifikat Domain Validation, bidang ini tidak divalidasi dan boleh dikosongkan, tetapi jangan hanya menekan Enter: OpenSSL akan mengisi nilai default dari konfigurasinya, dan konfigurasi bawaan biasanya berisi Internet Widgits Pty Ltd, yang akhirnya akan masuk ke CSR Anda. Ketik satu tanda titik (.) agar bidang ini benar-benar kosong.
• Organizational Unit Name: sudah tidak digunakan (deprecated) oleh CA/Browser Forum, jadi biarkan kosong.
• Common Name: nama domain lengkap yang memenuhi syarat (FQDN) yang ingin Anda amankan, misalnya www.yourdomain.com. Untuk wildcard, masukkan *.yourdomain.com. Common Name juga harus tercantum dalam daftar SAN.
• Email Address: alamat email kontak yang valid (atau biarkan kosong).
• A challenge password dan An optional company name: biarkan keduanya kosong. Tekan Enter untuk melewati.

OpenSSL akan menuliskan dua file di direktori saat ini:

• yourdomain.csr: CSR yang Anda kirimkan ke Certificate Authority Anda.
• yourdomain.key: private key. Jaga kerahasiaan file ini dan buat cadangannya; Anda akan membutuhkannya lagi saat mengunggah sertifikat yang diterbitkan ke Heroku.

Langkah 4: Kirim CSR ke Certificate Authority Anda

Buka yourdomain.csr di editor teks mana pun dan salin seluruh blok teksnya, termasuk penanda -----BEGIN CERTIFICATE REQUEST----- dan -----END CERTIFICATE REQUEST-----. Tempelkan ke kolom CSR saat melakukan pemesanan SSL Anda.

Sebelum mengirimkannya, Anda dapat memverifikasi isi CSR dengan CSR Decoder kami: alat ini menampilkan Common Name, daftar SAN, jenis key, dan panjang key sehingga Anda bisa menemukan kesalahan ketik sebelum CA melakukannya.

Selesaikan langkah validasi yang diminta oleh CA (berbasis DNS, file, atau email). Setelah sertifikat diterbitkan, CA akan mengirimkan sertifikat end-entity yang telah ditandatangani (biasanya file .crt) beserta bundle intermediate CA (sering kali file .ca-bundle). Lanjutkan ke proses pengunggahan di bawah ini.

Mengunggah sertifikat ke Heroku

Langkah 1: Daftarkan domain khusus Anda ke aplikasi

Heroku tidak akan mengaitkan sertifikat sampai domain khusus tersebut didaftarkan ke aplikasi. Dari terminal yang sudah login ke Heroku CLI, jalankan:

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

Ganti www.example.com dengan domain Anda dan your-app-name dengan nama aplikasi Heroku Anda. Ulangi perintah ini untuk setiap hostname tambahan (misalnya domain root polos atau subdomain kedua). Perintah ini akan mengembalikan target DNS per domain seperti quiet-fire-1234.herokudns.com: nilai inilah yang akan Anda arahkan dari penyedia DNS Anda pada Langkah 4.

Langkah 2: Susun file PEM fullchain

Heroku mengharapkan satu file PEM dengan sertifikat end-entity terlebih dahulu, diikuti oleh intermediate chain setelahnya. Di Linux atau macOS, gabungkan file-file tersebut dengan cat:

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

Di Windows, buka kedua file tersebut di editor teks biasa (Notepad++ atau VS Code, bukan Word) lalu tempelkan isi file .ca-bundle di bawah isi file .crt, dalam urutan tersebut, tanpa baris kosong di antara kedua blok. Simpan file gabungan tersebut sebagai server.crt. Jika CA Anda sudah mengirimkan chain tersebut dalam satu file PEM (dengan leaf di bagian atas), Anda bisa langsung menggunakan file tersebut apa adanya.

Langkah 3: Unggah sertifikat dengan Heroku CLI

Untuk instalasi baru, unggah file PEM fullchain beserta private key yang bersesuaian dengan certs:add:

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

Jika Anda mengganti sertifikat yang sudah ada pada aplikasi yang sama (misalnya saat pembaruan/renewal), gunakan certs:update agar Heroku tetap mempertahankan target DNS yang sama:

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

Lebih suka menggunakan dashboard? Buka aplikasi Anda, masuk ke Settings > Domains and certificates, klik Configure SSL, pilih Manually, seret file server.crt gabungan ke kolom sertifikat dan file .key ke kolom private key, lalu klik Next dan konfirmasi.

Jika Anda melihat pesan Internal server error saat mengunggah, hampir selalu penyebabnya adalah Heroku CLI di mesin Anda yang sudah usang. Jalankan heroku update lalu coba lagi. Jika error tetap muncul, pastikan file sertifikat sudah berupa fullchain dalam format PEM (end-entity terlebih dahulu, diikuti intermediate) dan bahwa private key yang digunakan adalah key RSA yang bersesuaian dengan CSR yang Anda kirimkan.

Langkah 4: Arahkan DNS ke target DNS Heroku

Tampilkan daftar domain Anda dan salin target DNS yang dikembalikan Heroku untuk masing-masing domain:

heroku domains -a your-app-name

Di penyedia DNS Anda, buat satu record untuk setiap domain:

• Subdomain (misalnya www.example.com): buat record CNAME yang mengarah ke target DNS Heroku.
• Domain apex / root (misalnya example.com): CNAME tidak diperbolehkan pada apex sesuai spesifikasi DNS, jadi gunakan record ALIAS, ANAME, atau flattened-CNAME (nama pastinya tergantung penyedia DNS Anda) yang mengarah ke target DNS Heroku yang sama. Jika penyedia DNS Anda tidak mendukung satu pun dari opsi ini, pindahkan DNS Anda ke penyedia yang mendukungnya (Cloudflare, DNSimple, Route 53, NS1, easyDNS, dan sejenisnya).

Jangan arahkan DNS ke your-app-name.herokuapp.com atau ke hostname *.herokussl.com mana pun: pengaitan manual tidak akan dapat dirutekan dengan benar melalui keduanya. Selalu gunakan target DNS per domain yang ditetapkan oleh Heroku.

Memverifikasi CSR dan sertifikat yang sudah diterapkan

Sebelum mengirimkan CSR, dekode terlebih dahulu secara lokal untuk memastikan Common Name, daftar SAN, jenis key, dan panjang key:

openssl req -in yourdomain.csr -noout -text

Atau tempelkan CSR ke CSR Decoder kami untuk mendapatkan informasi yang sama langsung di browser Anda.

Setelah mengunggah, pastikan sertifikat sudah terpasang dan melayani trafik. Dari CLI:

heroku certs:info -a your-app-name

Output-nya menampilkan sertifikat, CA penerbit, tanggal kedaluwarsa, dan domain yang dicakupnya. Selanjutnya, buka situs Anda melalui https:// di browser, periksa apakah ikon gembok sudah muncul, dan jalankan pemindaian eksternal yang lebih mendalam dengan SSL Checker kami untuk memastikan bahwa rantai sertifikat sudah lengkap dan protokolnya dikonfigurasi dengan benar.