Cara Menginstal Sertifikat SSL di Server JBoss

Tutorial ini menunjukkan kepada Anda cara menginstal sertifikat SSL di JBoss EAP dan WildFly menggunakan keytool dan subsistem keamanan Elytron. Jika Anda belum memiliki file sertifikat, bagian pertama membahas cara membuat CSR.

Catatan mengenai versi: JBoss EAP modern (7.1 dan yang lebih baru, termasuk EAP 8) serta rilis WildFly terbaru mengonfigurasi HTTPS melalui subsistem elytron yang terhubung ke https-listener Undertow. Metode lama security-realm serta konektor Tomcat atau Jetty yang lama sudah tidak digunakan lagi (deprecated), sehingga panduan ini menggunakan pendekatan yang terkini.

Kami juga telah merekam video yang memandu Anda melalui seluruh proses ini. Anda dapat menonton videonya, membaca instruksinya, atau melakukan keduanya. Anda dapat menonton videonya di bawah ini.

Membuat kode CSR di JBoss

CSR (Certificate Signing Request) adalah blok teks terenkode yang Anda kirimkan ke Certificate Authority (CA) saat memesan sertifikat. CSR ini berisi detail domain dan organisasi Anda, yang digunakan CA untuk memverifikasi permintaan tersebut. Pembuatan CSR juga menghasilkan private key yang sesuai, yang tetap berada di server Anda dan diperlukan saat proses instalasi.

Anda memiliki dua pilihan:

• Gunakan CSR Generator kami untuk membuat CSR secara otomatis.
• Ikuti tutorial langkah demi langkah kami tentang cara membuat CSR di JBoss.

Di JBoss, CSR dibuat dengan keytool dari keystore .jks atau .p12. Catat alias dan nama keystore yang Anda pilih sekarang: nanti Anda akan mengimpor sertifikat yang telah ditandatangani kembali ke alias yang sama persis tersebut. Kirimkan CSR ke CA saat melakukan pemesanan, dan setelah sertifikat diterbitkan, lanjutkan dengan instalasi di bawah ini.

Menginstal sertifikat SSL di JBoss Server

Langkah 1: Siapkan file sertifikat Anda

Setelah proses verifikasi, CA akan mengirimkan email berisi file sertifikat Anda, biasanya dalam bentuk arsip ZIP. Ekstrak arsip tersebut. Anda seharusnya memiliki:

• Sertifikat utama Anda (file .crt, .cer, atau .pem).
• Sertifikat perantara (intermediate), yang sering diberikan sebagai file .ca-bundle (CA bundle). Beberapa CA juga menyertakan root.
• Keystore (.jks atau .p12) yang Anda buat bersamaan dengan CSR, yang menyimpan private key Anda di bawah alias yang Anda pilih saat membuat CSR.

Simpan file-file ini bersama, dan salin ke server, misalnya ke dalam direktori konfigurasi JBoss ($JBOSS_HOME/standalone/configuration/). Jika sebuah file terbuka sebagai teks, Anda dapat memastikan bahwa file tersebut berisi baris BEGIN CERTIFICATE dan END CERTIFICATE yang diharapkan.

Langkah 2: Impor rantai CA ke dalam keystore

Impor terlebih dahulu sertifikat intermediate (dan root, jika disediakan) agar keytool dapat membangun rantai kepercayaan (chain of trust) yang lengkap. Gunakan keystore yang sama yang menyimpan private key Anda, dan berikan alias tersendiri untuk setiap sertifikat CA:

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

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

Jika CA Anda mengirimkan satu file .ca-bundle, impor file tersebut dengan satu alias (misalnya -alias intermediate). Ketika diminta, masukkan kata sandi keystore dan konfirmasi kepercayaan (trust). Entri-entri ini adalah entri sertifikat tepercaya (trusted-certificate entries), bukan entri kunci (key entries), sehingga tidak memengaruhi private key Anda.

Langkah 3: Impor sertifikat yang telah ditandatangani ke alias kunci Anda

Sekarang impor sertifikat yang telah ditandatangani (balasan dari CA) ke dalam alias yang tepat sama seperti yang Anda gunakan saat membuat CSR. Karena alias tersebut sudah menyimpan private key, keytool memperlakukan ini sebagai balasan sertifikat (certificate reply) dan mengganti sertifikat self-signed sementara dengan rantai yang ditandatangani CA, sambil tetap menjaga kunci tersebut tetap utuh:

keytool -import -trustcacerts -alias your_csr_alias -file your_domain.crt -keystore your_keystore.jks

Ganti your_csr_alias dengan alias yang Anda gunakan saat membuat CSR dan your_keystore.jks dengan nama keystore Anda. Jika berhasil, keytool akan mencetak Certificate reply was installed in keystore.

Penting: jangan membuat alias baru di sini. Mengimpor balasan tersebut dengan alias baru akan membuat entri sertifikat tepercaya tanpa private key, rantainya akan hilang, dan server tidak dapat menyelesaikan proses TLS handshake. Jika Anda melihat pesan Failed to establish chain from reply, artinya sertifikat intermediate atau root dari Langkah 2 belum ada di keystore.

Anda dapat memverifikasi hasilnya, alias tersebut sekarang seharusnya menunjukkan rantai sertifikat dengan panjang lebih dari 1:

keytool -list -v -alias your_csr_alias -keystore your_keystore.jks

Langkah 4: Konfigurasi HTTPS di subsistem Elytron

Letakkan keystore di $JBOSS_HOME/standalone/configuration/, lalu tentukan key-store, key-manager, dan server-ssl-context Elytron. Cara tercepat adalah menggunakan CLI manajemen. Mulai server, sambungkan dengan jboss-cli.sh --connect, dan jalankan sebuah batch agar perubahan diterapkan secara bersamaan:

batch

/subsystem=elytron/key-store=httpsKS:add(path=your_keystore.jks, relative-to=jboss.server.config.dir, credential-reference={clear-text=your_keystore_password}, type=JKS)

/subsystem=elytron/key-manager=httpsKM:add(key-store=httpsKS, credential-reference={clear-text=your_keystore_password})

/subsystem=elytron/server-ssl-context=httpsSSC:add(key-manager=httpsKM, protocols=["TLSv1.3","TLSv1.2"])

run-batch

Selanjutnya, arahkan https-listener Undertow ke ssl-context yang baru. Undertow tidak dapat merujuk ke security-realm lama dan ssl-context Elytron secara bersamaan, sehingga hapus referensi lama dan tetapkan yang baru dalam satu batch:

batch

/subsystem=undertow/server=default-server/https-listener=https:undefine-attribute(name=security-realm)

/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context, value=httpsSSC)

run-batch

Jika Anda lebih memilih untuk mengedit standalone.xml secara langsung (dengan server dalam keadaan berhenti), konfigurasi yang setara akan terlihat seperti ini di dalam subsistem elytron:

<tls>
    <key-stores>
        <key-store name="httpsKS">
            <credential-reference clear-text="your_keystore_password"/>
            <implementation type="JKS"/>
            <file path="your_keystore.jks" relative-to="jboss.server.config.dir"/>
        </key-store>
    </key-stores>
    <key-managers>
        <key-manager name="httpsKM" key-store="httpsKS">
            <credential-reference clear-text="your_keystore_password"/>
        </key-manager>
    </key-managers>
    <server-ssl-contexts>
        <server-ssl-context name="httpsSSC" key-manager="httpsKM" protocols="TLSv1.3 TLSv1.2"/>
    </server-ssl-contexts>
</tls>

Dan listener yang sesuai di subsistem undertow merujuk ke ssl-context tersebut:

<https-listener name="https" socket-binding="https" ssl-context="httpsSSC" enable-http2="true"/>

Membatasi protocols hanya pada TLS 1.3 dan TLS 1.2 akan menonaktifkan TLS 1.0 dan 1.1 yang sudah usang. Port HTTPS default adalah 8443; petakan ke port 443 menggunakan load balancer atau pengalihan port jika Anda memerlukan port standar.

Langkah 5: Mulai ulang JBoss

Jika Anda mengedit standalone.xml secara manual, mulai ulang server agar konfigurasi baru dapat dimuat. Jika Anda menggunakan batch CLI di atas, perubahan diterapkan secara langsung, namun reload dapat memastikan proses startup berjalan bersih:

jboss-cli.sh --connect --command=:reload

Perhatikan log server untuk melihat adanya kesalahan SSL atau Elytron selama proses startup. Setelah server berhasil dimulai tanpa masalah, sertifikat SSL Anda telah terinstal di JBoss.

Uji instalasi SSL Anda

Setelah instalasi, pastikan sertifikat dan rantainya disajikan dengan benar. Buka situs Anda melalui HTTPS (misalnya https://www.yourdomain.com:8443) dan periksa ikon gembok, atau jalankan pemindaian eksternal dengan SSL Checker kami untuk mendapatkan laporan lengkap mengenai sertifikat, rantai, dan dukungan protokol. Anda juga dapat memeriksanya melalui baris perintah:

echo | openssl s_client -connect yourdomain.com:8443 -servername yourdomain.com 2>/dev/null | openssl x509 -noout -issuer -dates

Perintah ini akan menampilkan penerbit dan tanggal keberlakuan sertifikat yang disajikan JBoss. Jika penerbitnya adalah CA Anda (bukan entri self-signed), maka balasan tersebut telah berhasil diimpor dengan benar.

Pertanyaan yang Sering Diajukan