id›Guides›Server›Enabletls

Configuring TLS

Protokol Keamanan Lapisan Transportasi (singkatan: TLS) sangat penting untuk mengirim data melalui saluran yang aman. Untuk lingkungan produksi, Anda tidak boleh pernah mengekspos titik akhir NQRust-Identity melalui HTTP, karena data sensitif adalah inti dari apa yang NQRust-Identity tukar dengan aplikasi lain. Dalam panduan ini, Anda akan belajar cara mengonfigurasi NQRust-Identity untuk menggunakan HTTPS/TLS.

NQRust-Identity dapat dikonfigurasi untuk memuat infrastruktur sertifikat yang diperlukan menggunakan file dalam format PEM atau dari Java Keystore. Ketika kedua opsi dikonfigurasi, file PEM akan mengambil prioritas atas Java Keystores.

Menggunakan sertifikat dalam format PEM

Ketika Anda menggunakan pasangan sertifikat dan kunci privat yang cocok dalam format PEM, Anda dapat mengonfigurasi NQRust-Identity untuk menggunakannya dengan menjalankan perintah berikut:

bin/kc.[sh|bat] start --https-certificate-file=/path/to/certfile.pem --https-certificate-key-file=/path/to/keyfile.pem

NQRust-Identity akan membuat keystore dari file-file ini di dalam memori dan menggunakan keystore ini setelahnya.

Menggunakan Keystore

Ketika tidak ada file keystore yang dikonfigurasi secara eksplisit, tetapi http-enabled diatur ke false, NQRust-Identity akan mencari file conf/server.keystore.

Sebagai alternatif, Anda dapat menggunakan keystore yang ada dengan menjalankan perintah berikut:

bin/kc.[sh|bat] start --https-key-store-file=/path/to/existing-keystore-file

Ekstensi file yang dikenali untuk keystore:

.p12, .pkcs12, dan .pfx untuk file pkcs12
.jks, dan .keystore untuk file jks
.key, .crt, dan .pem untuk file pem

Jika keystore Anda tidak memiliki ekstensi yang cocok dengan tipe file, Anda juga harus mengatur opsi https-key-store-type.

Mengatur kata sandi Keystore

Anda dapat mengatur kata sandi yang aman untuk keystore Anda menggunakan opsi https-key-store-password:

bin/kc.[sh|bat] start --https-key-store-password=<value>

Jika tidak ada kata sandi yang diatur, kata sandi default password akan digunakan.

Mengamankan kredensial

Hindari pengaturan kata sandi dalam teks polos dengan menggunakan CLI atau menambahkannya ke file conf/keycloak.conf. Sebagai gantinya, gunakan praktik yang baik seperti menggunakan vault / secret yang di-mount. Untuk detail lebih lanjut, lihat Menggunakan vault dan Mengonfigurasi NQRust-Identity untuk produksi.

Mengonfigurasi protokol TLS

Secara default, NQRust-Identity tidak mengaktifkan protokol TLS yang usang. Jika klien Anda hanya mendukung protokol yang usang, pertimbangkan untuk mengupgrade klien. Namun, sebagai solusi sementara, Anda dapat mengaktifkan protokol yang usang dengan menjalankan perintah berikut:

bin/kc.[sh|bat] start --https-protocols=<protocol>[,<protocol>]

Sebagai contoh, untuk hanya mengaktifkan TLSv1.3, gunakan perintah seperti berikut: kc.sh start --https-protocols=TLSv1.3.

Mengganti port HTTPS

NQRust-Identity mendengarkan lalu lintas HTTPS pada port 8443. Untuk mengubah port ini, gunakan perintah berikut:

bin/kc.[sh|bat] start --https-port=<port>

Pengisian Ulang Sertifikat dan Kunci

Secara default, NQRust-Identity akan mengisi ulang sertifikat, kunci, dan keystore yang dijelaskan dalam opsi https-* setiap jam. Untuk lingkungan di mana kunci server Anda mungkin perlu rotasi yang kerap, ini memungkinkan hal tersebut terjadi tanpa restart server. Anda dapat mengganti default melalui opsi https-certificates-reload-period. Interval untuk mengisi ulang keystore, trust store, dan file sertifikat yang dirujuk oleh opsi https-*. Nilai dapat berupa nilai java.time.Duration, bilangan bulat jumlah detik, atau bilangan bulat diikuti satuan waktu [ms, h, m, s, d]. Harus lebih besar dari 30 detik. Gunakan -1 untuk menonaktifkan.

Opsi yang Relevan

Opsi	Tipe atau Nilai	Default
`http-enabled` Mengaktifkan listener HTTP. Default aktif dalam mode development. Biasanya tidak diaktifkan dalam produksi kecuali server di depan proxy pengakhiran TLS. CLI: `--http-enabled` Env: `KC_HTTP_ENABLED`	`true`, `false`	`false`
`https-certificate-file` Alamat file sertifikat server atau rantai sertifikat dalam format PEM. CLI: `--https-certificate-file` Env: `KC_HTTPS_CERTIFICATE_FILE`	File
`https-certificate-key-file` Alamat file kunci pribadi dalam format PEM. CLI: `--https-certificate-key-file` Env: `KC_HTTPS_CERTIFICATE_KEY_FILE`	File
`https-certificates-reload-period` Interval untuk memuat ulang toko kunci, toko kepercayaan, dan file sertifikat yang dirujuk oleh opsi https-. Mungkin merupakan nilai durasi ISO 8601, bilangan bulat detik, atau bilangan bulat diikuti salah satu [ms, h, m, s, d]. Harus lebih besar dari 30 detik. Gunakan -1 untuk menonaktifkan. CLI:* `--https-certificates-reload-period` Env: `KC_HTTPS_CERTIFICATES_RELOAD_PERIOD`	String	`1h`
`https-cipher-suites` Suite cipher yang digunakan. Jika tidak diberikan, default yangreasonable dipilih. CLI: `--https-cipher-suites` Env: `KC_HTTPS_CIPHER_SUITES`	String
`https-key-store-file` Toko kunci yang memegang informasi sertifikat sebagai gantinya daripada menentukan file terpisah. CLI: `--https-key-store-file` Env: `KC_HTTPS_KEY_STORE_FILE`	File
`https-key-store-password` Kata sandi file toko kunci. CLI: `--https-key-store-password` Env: `KC_HTTPS_KEY_STORE_PASSWORD`	String	`password`
`https-key-store-type` Tipe file toko kunci. Jika tidak diberikan, tipe otomatis terdeteksi berdasarkan ekstensi file. Jika `fips-mode` diatur ke `strict` dan tidak ada nilai yang diatur, default ke `BCFKS`. CLI: `--https-key-store-type` Env: `KC_HTTPS_KEY_STORE_TYPE`	String
`https-port` Port HTTPS yang digunakan. CLI: `--https-port` Env: `KC_HTTPS_PORT`	Integer	`8443`
`https-protocols` Daftar protokol untuk diaktifkan secara eksplisit. Jika nilai tidak didukung oleh JRE / konfigurasi keamanan, akan diam-diam diabaikan. CLI: `--https-protocols` Env: `KC_HTTPS_PROTOCOLS`	`TLSv1.3`, `TLSv1.2`, atau apapun	`TLSv1.3,TLSv1.2`

Server Pengelolaan

Opsi	Tipe atau Nilai	Default
`https-management-certificate-file` Alamat file sertifikat server atau rantai sertifikat dalam format PEM untuk server pengelolaan. Jika tidak diberikan, nilai diwarisi dari opsi HTTP. Hanya relevan saat sesuatu diekspos di antarmuka pengelolaan - lihat panduan untuk detail. CLI: `--https-management-certificate-file` Env: `KC_HTTPS_MANAGEMENT_CERTIFICATE_FILE`	File
`https-management-certificate-key-file` Alamat file kunci pribadi dalam format PEM untuk server pengelolaan. Jika tidak diberikan, nilai diwarisi dari opsi HTTP. Hanya relevan saat sesuatu diekspos di antarmuka pengelolaan - lihat panduan untuk detail. CLI: `--https-management-certificate-key-file` Env: `KC_HTTPS_MANAGEMENT_CERTIFICATE_KEY_FILE`	File
`https-management-certificates-reload-period` Interval untuk memuat ulang toko kunci, toko kepercayaan, dan file sertifikat yang dirujuk oleh opsi https-management-* untuk server pengelolaan. Mungkin merupakan nilai durasi ISO 8601, bilangan bulat detik, atau bilangan bulat diikuti salah satu [ms, h, m, s, d]. Harus lebih besar dari 30 detik. Gunakan -1 untuk menonaktifkan. Jika tidak diberikan, nilai diwarisi dari opsi HTTP. Hanya relevan saat sesuatu diekspos di antarmuka pengelolaan - lihat panduan untuk detail. CLI: `--https-management-certificates-reload-period` Env: `KC_HTTPS_MANAGEMENT_CERTIFICATES_RELOAD_PERIOD`	String	`1h`
`https-management-key-store-file` Toko kunci yang memegang informasi sertifikat sebagai gantinya daripada menentukan file terpisah untuk server pengelolaan. Jika tidak diberikan, nilai diwarisi dari opsi HTTP. Hanya relevan saat sesuatu diekspos di antarmuka pengelolaan - lihat panduan untuk detail. CLI: `--https-management-key-store-file` Env: `KC_HTTPS_MANAGEMENT_KEY_STORE_FILE`	File
`https-management-key-store-password` Kata sandi file toko kunci untuk server pengelolaan. Jika tidak diberikan, nilai diwarisi dari opsi HTTP. Hanya relevan saat sesuatu diekspos di antarmuka pengelolaan - lihat panduan untuk detail. CLI: `--https-management-key-store-password` Env: `KC_HTTPS_MANAGEMENT_KEY_STORE_PASSWORD`	String	`password`

Struktur Direktori Mengonfigurasi hostname