Tham số cấu hình SAML

Tài liệu chi tiết tất cả tham số cấu hình của plugin @digiforce-nc/plugin-auth-saml.

Tham số IdP

Tham số	Kiểu	Mặc định	Mô tả
ssoUrl	string	—	URL SSO endpoint của IdP — nơi gửi AuthnRequest. Ví dụ: https://dev-123456.okta.com/app/xxx/sso/saml
certificate	string	—	Certificate (PEM format) của IdP để verify chữ ký trên SAMLResponse/Assertion. Phải bao gồm header -----BEGIN CERTIFICATE----- và footer
idpIssuer	string	—	Entity ID của IdP. Giá trị này phải khớp chính xác với trường Issuer trong SAMLResponse từ IdP

Tham số chữ ký

Tham số	Kiểu	Mặc định	Mô tả
signResponse	boolean	true	Yêu cầu toàn bộ SAMLResponse phải được ký. Nếu true, plugin sẽ reject response không có chữ ký hợp lệ trên element Response
signAssertion	boolean	false	Yêu cầu Assertion bên trong Response phải được ký riêng. Một số IdP ký cả Response lẫn Assertion, một số chỉ ký Response
signatureAlgorithm	string	sha256	Thuật toán chữ ký: sha1, sha256, sha512. Phải khớp với thuật toán IdP sử dụng khi ký

Lưu ý về signResponse và signAssertion

Ít nhất một trong hai phải là true. Nếu cả hai đều false, plugin không thể verify tính toàn vẹn của response → không an toàn.

Cấu hình phổ biến:

• signResponse: true, signAssertion: false — IdP ký toàn bộ response (mặc định)
• signResponse: false, signAssertion: true — IdP chỉ ký assertion
• signResponse: true, signAssertion: true — IdP ký cả hai (an toàn nhất)

Tham số network và redirect

Tham số	Kiểu	Mặc định	Mô tả
http	boolean	false	Dùng HTTP thay HTTPS cho ACS URL. Chỉ bật khi phát triển local
autoRedirect	boolean	false	Tự động redirect đến IdP khi truy cập trang đăng nhập. Bỏ qua trang login Digiforce

Tham số user binding

Tham số	Kiểu	Mặc định	Mô tả
userBindField	string	email	Field dùng để liên kết SAML user với local user
public.autoSignup	boolean	true	Tự động tạo tài khoản nếu user chưa tồn tại

SP Entity ID

SP Entity ID không phải tham số cấu hình riêng — nó chính là tên authenticator được đặt khi tạo. Giá trị này cần khớp với Audience Restriction trong IdP configuration.

Ví dụ: nếu tên authenticator là okta-sso, thì SP Entity ID = okta-sso.

ACS URL (Assertion Consumer Service)

ACS URL được xây dựng tự động từ các tham số:

{protocol}://{host}{API_BASE_PATH}saml:redirect?authenticator={name}&__appName={app}

Trong đó:

• protocol: https (mặc định) hoặc http nếu bật tham số http
• host: domain của Digiforce
• API_BASE_PATH: mặc định /api/
• name: tên authenticator
• app: tên ứng dụng

URL này phải được đăng ký tại IdP là Reply URL hoặc ACS URL.

Ví dụ cấu hình với Okta

{
  "ssoUrl": "https://dev-123456.okta.com/app/abc123/sso/saml",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----",
  "idpIssuer": "http://www.okta.com/abc123",
  "signResponse": true,
  "signAssertion": false,
  "signatureAlgorithm": "sha256",
  "userBindField": "email",
  "autoRedirect": false,
  "public": {
    "autoSignup": true
  }
}

Ví dụ cấu hình với Azure AD

{
  "ssoUrl": "https://login.microsoftonline.com/{tenant-id}/saml2",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----",
  "idpIssuer": "https://sts.windows.net/{tenant-id}/",
  "signResponse": true,
  "signAssertion": true,
  "signatureAlgorithm": "sha256",
  "userBindField": "email",
  "public": {
    "autoSignup": true
  }
}