> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dbiz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lỗi thường gặp khi tích hợp đăng nhập Keycloak

> Cách nhận biết và xử lý các lỗi hay gặp khi tích hợp Keycloak: Invalid redirect uri, aud account, issuer lệch, CORS, issuer cũ trong cache Next.js, secret cũ.

Phần lớn lỗi tích hợp đăng nhập Keycloak đến từ vài cấu hình lệch nhỏ giữa app và client. Trang này liệt kê các lỗi đã gặp, dấu hiệu nhận biết và cách xử lý.

> [accordion] Đăng nhập báo Invalid parameter: redirect\_uri
>
> `redirect_uri` app gửi lên không khớp danh sách "Valid redirect URIs" của client. Hay gặp khi khác scheme (`http` và `https`), khác host, thiếu hoặc thừa đường dẫn, hoặc app desktop dùng `localhost` trong khi client khai `127.0.0.1`.
>
> **Cách xử lý:** xem `redirect_uri` thật trên thanh địa chỉ của trang lỗi, đối chiếu với cấu hình client. App desktop dùng `127.0.0.1`.

> [accordion] Đăng xuất báo Invalid redirect uri và không đăng xuất
>
> Keycloak từ chối mọi `post_logout_redirect_uri` không có trong post-logout redirect URIs của client; danh sách trống thì từ chối hết.
>
> **Cách xử lý:** yêu cầu khai post-logout URI cho client, gửi kèm `id_token_hint` khi đăng xuất. Kiểm nhanh bằng lệnh ở trang [Đăng xuất](https://docs.dbiz.com/sso/dang-xuat.md).

> [accordion] Đăng xuất rồi bấm đăng nhập lại vào thẳng tài khoản cũ
>
> App chỉ xoá phiên của mình, phiên Keycloak vẫn còn.
>
> **Cách xử lý:** cấu hình app chuyển tới end session của Keycloak khi đăng xuất. Xem [Đăng xuất](https://docs.dbiz.com/sso/dang-xuat.md).

> [accordion] API từ chối token vì aud là account
>
> Mặc định Keycloak không đưa client của bạn vào `aud` của access token, chỉ có `aud: account`. API kiểm `aud` sẽ từ chối.
>
> **Cách xử lý:** yêu cầu thêm audience mapper cho client phát token, trỏ tới tên API.

> [accordion] Token bị từ chối vì iss không khớp
>
> Backend gọi Keycloak qua địa chỉ nội bộ nhưng `iss` trong token vẫn là địa chỉ công khai. Hoặc issuer khai có `/` ở cuối.
>
> **Cách xử lý:** khai issuer đúng `https://<id-host>/realms/<realm>`, không có `/` cuối. Nếu thư viện bắt issuer trùng URL discovery, cấu hình tách "issuer" và "URL tải metadata".

> [accordion] Gọi Keycloak từ trình duyệt bị lỗi CORS
>
> Web origin khai có `/` cuối, ví dụ `https://app.example.com/`. Header `Origin` không bao giờ có `/` cuối nên không khớp request nào, và Keycloak không báo lỗi gì rõ ràng.
>
> **Cách xử lý:** khai web origin dạng `https://<app-host>`.

> [accordion] Next.js vẫn dùng issuer cũ sau khi đổi cấu hình
>
> Biến `NEXT_PUBLIC_*` được thay thẳng vào file JS. Next.js phục vụ `/_next/static/chunks/*` với cache `immutable` một năm. Nếu chỉ đổi biến môi trường mà tên chunk không đổi, trình duyệt tiếp tục dùng chunk cũ.
>
> **Cách xử lý:** build lại để tên chunk đổi. Khi kiểm, mở DevTools, tab Network, xem chunk tải về đang chứa issuer nào.

> [accordion] invalid\_client sau khi xoay client secret
>
> App đọc secret từ biến môi trường lúc khởi động nên vẫn giữ secret cũ.
>
> **Cách xử lý:** khởi động lại app sau khi secret đổi, hoặc cấu hình để app tự khởi động lại khi secret đổi.

> [accordion] oauth2-proxy không khởi động được
>
> oauth2-proxy đọc discovery ngay lúc khởi động. Keycloak chưa sẵn sàng, DNS chưa trỏ đúng, hoặc issuer trả về khác URL đã khai thì proxy thoát, và app phía sau ngừng phục vụ.
>
> **Cách xử lý:** khai issuer chính xác. Khi đổi host Keycloak, cập nhật cả `--oidc-issuer-url`, `--whitelist-domain` và `--backend-logout-url`.

> [accordion] Refresh token báo invalid\_grant
>
> Phiên đã hết hạn (quá thời gian rảnh hoặc thời gian tối đa của phiên), hoặc người dùng đã đăng xuất.
>
> **Cách xử lý:** xoá token đã lưu và cho người dùng đăng nhập lại.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.