Giao diện

FAQ & Troubleshooting — SAML ​

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

Certificate sai format ​

Triệu chứng: Validation luôn thất bại dù đã cấu hình certificate.

Nguyên nhân: Certificate phải ở dạng PEM đầy đủ, bao gồm header và footer.

Format đúng:

-----BEGIN CERTIFICATE-----
MIICmTCCAYECBgF7s8...
...nhiều dòng base64...
-----END CERTIFICATE-----

Lỗi thường gặp:

  • Thiếu -----BEGIN CERTIFICATE----- và -----END CERTIFICATE-----
  • Copy certificate từ IdP metadata nhưng thiếu dòng cuối
  • Certificate chứa khoảng trắng hoặc ký tự xuống dòng sai

Giải pháp:

  • Tải certificate trực tiếp từ IdP metadata XML (element <X509Certificate>)
  • Hoặc tải file .cer / .pem từ IdP settings
  • Thêm header/footer nếu chỉ có phần base64

Signature validation thất bại ​

Triệu chứng: Lỗi "Invalid signature on SAML response" hoặc tương tự.

Nguyên nhân và giải pháp:

  1. Certificate không khớp — IdP đã rotate certificate nhưng chưa cập nhật trong Digiforce → tải lại certificate mới
  2. signResponse / signAssertion sai — IdP chỉ ký assertion nhưng plugin yêu cầu ký response (hoặc ngược lại):
    • Kiểm tra SAMLResponse XML: nếu <Signature> nằm trong <Assertion> → bật signAssertion: true
    • Nếu <Signature> nằm trong <Response> → bật signResponse: true
  3. Thuật toán không khớp — IdP ký bằng sha256 nhưng plugin cấu hình sha1 → đổi signatureAlgorithm cho khớp

Cách debug: Decode SAMLResponse (base64) và kiểm tra XML:

bash
echo "SAMLResponse_base64" | base64 -d | xmllint --format -

Assertion không được ký (chỉ Response được ký) ​

Nếu IdP chỉ ký trên element <Response> mà không ký riêng <Assertion>:

json
{
  "signResponse": true,
  "signAssertion": false
}

Ngược lại, nếu IdP chỉ ký <Assertion>:

json
{
  "signResponse": false,
  "signAssertion": true
}

WARNING

Không nên đặt cả hai thành false — điều này vô hiệu hóa kiểm tra chữ ký, mở cửa cho tấn công giả mạo SAMLResponse.

ACS URL không khớp ​

Triệu chứng: IdP báo lỗi "Invalid ACS URL" hoặc "Reply URL mismatch".

Nguyên nhân: ACS URL đăng ký tại IdP phải khớp chính xác với URL Digiforce tạo ra.

Kiểm tra:

  • Protocol: https vs http (tham số http)
  • Domain: phải khớp host thực tế
  • Path: /api/saml:redirect (theo API_BASE_PATH)
  • Query params: ?authenticator={name}&__appName={app}

SP Entity ID không khớp ​

Triệu chứng: Lỗi "Audience validation failed".

Nguyên nhân: Audience Restriction trong SAMLResponse chứa SP Entity ID khác với tên authenticator.

Giải pháp: Đảm bảo giá trị Audience (hoặc SP Entity ID) cấu hình tại IdP = tên authenticator trong Digiforce.

Clock skew — Assertion hết hạn ​

Triệu chứng: Lỗi "SAML assertion expired" dù vừa đăng nhập.

Nguyên nhân: Đồng hồ trên server Digiforce và IdP lệch nhau quá nhiều.

Giải pháp:

  • Đồng bộ thời gian trên cả hai server bằng NTP
  • Kiểm tra NotBefore và NotOnOrAfter trong assertion — mặc định chỉ cho phép lệch vài phút