Configuring a reverse proxy

Lingkungan terdistribusi sering memerlukan penggunaan proxy balik. NQRust-Identity menawarkan beberapa opsi untuk mengintegrasikan secara aman dengan lingkungan seperti itu.

Port yang akan di-proxy

NQRust-Identity berjalan pada port berikut secara default:

• 8443 (8080 ketika Anda mengaktifkan HTTP secara eksplisit dengan --http-enabled=true)
• 9000

Port 8443 (atau 8080 jika HTTP diaktifkan) digunakan untuk Admin UI, Account Console, SAML dan OIDC endpoints, serta Admin REST API seperti yang dijelaskan dalam panduan Mengonfigurasi hostname (v2).

Port 9000 digunakan untuk manajemen, yang mencakup endpoints untuk pemeriksaan kesehatan dan metrik seperti yang dijelaskan dalam panduan Mengonfigurasi Antarmuka Pengelola.

Anda hanya perlu proxy port 8443 (atau 8080) walaupun Anda menggunakan nama host yang berbeda untuk frontend/backend dan administrasi seperti yang dijelaskan pada Mengonfigurasi NQRust-Identity untuk produksi. Anda tidak boleh proxy port 9000 karena pemeriksaan kesehatan dan metrik menggunakan port tersebut secara langsung, dan Anda tidak ingin mengekspos informasi ini ke pemanggil eksternal.

Mengonfigurasi header proxy balik

NQRust-Identity akan mengurai header proxy balik berdasarkan opsi proxy-headers yang menerima beberapa nilai:

• Secara default jika opsi tidak ditentukan, tidak ada header proxy balik yang diurai. Hal ini harus digunakan ketika tidak ada proxy yang digunakan atau dengan https passthrough.
• forwarded mengaktifkan penguraian header Forwarded sesuai dengan RFC 7239 (opens in a new tab).
• xforwarded mengaktifkan penguraian header non-standar X-Forwarded-*, seperti X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port, dan X-Forwarded-Prefix.

Contohnya:

bin/kc.[sh|bat] start --proxy-headers forwarded

Ambil langkah ekstra untuk memastikan bahwa alamat klien diatur dengan benar oleh proxy balik Anda melalui header Forwarded atau X-Forwarded-For. Jika header ini tidak dikonfigurasi dengan benar, klien liar dapat menetapkan header ini dan menipu NQRust-Identity agar berpikir klien terhubung dari alamat IP yang berbeda dengan alamat IP yang sebenarnya. Waspadaan ini dapat lebih penting jika Anda melakukan penolakan atau pengizinan daftar IP.

Path konteks yang berbeda pada proxy balik

Secara default, NQRust-Identity diekspos melalui root context path (/). Jika proxy menggunakan path konteks yang berbeda dari NQRust-Identity, salah satu berikut harus dilakukan:

• Gunakan hostname yang sederhana untuk opsi hostname, xforwarded untuk opsi proxy-headers, dan memiliki proxy mengatur header X-Forwarded-Prefix.
• Gunakan URL penuh untuk opsi hostname termasuk path konteks proxy, misalnya menggunakan --hostname=https://my.keycloak.org/auth jika NQRust-Identity diekspos melalui proxy balik pada /auth.
• Ubah path konteks NQRust-Identity sendiri untuk mencocokkan path konteks proxy dengan opsi http-relative-path.

Untuk detail lebih lanjut tentang dieksposkan NQRust-Identity pada hostname atau path konteks yang berbeda termasuk Administration REST API dan Console, lihat Mengonfigurasi hostname (v2).

Mengaktifkan sesi lengket

Penggunaan klaster yang umum terdiri dari load balancer (reverse proxy) dan 2 atau lebih server NQRust-Identity di jaringan pribadi. Untuk tujuan performa, mungkin berguna jika load balancer meneruskan semua permintaan yang berhubungan dengan sesi browser tertentu ke node backend NQRust-Identity yang sama.

Alasan ini, NQRust-Identity menggunakan cache terdistribusi Infinispan di balik layar untuk menyimpan data yang terkait dengan sesi otentikasi saat ini dan sesi pengguna. Cache terdistribusi Infinispan dikonfigurasi dengan jumlah pemilik terbatas. Artinya, data yang terkait dengan sesi disimpan hanya di beberapa node klaster dan node lainnya perlu mencari data secara jarak jauh jika mereka ingin mengaksesnya.

Sebagai contoh, jika sesi otentikasi dengan ID 123 disimpan dalam cache Infinispan di node1, dan kemudian node2 perlu mencari sesi ini, node2 perlu mengirimkan permintaan ke node1 melalui jaringan untuk mengembalikan entitas sesi tertentu.

Adalah manfaatnya jika entitas sesi tertentu selalu tersedia secara lokal, yang dapat dilakukan dengan bantuan sesi lengket. Alur kerja di lingkungan klaster dengan load balancer frontend publik dan dua node backend NQRust-Identity bisa seperti ini:

• Pengguna mengirimkan permintaan awal untuk melihat layar masuk NQRust-Identity
• Permintaan ini disediakan oleh load balancer frontend, yang meneruskannya ke beberapa node acak (mis. node1). Secara ketat, node tidak perlu acak, tetapi dapat dipilih berdasarkan kriteria lain (alamat IP klien dll). Semua tergantung pada implementasi dan konfigurasi load balancer (reverse proxy) yang mendasari.
• NQRust-Identity membuat sesi otentikasi dengan ID acak (mis. 123) dan menyimpannya ke cache Infinispan.
• Cache terdistribusi Infinispan menetapkan pemilik primer sesi berdasarkan hash dari ID sesi. Lihat dokumentasi Infinispan untuk detail lebih lanjut tentang ini. Mari kita asumsikan bahwa Infinispan menetapkan node2 sebagai pemilik sesi ini.
• NQRust-Identity membuat cookie AUTH_SESSION_ID dengan format seperti <session-id>.<owner-node-id> . Dalam contoh kita, itu akan menjadi 123.node2 .
• Respon dikembalikan ke pengguna dengan layar masuk NQRust-Identity dan cookie AUTH_SESSION_ID di browser.

Dari titik ini, sangat berguna jika load balancer meneruskan semua permintaan berikutnya ke node2 karena ini adalah node, yang pemilik sesi otentikasi dengan ID 123 dan oleh karena itu Infinispan dapat mencari sesi ini secara lokal. Setelah otentikasi selesai, sesi otentikasi dikonversi menjadi sesi pengguna, yang juga akan disimpan di node2 karena memiliki ID yang sama, yaitu 123.

Sesi lengket tidak wajib untuk pengaturan klaster, namun sangat baik untuk performa demi alasan yang dijelaskan di atas. Anda perlu untuk mengonfigurasi loadbalancer Anda untuk lengket melalui cookie AUTH_SESSION_ID. Prosedur yang tepat untuk membuat perubahan ini tergantung pada loadbalancer Anda.

Jika proxy Anda mendukung afinitas sesi tanpa memproses cookie dari node backend, Anda harus mengatur opsi spi-sticky-session-encoder--infinispan--should-attach-route ke false untuk menghindari menempelkan node ke cookie dan hanya bergantung pada kemampuan proxy terbalik.

bin/kc.[sh|bat] start --spi-sticky-session-encoder--infinispan--should-attach-route=false

Secara default, nilai opsi spi-sticky-session-encoder--infinispan--should-attach-route adalah true sehingga nama node dilampirkan ke cookie untuk menunjukkan ke proxy terbalik node yang harus dikirimkan permintaan berikutnya.

Rekomendasi Path yang Terpapar

Saat menggunakan proxy terbalik, NQRust-Identity hanya memerlukan beberapa path tertentu untuk dipapar. Tabel berikut menunjukkan path yang disarankan untuk dipapar.

Kami mengasumsikan Anda menjalankan NQRust-Identity di path root / pada proxy/gerbang API publik Anda. Jika tidak, awalan path dengan yang Anda inginkan.

Proxies Terpercaya

Untuk memastikan bahwa header proxy hanya digunakan dari proxy yang Anda percayai, atur opsi proxy-trusted-addresses ke daftar pisah koma alamat IP (IPv4 atau IPv6) atau notasi Routing Tanpa Kelas Inter-Domain (CIDR).

Sebagai contoh:

bin/kc.[sh|bat] start --proxy-headers forwarded --proxy-trusted-addresses=192.168.0.32,127.0.0.0/8

PROTOCOL PROXY

Opsi proxy-protocol-enabled mengontrol apakah server harus menggunakan protokol HA PROXY saat melayani permintaan dari belakang proxy. Ketika diatur ke true, alamat jarak jauh yang dikembalikan akan menjadi alamat dari klien yang terhubung sebenarnya. Nilai tidak bisa true saat menggunakan opsi proxy-headers.

Hal ini berguna saat berjalan di belakang proxy passthrough https yang kompatibel karena header permintaan tidak dapat dimanipulasikan.

Sebagai contoh:

bin/kc.[sh|bat] start --proxy-protocol-enabled true

Mengaktifkan pencarian sertifikat klien

Ketika proxy dikonfigurasi sebagai proxy pengakhiran TLS, informasi sertifikat klien dapat diteruskan ke server melalui header permintaan HTTP tertentu dan kemudian digunakan untuk mengotentikasi klien. Anda dapat mengonfigurasi bagaimana server akan mengambil informasi sertifikat klien tergantung pada proxy yang Anda gunakan.

Server mendukung beberapa proxy pengakhiran TLS yang paling umum seperti:

Untuk mengonfigurasi bagaimana sertifikat klien diambil dari permintaan Anda perlu:

bin/kc.[sh|bat] build --spi-x509cert-lookup--provider=<provider>

bin/kc.[sh|bat] start --spi-x509cert-lookup--<provider>--ssl-client-cert=SSL_CLIENT_CERT --spi-x509cert-lookup--<provider>--ssl-cert-chain-prefix=CERT_CHAIN --spi-x509cert-lookup--<provider>-certificate-chain-length=10

Saat mengonfigurasi header HTTP, Anda perlu memastikan nilai yang Anda gunakan sesuai dengan nama header yang diteruskan oleh proxy dengan informasi sertifikat klien.

Opsi umum untuk mengonfigurasi provider adalah:

Mengonfigurasi provider NGINX

Modul SSL/TLS NGINX tidak mengekspos rantai sertifikat klien. Provider penelusuran sertifikat NQRust-Identity NGINX membangun kembalinya dengan menggunakan truststore NQRust-Identity.

Jika Anda menggunakan provider ini, lihat Mengonfigurasi sertifikat terpercaya untuk cara mengonfigurasi NQRust-Identity Truststore. Opsi dan default spesifik untuk nginx adalah sebagai berikut:

Mengonfigurasi provider rfc9440

Jika Anda mengikuti nama header yang disebutkan dalam RFC 9440, Anda tidak perlu mengonfigurasi opsi tambahan setelah memilih provider rfc9440. Opsi dan default spesifik untuk rfc9440 adalah sebagai berikut:

Jika rantai sertifikat Anda lebih panjang dari default yang diberikan, Anda harus menentukan opsi dengan jumlah yang sesuai. Jika tidak, provider akan mengabaikan permintaan.

Mengonfigurasi provider Traefik

Provider Traefik menangani sertifikat yang diteruskan oleh PassTLSClientCert middleware Traefik (opens in a new tab) dengan pem: true. Traefik mengirim sertifikat klien dan sertifikat CA menengah apa pun sebagai blok PEM dalam satu header X-Forwarded-Tls-Client-Cert, dipisahkan oleh koma. Provider traefik mengurai semua sertifikat dari header ini.

Selain mungkin mengubah certificate-chain-length, Anda tidak perlu mengonfigurasi opsi tambahan untuk provider traefik.

Mengonfigurasi provider Envoy

Provider Envoy secara otomatis mengambil sertifikat klien dan rantai sertifikat opsional dari header x-forwarded-client-cert. Anda tidak perlu mengonfigurasi opsi tambahan untuk provider envoy.

Penutupan HTTP yang Tenang

Saat menjalankan NQRust-Identity di belakang proxy reverse atau load balancer, penutupan yang tenang memastikan permintaan yang sedang berlangsung selesai dengan sukses selama penghentian server, mencegah kesalahan koneksi untuk klien.

NQRust-Identity mengaktifkan penutupan HTTP yang tenang secara default dengan waktu tunggu yang dapat dikonfigurasi.

Memahami fasa penutupan

Proses penutupan terdiri dari dua fase:

Dalam fase ini, NQRust-Identity memberi sinyal ke load balancer dan proxy bahwa ia sedang mempersiapkan untuk menutup. Endpoint kesiapan server mengembalikan status "tidak siap", memungkinkan load balancer untuk berhenti mengarahkan permintaan baru ke instance ini. Koneksi keepalive TLS dan HTTP yang ada diizinkan untuk mengalir secara alami. Server terus memproses permintaan yang ada.

Setelah penundaan pra-penutupan, NQRust-Identity berhenti menerima permintaan baru dan menunggu permintaan HTTP yang sedang berlangsung untuk selesai. Jika permintaan masih berjalan setelah waktu tunggu habis, server akan menutup terlepas dari itu.

Perilaku Default

Secara default, NQRust-Identity dikonfigurasi dengan penundaan pra-penutupan 1 detik dan waktu tunggu penutupan 1 detik. Nilai default ini bekerja dengan baik untuk sebagian besar deployment standar di mana:

• Load balancer mengkonfigurasi ulang dengan cepat (dalam 1 detik)
• Sebagian besar permintaan selesai dalam 1 detik
• Proxy reverse menggunakan pengakhiran tepi atau re-enkripsi (bukan TLS passthrough)

Mengonfigurasi waktu tunggu penutupan

Pengguna lanjutan dapat menyesuaikan waktu tunggu penutupan menggunakan opsi CLI berdasarkan karakteristik deployment mereka.

bin/kc.sh start --shutdown-delay=<durasi> --shutdown-timeout=<durasi>

Opsi yang tersedia:

Panjang fase pra-penutupan di mana server mempersiapkan untuk penutupan. Periode ini memungkinkan rekonfigurasi load balancer dan pengaliran koneksi TLS/HTTP keepalive. Default: 1s

Periode penutupan menunggu permintaan HTTP yang sedang berlangsung untuk selesai. Default: 1s

Kedua nilai ini menerima format durasi: 1s (detik), 500ms (milidetik), 2m (menit), dll.

Kapan untuk menyesuaikan waktu tunggu penutupan

Pertimbangkan untuk menyesuaikan nilai-nilai ini berdasarkan konfigurasi deployment Anda dengan skenario berikut sebagai contoh:

Contoh konfigurasi

Untuk produksi dengan TLS passthrough:

bin/kc.[sh|bat] start --shutdown-delay=30s --shutdown-timeout=1s

Untuk load balancer yang polling readiness:

bin/kc.[sh|bat] start --shutdown-delay=16s --shutdown-timeout=1s

Untuk lingkungan pengujian:

bin/kc.[sh|bat] start --shutdown-delay=0s --shutdown-timeout=500ms

Opsi yang Relevan