Khắc phục lỗi HTTPS và proxy của Keycloak trong chế độ production

Việc triển khai Keycloak ở chế độ production thường gây ra những lỗi khó hiểu như trang quản trị trống hoặc yêu cầu HTTPS nghiêm ngặt. Một bài phân tích kỹ thuật chuyên sâu gần đây, được công bố vào ngày 5 tháng 11 năm 2026, đã trình bày cách khắc phục các vấn đề này bằng Docker Compose, Nginx và các biến môi trường cụ thể. Hướng dẫn chỉ ra rằng việc chuyển tiếp header chính xác và cấu hình hostname là yếu tố then chốt để đảm bảo hệ thống quản lý danh tính hoạt động ổn định.

Chuyện gì đã xảy ra

Bài viết mô tả một môi trường phòng thí nghiệm có thể tái hiện lại, sử dụng Keycloak phiên bản 26.8.1, Nginx 1.31.8 và Postgres 18.6. Tác giả đã gặp phải nhiều lỗi tiêu chuẩn khi chuyển từ môi trường phát triển sang môi trường production. Các lỗi này bao gồm thông báo "HTTPS required" trên trang đăng nhập, giao diện quản trị bị trống do chặn nội dung hỗn hợp (mixed content), và thông báo "Invalid parameter: redirect_uri" trong quá trình xác thực. Mỗi lỗi đều bắt nguồn từ cách Keycloak diễn giải địa chỉ mạng và ngữ cảnh bảo mật của chính nó.

Nguyên nhân gốc rễ của các lỗi này thường là sự không khớp giữa URL mà trình duyệt nhìn thấy và URL mà Keycloak cho rằng nó đang phục vụ. Khi một reverse proxy kết thúc các kết nối TLS, Keycloak vẫn có thể tạo ra các liên kết HTTP nếu không được chỉ định rõ ràng điều ngược lại. Điều này dẫn đến việc trình duyệt chặn các tài nguyên không an toàn hoặc từ chối token vì claim về issuer (bên phát hành) không khớp với tên miền bảo mật mong đợi. Hướng dẫn cung cấp các bước cấu hình chính xác để đồng bộ hóa proxy, container và logic ứng dụng.

Chi tiết quan trọng

• Lỗi "HTTPS required" xảy ra khi Keycloak phát hiện một yêu cầu từ địa chỉ IP công cộng qua HTTP thuần túy, vốn bị chặn theo mặc định trong các realm production.
• Việc thiết lập KC_PROXY_HEADERS=xforwarded cho phép Keycloak tin tưởng các header được gửi bởi reverse proxy, chẳng hạn như X-Forwarded-Proto và X-Forwarded-Host.
• Biến KC_HOSTNAME phải được đặt thành URL công cộng đầy đủ, bao gồm cả scheme https, để đảm bảo token mang claim issuer chính xác.
• Sử dụng KC_HOSTNAME_BACKCHANNEL_DYNAMIC=true cho phép các dịch vụ nội bộ giao tiếp với Keycloak qua HTTP trong khi vẫn giữ cho token công cộng hợp lệ với HTTPS.
• Redirect URIs trong các ứng dụng khách phải khớp chính xác với các URI hợp lệ đã cấu hình, bao gồm scheme, host và cổng, để tránh các lỗi xác thực.
• Chế độ production yêu cầu KC_HTTP_ENABLED=true khi TLS được kết thúc tại edge, cho phép Keycloak lắng nghe trên cổng 8080 trong mạng Docker riêng tư.

Bối cảnh

Keycloak là một giải pháp mã nguồn mở cho quản lý danh tính và truy cập, phụ thuộc rất nhiều vào việc tạo URL chính xác cho các token bảo mật và chuyển hướng. Trong một thiết lập tự lưu trữ (self-hosted) điển hình, một reverse proxy như Nginx nằm phía trước container Keycloak để xử lý mã hóa SSL/TLS. Kiến trúc này có nghĩa là bản thân Keycloak thường chạy qua HTTP không mã hóa bên trong mạng container, trong khi thế giới bên ngoài chỉ thấy HTTPS. Nếu không cấu hình đúng, Keycloak không thể phân biệt giữa một yêu cầu trực tiếp không an toàn và một yêu cầu bảo mật được chuyển tiếp bởi proxy đáng tin cậy.

Giao thức OpenID Connect mà Keycloak sử dụng bao gồm trường "issuer" trong mọi token, cho biết ứng dụng nơi token xuất phát. Nếu URL issuer này sử dụng HTTP thay vì HTTPS, hoặc nếu nó trỏ đến hostname nội bộ của Docker thay vì tên miền công cộng, các ứng dụng khách sẽ từ chối token vì không hợp lệ. Tính năng bảo mật này ngăn chặn việc đánh cắp token nhưng đòi hỏi sự đồng bộ chính xác giữa cấu hình proxy và cài đặt nội bộ của Keycloak.

Tại sao điều này quan trọng

Đối với các đội ngũ vận hành phần mềm riêng, nhà cung cấp danh tính là cơ sở hạ tầng then chốt. Một instance Keycloak cấu hình sai có thể khóa quyền truy cập của quản trị viên và làm hỏng quy trình đăng nhập người dùng trên tất cả các ứng dụng kết nối. Lỗi "HTTPS required" đặc biệt dễ gây nhầm lẫn vì nó thường hoạt động tốt cục bộ trên laptop nhưng thất bại trên máy chủ ảo (VPS). Hiểu rằng Keycloak xử lý địa chỉ IP công cộng khác với địa chỉ IP riêng giúp các kỹ sư chẩn đoán lý do tại sao một thiết lập hoạt động trong môi trường phát triển lại bị hỏng trong production.

Hơn nữa, rủi ro bảo mật nảy sinh khi quản trị viên đi tắt, chẳng hạn như vô hiệu hóa hoàn toàn yêu cầu SSL. Mặc dù điều này có thể làm cho trang đăng nhập tải được, nhưng nó phơi bày mật khẩu và token trước nguy cơ bị đánh chặn. Cấu hình đúng reverse proxy để chuyển tiếp header đảm bảo rằng Keycloak duy trì ngữ cảnh bảo mật mà không cần trực tiếp xử lý chứng chỉ. Cách tiếp cận này giữ cho mạng nội bộ đơn giản trong khi vẫn duy trì bảo mật đầu-cuối cho người dùng.

Một tác động thực tế khác là sự ổn định của bảng điều khiển quản trị. Các lỗi nội dung hỗn hợp, khi một trang bảo mật cố gắng tải các script không bảo mật, khiến giao diện trở nên không thể sử dụng. Bằng cách đảm bảo Keycloak tạo ra các URL HTTPS cho tất cả tài nguyên, các đội ngũ tránh được các khối ở cấp độ trình duyệt. Sự nhất quán này cũng đơn giản hóa việc gỡ lỗi cho các nhà phát triển tích hợp ứng dụng của họ, vì các redirect URI và token issuer vẫn dự đoán được và chính xác.

Bạn có thể làm gì

• Cấu hình reverse proxy của bạn để gửi các header X-Forwarded-Proto, X-Forwarded-Host và X-Forwarded-Port tới container Keycloak.
• Đặt biến môi trường KC_PROXY_HEADERS thành xforwarded trong tệp Docker Compose của bạn để kích hoạt việc xử lý header.
• Xác định KC_HOSTNAME với URL HTTPS công cộng đầy đủ của bạn để sửa lỗi không khớp issuer token và đảm bảo tạo URL nhất quán.
• Kích hoạt KC_HTTP_ENABLED để cho phép Keycloak chấp nhận lưu lượng HTTP từ proxy trong khi vẫn giữ an toàn cho truy cập bên ngoài qua TLS.
• Kiểm tra xem redirect URIs của ứng dụng có khớp chính xác với các mẫu được phép trong Keycloak hay không, kiểm tra sự khác biệt giữa http và https.
• Sử dụng KC_HOSTNAME_BACKCHANNEL_DYNAMIC nếu các dịch vụ nội bộ cần truy cập Keycloak qua HTTP trong khi token công cộng vẫn hợp lệ với HTTPS.