Giao diện

FAQ & Troubleshooting — OIDC ​

Các câu hỏi thường gặp và cách xử lý sự cố khi sử dụng plugin OIDC.

Lỗi "State mismatch" khi callback ​

Triệu chứng: Sau khi đăng nhập tại IdP, quay về Digiforce nhận lỗi 401 state mismatch.

Nguyên nhân phổ biến:

  1. Cookie hết hạn hoặc bị xóa — cookie digiforce_oidc chứa state CSRF đã bị trình duyệt xóa trước khi callback
  2. Redirect URI không khớp — IdP trả về domain khác với domain đã set cookie
  3. Mở nhiều tab — mỗi tab tạo state mới, ghi đè cookie của tab trước
  4. Reverse proxy — proxy không forward cookie đúng cách

Giải pháp:

  • Kiểm tra Redirect URI tại IdP khớp chính xác với domain Digiforce
  • Không mở nhiều tab đăng nhập cùng lúc
  • Kiểm tra cấu hình reverse proxy: đảm bảo forward header Cookie và Set-Cookie

Tắt autoSignup — chỉ cho phép user đã có tài khoản ​

Đặt public.autoSignup = false. Khi đó:

  • User đăng nhập qua OIDC nhưng chưa có tài khoản trong Digiforce sẽ nhận lỗi
  • Admin phải tạo user trước với email/username khớp với giá trị từ IdP
  • Giá trị so sánh dựa trên userBindField (mặc định email)

Liên kết user không phân biệt hoa/thường (case-insensitive email) ​

Plugin so sánh email có phân biệt hoa/thường theo mặc định. Nếu IdP trả email dạng User@Example.com nhưng local user lưu user@example.com, việc liên kết sẽ thất bại.

Giải pháp:

  • Đảm bảo email trong Digiforce và IdP sử dụng cùng quy tắc viết hoa/thường
  • Hoặc chuẩn hóa email về lowercase trước khi lưu vào Digiforce

Quản lý state với nhiều ứng dụng (multi-app) ​

Khi chạy kiến trúc multi-app:

  • State chứa trường app để xác định ứng dụng đích
  • Gateway middleware giải mã state và forward request đến đúng app
  • Mỗi app có thể có authenticator OIDC riêng hoặc dùng chung
  • Đảm bảo Redirect URI đăng ký tại IdP là URL chung của gateway

Lỗi SSL certificate (UNABLE_TO_VERIFY_LEAF_SIGNATURE) ​

Triệu chứng: Plugin không kết nối được IdP, log báo lỗi SSL.

Nguyên nhân: IdP sử dụng certificate tự ký hoặc CA không nằm trong trust store.

Giải pháp tạm thời (chỉ dùng khi phát triển):

  • Bật skipSSLVerification = true

Giải pháp đúng (production):

  • Thêm CA certificate vào trust store của Node.js qua biến NODE_EXTRA_CA_CERTS
  • Hoặc cấu hình IdP sử dụng certificate từ CA được tin cậy

Lỗi "invalid_client" khi exchange token ​

Nguyên nhân: Client ID hoặc Client Secret không đúng, hoặc đã hết hạn.

Giải pháp:

  • Kiểm tra lại Client ID và Client Secret tại IdP
  • Đảm bảo không có khoảng trắng thừa khi copy-paste
  • Một số IdP (Azure AD) cho phép tạo nhiều secret — đảm bảo dùng đúng secret còn hiệu lực

Lỗi "Discovery failed" khi khởi động ​

Nguyên nhân: Plugin không truy cập được {issuer}/.well-known/openid-configuration.

Giải pháp:

  • Kiểm tra URL issuer có đúng không (không có dấu / thừa ở cuối)
  • Kiểm tra kết nối mạng từ server Digiforce đến IdP
  • Thử truy cập URL discovery bằng curl từ server