Mengonfigurasi Keycloak v26 dengan Nginx Reverse Proxy di Docker: Menyelesaikan Masalah Konsol di Berbagai Bidang

Mengatasi Error Keycloak Console dengan Nginx dan Docker

Menyiapkan Keycloak dalam Container Docker dengan Nginx reverse proxy bisa menjadi konfigurasi yang ampuh untuk mengelola akses aman, namun hal ini bukannya tanpa tantangan. 🐳 Saat memigrasikan database Keycloak atau menangani beberapa ranah, kesalahan tak terduga sering kali muncul, sehingga menimbulkan kebingungan bagi administrator.

Skenario ini menjelaskan migrasi dari Keycloak v19.0.2 ke Keycloak v26, di mana pesan kesalahan "Tidak dapat menentukan" muncul di semua wilayah setelah login. Melacak masalah melalui log Nginx dan log kesalahan Keycloak menunjukkan permintaan HTTP yang gagal.

Dalam pengaturan serupa, proxy atau lapisan jaringan yang salah dikonfigurasi dapat memicu kesalahan “502 bad gateway”, biasanya karena masalah dalam cara Nginx atau Docker merutekan permintaan ke Keycloak. Masalah ini mungkin memerlukan penyesuaian dalam pengaturan proksi, variabel lingkungan, atau konfigurasi SSL untuk memastikan Keycloak berfungsi dengan lancar.

Dalam panduan ini, kami akan membahas solusi potensial untuk memecahkan masalah ini di Keycloak. Kami akan meninjau konfigurasi kunci, menganalisis log kesalahan, dan menjelajahi pengaturan spesifik yang dapat membantu menstabilkan Keycloak dalam pengaturan Docker-Nginx. Pada akhirnya, Anda akan mendapatkan wawasan untuk menyelesaikan masalah tersebut dan memastikan akses yang lancar dan tanpa gangguan ke konsol admin.

Rincian Detail Konfigurasi Keycloak dan Nginx

Skrip yang kami kembangkan untuk mengonfigurasi Keycloak di belakang proksi terbalik Nginx berperan penting dalam merutekan dan mengelola akses aman ke konsol admin Keycloak. File konfigurasi Nginx, misalnya, menentukan hulu blok yang menentukan alamat IP dan port backend Keycloak, memungkinkan Nginx mengarahkan permintaan secara akurat. Hal ini penting untuk skenario di mana layanan Keycloak beroperasi di segmen jaringan atau kontainer Docker yang berbeda. Dengan menggunakan arahan proxy seperti proxy_pass, kami memungkinkan Nginx bertindak sebagai perantara, menangani permintaan eksternal dan meneruskannya ke titik akhir layanan internal Keycloak. Penyiapan ini biasanya terlihat di lingkungan produksi yang memerlukan proxy terbalik untuk penyeimbangan beban dan akses yang aman.

Dalam konfigurasi Nginx, beberapa header disetel proxy_set_header perintah untuk memastikan Keycloak menerima semua informasi klien secara akurat. Misalnya, X-Real-IP Dan X-Diteruskan-Proto digunakan untuk meneruskan IP klien dan protokol permintaan asli. Informasi ini penting karena Keycloak menggunakannya untuk menghasilkan URL pengalihan yang akurat dan mengelola kebijakan keamanan. Masalah umum dalam pengaturan tersebut adalah hilangnya header, yang dapat menyebabkan kesalahan saat Keycloak mencoba mengautentikasi pengguna atau memvalidasi ranah. Dengan mendefinisikan header ini secara eksplisit, administrator memastikan bahwa Keycloak menerima konteks yang diperlukan untuk memproses permintaan dengan benar. Pendekatan ini meningkatkan keamanan dan konsistensi dalam cara pengelolaan permintaan.

File Docker Compose yang kami buat untuk Keycloak menyederhanakan penerapan dengan menggunakan env_file untuk semua variabel lingkungan. Hal ini memungkinkan kontainer Docker memuat konfigurasi seperti kredensial database, nama host Keycloak, dan jalur relatif, sehingga lebih aman dan mudah beradaptasi. Menggunakan file lingkungan juga praktis karena memisahkan informasi sensitif dari file Docker Compose, menghindari nilai hard-coded. Hasilnya, peralihan basis data atau modifikasi kredensial akses menjadi lancar, yang khususnya berguna dalam lingkungan dinamis di mana layanan sering diperbarui. Dalam contoh ini, variabel lingkungan KC_PROXY_HEADERS yang disetel ke "xforwarded" memastikan bahwa Keycloak memahami bahwa ia berada di balik proksi, sehingga melakukan penyesuaian dalam pembuatan URL dan pengelolaan sesi.

Selain konfigurasi, kami menyediakan a Pesta skrip yang berfungsi sebagai pemeriksaan kesehatan sederhana untuk memverifikasi ketersediaan Keycloak. Skrip menggunakan keriting untuk melakukan permintaan HTTP ke titik akhir Keycloak dan memeriksa apakah kode status sama dengan 200, yang menunjukkan layanan beroperasi. Jika terjadi kegagalan, skrip akan memulai ulang container Nginx, menawarkan bentuk pemulihan otomatis. Penyiapan ini ideal untuk lingkungan produksi di mana waktu aktif sangat penting, karena memungkinkan layanan melakukan pemulihan sendiri jika terjadi masalah koneksi. Menguji skrip seperti ini, bersama dengan pengujian unit berbasis Python untuk aksesibilitas titik akhir, memperkuat stabilitas sistem, memberikan ketenangan pikiran kepada administrator karena mengetahui bahwa pengaturan akan memberi tahu atau memperbaiki masalah secara proaktif. Pendekatan manajemen yang proaktif ini sangat penting dalam meminimalkan waktu henti dan memastikan akses tanpa batas ke Keycloak konsol admin.

upstream sso-mydomain-com {
    server 10.10.0.89:8080;
}
server {
    listen 443 ssl;
    server_name sso.mydomain.com;
    location / {
        proxy_pass http://sso-mydomain-com/;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
    }
    ssl_certificate /etc/nginx/ssl/sso.mydomain.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/sso.mydomain.com/privkey.pem;
}
server {
    listen 8443 ssl;
    server_name sso.mydomain.com;
    error_log /usr/local/nginx/logs/sso_err.log debug;
    location / {
        proxy_pass http://sso-mydomain-com/;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
    }
    ssl_certificate /etc/nginx/ssl/sso.mydomain.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/sso.mydomain.com/privkey.pem;
}

version: '3.9'
services:
  keycloak:
    container_name: keycloak
    image: quay.io/keycloak/keycloak:26.0
    env_file:
      - .env
    ports:
      - "8080:8080"
    volumes:
      - /opt/keycloak/themes:/opt/keycloak/themes
      - /etc/localtime:/etc/localtime
    privileged: true
    command: start

import requests
def test_whoami_endpoint():
    url = "https://sso.mydomain.com:8443/auth/admin/master/console/whoami?currentRealm=master"
    headers = {"Content-Type": "application/json"}
    try:
        response = requests.get(url, headers=headers, verify=True)
        assert response.status_code == 200, "Expected 200 OK, got {}".format(response.status_code)
        print("Test passed: whoami endpoint accessible")
    except requests.ConnectionError:
        print("Connection error: Check Nginx reverse proxy and Keycloak availability")
    except AssertionError as e:
        print("Assertion error:", e)
# Run the test
test_whoami_endpoint()

#!/bin/bash
# Check if Keycloak is reachable via the /whoami endpoint
URL="http://10.10.0.89:8080/auth/admin/master/console/whoami"
STATUS_CODE=$(curl -s -o /dev/null -w "%{http_code}" $URL)
if [ "$STATUS_CODE" -ne 200 ]; then
    echo "Keycloak endpoint unavailable, restarting Nginx..."
    docker restart nginx
else
    echo "Keycloak endpoint is healthy."
fi

Mengoptimalkan Keycloak untuk Operasi Proxy Terbalik yang Aman dan Mulus

Saat mengonfigurasi Keycloak di belakang proxy terbalik seperti Nginx, beberapa pertimbangan tambahan dapat membantu memastikan penyiapan aman, berperforma baik, dan stabil. Salah satu aspek penting adalah penghentian SSL—menangani HTTPS di lapisan Nginx. Karena Keycloak biasanya mendengarkan HTTP dalam Docker, Nginx dapat bertindak sebagai titik akhir SSL, membongkar enkripsi dan mengurangi beban sumber daya di Keycloak. Pengaturan ini memungkinkan Nginx berkomunikasi dengan Keycloak melalui HTTP sambil mempertahankan akses HTTPS yang aman bagi pengguna akhir. Selain itu, sertifikat SSL hanya disimpan di Nginx, sehingga menyederhanakan manajemen sertifikat. Alat otomatis seperti Let's Encrypt dapat menyederhanakan pembaruan, terutama dengan skrip yang memuat ulang Nginx saat pembaruan sertifikat.

Faktor penting lainnya adalah penyeimbangan beban dan penskalaan. Misalnya, dengan menggunakan konfigurasi jaringan Docker, administrator dapat membuat kumpulan server upstream di Nginx yang mencakup beberapa container Keycloak, sehingga meningkatkan distribusi dan ketersediaan beban. Itu proxy_pass arahan menunjuk ke kumpulan ini, memungkinkan Nginx merutekan permintaan di beberapa instance Keycloak. Pendekatan ini bermanfaat dalam lingkungan dengan lalu lintas tinggi, karena mencegah satu instance pun kewalahan. Selain itu, persistensi sesi, juga disebut sesi tempel, memastikan pengguna tetap terhubung ke instance yang sama, menghindari masalah autentikasi. Pemeriksaan kondisi dapat diotomatisasi menggunakan skrip Nginx atau Docker, memantau ketersediaan Keycloak, dan memulai ulang instance jika terjadi kegagalan. 🛠️

Terakhir, memanfaatkan metrik dan log bawaan Keycloak sangat penting untuk memelihara dan memecahkan masalah sistem. Keycloak dapat menghasilkan log terperinci untuk setiap permintaan, yang bila dipasangkan dengan log akses Nginx, akan membuat jejak audit lengkap. Alat pemantauan seperti Prometheus dan Grafana dapat memvisualisasikan metrik kinerja Keycloak, memperingatkan administrator tentang anomali sebelum hal tersebut berdampak pada pengguna. Di Nginx, pengaturan kesalahan_log ke debug level selama pengaturan menangkap informasi rinci untuk mendiagnosis masalah konfigurasi atau jaringan. Bersama-sama, strategi ini memastikan penerapan Keycloak yang lebih tangguh dan aman, menjadikannya solusi ideal untuk autentikasi tingkat perusahaan di balik proksi terbalik.