Hướng dẫn cài đặt SAML

Hướng dẫn thiết lập xác thực SAML 2.0 trong Digiforce, bao gồm cấu hình trên các IdP phổ biến và đăng ký ACS URL.

Điều kiện tiên quyết

• Digiforce đã cài đặt và chạy ổn định
• Plugin @digiforce-nc/plugin-auth-saml đã được kích hoạt
• Tài khoản admin trên Identity Provider (Okta, OneLogin, Azure AD, ADFS...)

Các khái niệm cần biết

Thuật ngữ	Ý nghĩa
SP (Service Provider)	Digiforce — ứng dụng user muốn truy cập
IdP (Identity Provider)	Okta, Azure AD... — nơi user đăng nhập
SP Entity ID	Định danh SP = tên authenticator trong Digiforce
ACS URL	Callback URL nhận SAMLResponse từ IdP

Bước 1: Tạo authenticator trong Digiforce

1. Vào Settings → Authentication → Add new
2. Chọn loại SAML
3. Đặt tên authenticator (ví dụ: okta-sso, azure-saml)
4. Lưu lại — tên này chính là SP Entity ID

ACS URL có dạng:

https://your-domain.com/api/saml:redirect?authenticator={name}&__appName={app}

Ví dụ: https://app.example.com/api/saml:redirect?authenticator=okta-sso&__appName=main

Bước 2: Cấu hình Identity Provider

Okta

1. Truy cập Okta Admin → Applications → Create App Integration
2. Chọn SAML 2.0
3. Điền:
   • Single sign-on URL (ACS): https://your-domain.com/api/saml:redirect?authenticator=okta-sso&__appName=main
   • Audience URI (SP Entity ID): okta-sso (tên authenticator)
4. Cấu hình Attribute Statements: email → user.email, name → user.displayName
5. Hoàn tất → sao chép IdP SSO URL và Certificate

OneLogin

1. Vào Applications → Add App → SAML Custom Connector (Advanced)
2. Trong tab Configuration:
   • ACS URL: https://your-domain.com/api/saml:redirect?authenticator=onelogin-sso&__appName=main
   • Audience: onelogin-sso
3. Tab SSO → sao chép SAML 2.0 Endpoint (HTTP) và X.509 Certificate

Azure AD (Entra ID)

1. Vào Azure Portal → Enterprise applications → New application → Create your own
2. Chọn Integrate any other application you don't find in the gallery (Non-gallery)
3. Vào Single sign-on → SAML:
   • Identifier (Entity ID): tên authenticator (ví dụ: azure-saml)
   • Reply URL (ACS): https://your-domain.com/api/saml:redirect?authenticator=azure-saml&__appName=main
4. Tải Certificate (Base64) và sao chép Login URL

Bước 3: Điền thông số vào Digiforce

Quay lại Settings → Authentication → chọn authenticator:

Trường	Giá trị
SSO URL	IdP SSO URL (Login URL)
Certificate	Certificate PEM từ IdP (bao gồm -----BEGIN CERTIFICATE----- và -----END CERTIFICATE-----)
IdP Issuer	Entity ID của IdP (thường có trong metadata)
Sign Response	true (mặc định — yêu cầu toàn bộ Response được ký)
Signature Algorithm	sha256 (khuyến nghị)

Bước 4: Kiểm tra đăng nhập

1. Mở cửa sổ ẩn danh
2. Tại trang đăng nhập, nhấn nút Đăng nhập bằng SAML
3. Hệ thống redirect đến IdP → đăng nhập → POST SAMLResponse về ACS URL
4. Xác minh user được tạo/liên kết thành công

Bước 5: Tùy chỉnh nâng cao

• Auto-redirect: bật autoRedirect để bỏ qua trang login Digiforce
• Sign Assertion: bật signAssertion nếu IdP ký riêng assertion (ngoài response)
• HTTP: bật nếu chạy local không có SSL

Xem chi tiết tại Tham số cấu hình.