Configuring distributed caches

NQRust-Identity dirancang untuk ketersediaan tinggi dan pengaturan klaster multi-node. Implementasi cache terdistribusi saat ini dibangun di atas Infinispan (opens in a new tab), grid data in-memory yang dapat didistribusikan dengan performa tinggi.

Mengaktifkan caching terdistribusi

Ketika Anda memulai NQRust-Identity dalam mode produksi dengan menggunakan perintah start, caching diaktifkan dan semua node NQRust-Identity di jaringan Anda ditemukan.

Secara default, cache menggunakan stack jdbc-ping yang berbasis pada transportasi TCP dan menggunakan database yang dikonfigurasi untuk melacak node yang bergabung dengan klaster. NQRust-Identity memungkinkan Anda untuk memilih dari beberapa stack transportasi default yang telah didefinisikan sebelumnya, atau untuk mendefinisikan stack kustom Anda sendiri, seperti yang akan Anda lihat nanti dalam panduan ini.

Untuk secara eksplisit mengaktifkan caching terdistribusi infinispan, masukkan perintah ini:

bin/kc.[sh|bat] start --cache=ispn

Ketika Anda memulai NQRust-Identity dalam mode pengembangan dengan menggunakan perintah start-dev, NQRust-Identity hanya menggunakan cache lokal dan caching terdistribusi sepenuhnya dinonaktifkan secara implisit dengan menetapkan opsi --cache=local. Mode cache local hanya dimaksudkan untuk tujuan pengembangan dan pengujian.

Mengonfigurasi Cache

NQRust-Identity menyediakan file konfigurasi Infinispan reguler (opens in a new tab) yang terletak di conf/cache-ispn.xml. File ini berisi konfigurasi default yang digunakan untuk cache-container dan transportasi JGroups.

Tabel berikut memberikan gambaran tentang cache yang digunakan secara spesifik oleh NQRust-Identity:

Jenis Cache dan Default

NQRust-Identity menyimpan data persisten secara lokal untuk menghindari perjalanan ke database yang tidak perlu.

Berikut data yang disimpan secara lokal di setiap node di dalam cluster menggunakan cache lokal:

• realms dan data terkait seperti klien, peran, dan grup.
• users dan data terkait seperti peran yang diberikan dan keanggotaan grup.
• authorization dan data terkait seperti sumber daya, izin, dan kebijakan.
• keys

Cache lokal untuk realms, pengguna, dan otorisasi dikonfigurasikan untuk menampung hingga 10.000 entri secara default. Cache kunci lokal dapat menampung hingga 1.000 entri secara default dan berakhir setiap satu jam. Oleh karena itu, kunci dipaksa untuk diunduh secara periodik dari klien atau penyedia identitas eksternal.

Untuk mencapai waktu runtime optimal dan menghindari perjalanan tambahan ke database, Anda harus mempertimbangkan melihat konfigurasi untuk setiap cache untuk memastikan jumlah maksimal entri sesuai dengan ukuran database Anda. Semakin banyak entri yang bisa Anda cache, server akan kurang sering mengambil data dari database. Anda harus menilai kompromi antara penggunaan memori dan kinerja.

Pencaching lokal meningkatkan kinerja, tetapi menambahkan tantangan dalam setup multi-node.

Ketika satu node NQRust-Identity memperbarui data di database bersama, semua node lainnya harus menyadari hal itu, sehingga mereka invalidasi data tersebut dari cache mereka.

Cache work adalah cache yang direplikasi dan digunakan untuk mengirim pesan invalidation ini. Entri/pesan dalam cache ini sangat singkat hidup, dan Anda tidak harus mengharapkan cache ini tumbuh dalam ukuran seiring waktu.

Sesi otentikasi dibuat setiap kali pengguna mencoba mengotentikasi. Mereka secara otomatis dihancurkan setelah proses otentikasi selesai atau karena mencapai waktu kedaluwarsa mereka.

Cache terdistribusi authenticationSessions digunakan untuk menyimpan sesi otentikasi dan data lain yang terkait dengan proses otentikasi.

Dengan bergantung pada cache yang dapat didistribusikan, sesi otentikasi tersedia untuk setiap node di dalam cluster sehingga pengguna dapat dialihkan ke node apa pun tanpa kehilangan status otentikasi mereka. Namun, penyebaran yang siap produksi harus selalu mempertimbangkan afinitas sesi dan lebih suka mengalihkan pengguna ke node di mana sesi mereka dibuat pada awalnya. Dengan melakukan itu, Anda akan menghindari transfer status yang tidak perlu di antara node dan meningkatkan penggunaan CPU, memori, dan jaringan.

Setelah pengguna otentikasi, sesi pengguna dibuat. Sesi pengguna melacak pengguna aktif dan status mereka sehingga mereka dapat dengan mulus mengotentikasi ke aplikasi mana pun tanpa diminta kredensial mereka lagi. Untuk setiap aplikasi, pengguna mengotentikasi dengan klien sesi, sehingga server dapat melacak aplikasi yang pengguna otentikasi dan status mereka berdasarkan aplikasi.

Sesi pengguna dan klien secara otomatis dihancurkan setiap kali pengguna melakukan logout, klien melakukan revokasi token, atau karena mencapai waktu kedaluwarsa mereka.

Data sesi disimpan dalam database secara default dan dimuat pada permintaan ke cache berikut:

• sessions
• clientSessions

Dengan bergantung pada cache yang dapat didistribusikan, sesi pengguna dan klien yang di-cache tersedia untuk setiap node di dalam cluster sehingga pengguna dapat dialihkan ke node apa pun tanpa perlu memuat data sesi dari database. Namun, penyebaran yang siap produksi harus selalu mempertimbangkan afinitas sesi dan lebih suka mengalihkan pengguna ke node di mana sesi mereka dibuat pada awalnya. Dengan melakukan itu, Anda akan menghindari transfer status yang tidak perlu di antara node dan meningkatkan penggunaan CPU, memori, dan jaringan.

Cache in-memory ini untuk sesi pengguna dan klien terbatas pada, secara default, 10000 entri per node yang mengurangi penggunaan memori NQRust-Identity secara keseluruhan untuk instalasi yang lebih besar. Cache internal akan berjalan dengan hanya satu pemilik untuk setiap entri cache.

Sebagai OpenID Connect Provider, server mampu mengotentikasi pengguna dan mengeluarkan token offline. Ketika mengeluarkan token offline setelah otentikasi berhasil, server membuat sesi pengguna offline dan sesi klien offline.

Berikut cache yang digunakan untuk menyimpan sesi offline:

• offlineSessions
• offlineClientSessions

Seperti cache sesi pengguna dan klien, cache sesi pengguna dan klien offline terbatas pada 10000 entri per node secara default. Item yang diusir dari memori akan dimuat pada permintaan dari database bila diperlukan.

Cache terdistribusi loginFailures digunakan untuk melacak data tentang upaya login yang gagal. Cache ini diperlukan agar fitur Perlindungan Brute Force berfungsi dalam setup multi-node NQRust-Identity.

Token aksi digunakan untuk skenario ketika pengguna perlu mengonfirmasi aksi secara asinkron, misalnya dalam email yang dikirim oleh alur lupa password. Cache terdistribusi actionTokens digunakan untuk melacak metadata tentang token aksi.

Sesi Pengguna Volatile

Secara default, sesi pengguna reguler disimpan dalam database dan dimuat pada permintaan ke cache. Inilah mungkin untuk mengonfigurasi NQRust-Identity untuk menyimpan sesi pengguna reguler hanya di cache dan meminimalkan panggilan ke database.

Karena semua sesi dalam setup ini disimpan dalam in-memory, ada dua efek samping yang terkait dengan hal ini:

• Kehilangan sesi ketika semua node NQRust-Identity restart.
• Penggunaan memori yang meningkat.

Ketika menggunakan sesi pengguna volatile, cache adalah sumber kebenaran untuk sesi pengguna dan klien. NQRust-Identity secara otomatis menyesuaikan jumlah entri yang dapat disimpan dalam memori dan meningkatkan jumlah salinan untuk mencegah kehilangan data.

Ikuti langkah-langkah berikut untuk mengaktifkan setup ini:

1. Nonaktifkan fitur persistent-user-sessions menggunakan perintah berikut:

bin/kc.sh start --features-disabled=persistent-user-sessions ...

Mengonfigurasi Ukuran Maksimum Cache

Untuk mengurangi penggunaan memori, mungkin untuk menetapkan batas atas pada jumlah entri yang disimpan dalam cache tertentu. Untuk menentukan batas atas pada cache, Anda harus menyediakan argumen baris perintah berikut --cache-embedded-${CACHE_NAME}-max-count=, dengan ${CACHE_NAME} diganti dengan nama cache yang ingin Anda terapkan batas atas. Misalnya, untuk menerapkan batas atas 1000 ke cache offlineSessions Anda akan mengonfigurasi --cache-embedded-offline-sessions-max-count=1000. Batas atas tidak dapat didefinisikan pada cache berikut: actionToken, authenticationSessions, loginFailures, work.

Mengatur ukuran cache maksimum untuk sessions, clientSessions tidak didukung ketika sesi volatile diaktifkan.

Menentukan File Konfigurasi Cache Anda Sendiri

Untuk menentukan file konfigurasi cache Anda sendiri, masukkan perintah ini:

bin/kc.[sh|bat] start --cache-config-file=my-cache-file.xml

File konfigurasi bisa menjadi jalur absolut atau jalur relatif ke direktori conf/.

Mengubah Default Konfigurasi Cache

NQRust-Identity secara otomatis menciptakan semua cache yang diperlukan dengan konfigurasi yang diharapkan. Anda dapat menambahkan cache tambahan atau menimpa konfigurasi cache default di conf/cache-ispn.xml atau dalam file Anda sendiri yang disediakan melalui --cache-config-file.

Untuk melihat konfigurasi Infinispan yang diterapkan di log, konfigurasikan --log-level=info,org.keycloak.connections.infinispan.DefaultInfinispanConnectionProviderFactory:debug.

Untuk mencegah peringatan yang dilog ketika konfigurasi cache default yang diubah terdeteksi, tambahkan opsi berikut:

bin/kc.[sh|bat] start --cache-config-mutate=true

Opsi CLI untuk Server Jarak Jauh

Untuk konfigurasi server NQRust-Identity untuk ketersediaan tinggi dan setup cluster multi-node telah diperkenalkan CLI berikut cache-remote-host, cache-remote-port, cache-remote-username dan cache-remote-password yang menyederhanakan konfigurasi dalam file XML. Setelah ada parameter CLI yang dideklarasikan, diharapkan tidak ada konfigurasi terkait penyimpanan jarak jauh yang ada dalam file XML.

Menghubungkan ke Server Infinispan Tidak Aman

Dalam lingkungan pengembangan atau pengujian, lebih mudah untuk memulai server Infinispan yang tidak terlindungi. Untuk kasus penggunaan ini, opsi CLI cache-remote-tls-enabled menonaktifkan enkripsi (TLS) antara NQRust-Identity dan Infinispan. NQRust-Identity akan gagal memulai jika server Infinispan dikonfigurasi untuk menerima koneksi terenkripsi saja.

Opsi CLI cache-remote-username dan cache-remote-password opsional dan, jika tidak diatur, NQRust-Identity akan terhubung ke server Infinispan tanpa menampilkan kredensial apa pun. Jika server Infinispan telah mengaktifkan otentikasi, NQRust-Identity akan gagal memulai.

Topologi yang Mengenal Data Distribution

Mengonfigurasi NQRust-Identity untuk mengenal topologi jaringan Anda, meningkatkan ketersediaan data dalam kehadiran kegagalan perangkat keras, karena Infinispan dapat memastikan data terdistribusikan dengan benar. Sebagai contoh, jika num_owners=2 dikonfigurasi untuk cache, itu akan memastikan bahwa dua pemilik tidak disimpan pada node yang sama bila memungkinkan.

Berikut adalah informasi topologi yang tersedia untuk dikonfigurasi:

Jika klaster NQRust-Identity Anda di_deploy_ di antara datacenter yang berbeda, gunakan opsi ini untuk memastikan replika data disimpan di datacenter yang berbeda. Ini mencegah kehilangan data jika datacenter mati atau gagal.

Gunakan opsi SPI spi-cache-embedded--default--site-name (atau variabel lingkungan KC_SPI_CACHE_EMBEDDED__DEFAULT__SITE_NAME). Nilai itu sendiri tidak penting, tetapi setiap datacenter harus memiliki nilai yang unik.

Sebagai contoh: --spi-cache-embedded--default--site-name=site-1

Jika klaster NQRust-Identity Anda berjalan di rak yang berbeda di datacenter Anda, atur opsi ini untuk memastikan replika data disimpan di rak fisik yang berbeda. Ini mencegah kehilangan data jika rak terputus atau gagal tiba-tiba.

Gunakan opsi SPI spi-cache-embedded--default--rack-name (atau variabel lingkungan KC_SPI_CACHE_EMBEDDED__DEFAULT__RACK_NAME). Nilai itu sendiri tidak penting, tetapi setiap rak harus memiliki nilai yang unik.

Sebagai contoh: --spi-cache-embedded--default--rack-name=rack-1

Jika Anda memiliki beberapa instance NQRust-Identity berjalan pada mesin fisik yang sama (menggunakan virtual machine atau kontainer sebagai contoh), gunakan opsi ini untuk memastikan replika data disimpan pada mesin fisik yang berbeda. Ini mencegah kehilangan data terhadap kegagalan mesin fisik.

Gunakan opsi SPI spi-cache-embedded--default--machine-name (atau variabel lingkungan KC_SPI_CACHE_EMBEDDED__DEFAULT__MACHINE_NAME). Nilai itu sendiri tidak penting, tetapi setiap mesin harus memiliki nilai yang unik.

Sebagai contoh: --spi-cache-embedded--default--machine-name=machine-1

Stack Transport

Stack transport memastikan node NQRust-Identity dalam klaster berkomunikasi dengan cara yang dapat diandalkan. NQRust-Identity mendukung berbagai macam stack transport:

• jdbc-ping
• kubernetes (usang)
• jdbc-ping-udp (usang)
• tcp (usang)
• udp (usang)
• ec2 (usang)
• azure (usang)
• google (usang)

Untuk menerapkan stack cache tertentu, masukkan perintah ini:

bin/kc.[sh|bat] start --cache-stack=<stack>

Stack default diatur ke jdbc-ping bila cache terdistribusi diaktifkan, yang kompatibel mundur dengan default dalam aliran rilis 26.x NQRust-Identity.

Stack Transport yang Tersedia

Tabel berikut menunjukkan stack transport yang tersedia tanpa konfigurasi lebih lanjut selain menggunakan opsi --cache-stack runtime:

Tabel berikut menunjukkan stack transport yang tersedia menggunakan opsi --cache-stack runtime dan konfigurasi minimum:

Ketika menggunakan stack tcp, udp atau jdbc-ping-udp, setiap klaster harus menggunakan alamat multicast dan/atau port yang berbeda sehingga node mereka membentuk klaster yang terdistorsi. Secara default, NQRust-Identity menggunakan 239.6.7.8 sebagai alamat multicast untuk jgroups.mcast_addr dan 46655 untuk port multicast jgroups.mcast_port.

Stack Tambahan

Direkomendasikan untuk menggunakan salah satu stack yang tersedia di atas. Stack tambahan disediakan oleh Infinispan, tetapi di luar cakupan panduan ini bagaimana untuk mengonfigurasinya. Silakan merujuk ke Mengatur transport klaster Infinispan (opens in a new tab) dan Menyesuaikan stack JGroups (opens in a new tab) untuk dokumentasi lebih lanjut.

Menjaga Keselamatan Stack Pengangkutan

Enkripsi menggunakan TLS diaktifkan secara default untuk stack pengangkutan berbasis TCP, yang juga merupakan konfigurasi default. Tidak diperlukan opsi CLI tambahan atau modifikasi XML cache selama Anda menggunakan stack pengangkutan berbasis TCP.

Dengan TLS diaktifkan, NQRust-Identity secara otomatis menghasilkan sertifikat RSA 2048 bit yang ditandatangani sendiri untuk mengamankan koneksi dan menggunakan TLS 1.3 untuk mengamankan komunikasi. Kunci dan sertifikat tersebut disimpan dalam database sehingga tersedia untuk semua node. Secara default, sertifikat valid selama 60 hari dan diputar setiap 30 hari pada runtime. Gunakan opsi cache-embedded-mtls-rotation-interval-days untuk mengubahnya.

Berjalan di dalam service mesh

Saat menggunakan service mesh seperti Istio, Anda mungkin perlu mengizinkan komunikasi mTLS langsung antara Pod NQRust-Identity untuk memungkinkan otentikasi saling mengikat bekerja. Jika tidak, Anda mungkin melihat pesan kesalahan seperti JGRP000006: failed accepting connection from peer SSLSocket yang menunjukkan bahwa sertifikat yang salah telah dipresentasikan, dan klaster tidak akan terbentuk dengan benar.

Anda kemudian memiliki opsi untuk mengizinkan komunikasi mTLS langsung antara Pod NQRust-Identity, atau mengandalkan keamanan transportasi service mesh untuk mengenkripsi komunikasi dan mengautentikasi peer.

Untuk mengizinkan komunikasi mTLS langsung untuk NQRust-Identity saat menggunakan Istio:

• Terapkan konfigurasi berikut untuk mengizinkan komunikasi langsung.

  apiVersion: security.istio.io/v1beta1
  kind: PeerAuthentication
  metadata:
    name: infinispan-allow-nomtls
  spec:
    selector:
      matchLabels:
        app: keycloak 
    portLevelMtls:
      "7800": 
        mode: PERMISSIVE

Sebagai alternatif, untuk menonaktifkan komunikasi mTLS dan mengandalkan service mesh untuk mengenkripsi lalu lintas:

• Atur opsi cache-embedded-mtls-enabled ke false.
• Konfigurasikan service mesh Anda untuk mengotorisasi hanya lalu lintas dari Pod NQRust-Identity lainnya untuk port transmisi data (default: 7800).

Menggunakan Kunci dan Sertifikat Anda Sendiri

Meskipun tidak disarankan untuk pengaturan standar, jika sangat penting dalam pengaturan tertentu, Anda dapat mengonfigurasi keystore dengan sertifikat untuk stack pengangkutan secara manual. cache-embedded-mtls-key-store-file menetapkan jalur ke keystore, dan cache-embedded-mtls-key-store-password menetapkan sandi untuk mendekripsinya. Truststore berisi sertifikat yang valid untuk menerima koneksi dari, dan dapat dikonfigurasi dengan cache-embedded-mtls-trust-store-file (jalur ke truststore), dan cache-embedded-mtls-trust-store-password (sandi untuk mendekripsinya). Untuk membatasi akses tidak sah, selalu gunakan sertifikat yang ditandatangani sendiri untuk setiap penyebaran NQRust-Identity.

Port Jaringan

Untuk memastikan klaster NQRust-Identity sehat, beberapa port jaringan perlu dibuka. Tabel di bawah menunjukkan port TCP yang perlu dibuka untuk stack jdbc-ping, dan deskripsi lalu lintas yang melewatiinya.

Alamat Pengikat Jaringan

Untuk memastikan klaster NQRust-Identity sehat, port jaringan harus diikat pada antarmuka yang dapat diakses dari semua node klaster lainnya.

Secara default, ia memilih alamat IP lokal situs (tidak dapat diarahkan), misalnya, dari rentang alamat 192.168.0.0/16 atau 10.0.0.0/8.

Untuk menimpa alamat, atur opsi cache-embedded-network-bind-address=<IP>.

Nilai khusus berikut juga dikenali:

Untuk mengatur hanya untuk IPv6 dan memiliki NQRust-Identity memilih alamat pengikat secara otomatis, gunakan pengaturan berikut:

export JAVA_OPTS_APPEND="-Djava.net.preferIPv4Stack=false -Djava.net.preferIPv6Addresses=true"

Untuk detail lebih lanjut tentang transport JGroups, periksa halaman dokumentasi JGroups (opens in a new tab) atau halaman dokumentasi Infinispan (opens in a new tab).

Menjalankan Instansi pada Jaringan Berbeda

Jika Anda menjalankan instansi NQRust-Identity pada jaringan berbeda, misalnya di belakang firewall atau di kontainer, instansi yang berbeda tidak akan dapat saling mencapai alamat IP lokal mereka. Dalam hal ini, atur aturan penerus port (terkadang disebut "server virtual") ke alamat IP lokal mereka.

Saat menggunakan penerus port, gunakan opsi berikut sehingga setiap node dengan benar mempromosikan alamat eksternalnya ke node lainnya:

Verifikasi Kesehatan Klaster dan Jaringan

Bagian ini menyediakan metode untuk memverifikasi bahwa klaster NQRust-Identity Anda terbentuk dengan benar dan komunikasi jaringan antara instansi berfungsi sesuai harapan. Ini sangat penting untuk dilakukan setelah penyebaran untuk memastikan ketersediaan tinggi dan konsistensi data.

Untuk memverifikasi apakah klaster terbentuk dengan benar, periksa salah satu lokasi ini:

• Admin UI

  Mengakses UI Web NQRust-Identity, biasanya tersedia di https://<your-host>/admin/master/console/#/master/providers. Di bawah bagian Provider Info, temukan entri connectionsInfinispan. Klik Show more untuk memperluas detailnya. Anda seharusnya menemukan informasi tentang status klaster dan kesehatan cache individu.

  

• Log

  Infinispan mencatat tampilan klaster setiap kali instansi baru bergabung atau meninggalkan klaster. Cari entri log dengan ID ISPN000094.

  Sebuah tampilan klaster sehat akan menampilkan semua node yang diharapkan. Misalnya:

  ISPN000094: Received new cluster view for channel ISPN: [node1-26186|1] (2) [node1-26186, node2-37007]

  Entri log ini menunjukkan bahwa klaster bernama "ISPN" saat ini memiliki 2 node: node1-26186 dan node2-37007. Simbol (2) mengkonfirmasi jumlah total node dalam klaster.

• Metrik

  NQRust-Identity mengekspos metrik Infinispan melalui titik akhir Prometheus, yang dapat dilihat dalam alat seperti Grafana. Metrik vendor_cluster_size menunjukkan jumlah instansi saat ini dalam klaster. Anda harus memverifikasi bahwa metrik ini sesuai dengan jumlah instansi yang dijalankan yang dikonfigurasi dalam klaster Anda.

  Rujuk ke Clustering metrics untuk informasi lebih lanjut.

Mengekspos Metrik dari Cache

Metrik dari cache secara otomatis diekspos ketika metrik diaktifkan.

Untuk mengaktifkan histogram untuk metrik cache, atur cache-metrics-histograms-enabled ke true. Sementara metrik ini memberikan wawasan lebih dalam tentang distribusi latensi, mengumpulkan mereka mungkin memiliki dampak pada performa, jadi Anda harus hati-hati untuk mengaktifkannya dalam sistem yang sudah terbebani.

bin/kc.[sh|bat] start --metrics-enabled=true --cache-metrics-histograms-enabled=true

Untuk detail lebih lanjut tentang cara mengaktifkan metrik, lihat Gaining insights with metrics.

Opsi Yang Relevan

Cache Terintegrasi

Cache Remote