Chi tiết luồng xác thực SAML

Mô tả luồng SP-initiated SSO, HTTP POST binding, validation assertion và xử lý RelayState.

Tổng quan luồng

Plugin triển khai SP-initiated SSO với HTTP POST binding: Digiforce (SP) tạo AuthnRequest → redirect user đến IdP → IdP POST SAMLResponse về ACS URL → plugin validate và trích xuất user.

Sequence diagram chi tiết

Chi tiết AuthnRequest

AuthnRequest XML được tạo bởi thư viện @node-saml/node-saml:

Field	Giá trị
Issuer	Tên authenticator (SP Entity ID)
AssertionConsumerServiceURL	ACS URL đầy đủ
NameIDPolicy	urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
Destination	IdP SSO URL

AuthnRequest được base64-encode và gửi qua query string SAMLRequest (HTTP-Redirect binding).

RelayState

RelayState mang thông tin redirect URL sau khi đăng nhập thành công:

1. Client gửi redirect parameter khi gọi saml:getAuthUrl
2. Server đặt giá trị này làm RelayState trong AuthnRequest
3. IdP trả lại RelayState nguyên vẹn trong POST SAMLResponse
4. Server đọc RelayState → redirect user về URL ban đầu

Validation chi tiết

Plugin gọi validatePostResponseAsync() từ @node-saml/node-saml để kiểm tra:

Kiểm tra	Mô tả
Chữ ký	Verify XML signature bằng certificate PEM. Tùy signResponse / signAssertion mà verify trên element nào
Thuật toán	Thuật toán ký phải khớp signatureAlgorithm (sha1/sha256/sha512)
Issuer	Issuer trong Response phải khớp idpIssuer
Audience	AudienceRestriction phải chứa SP Entity ID
Thời hạn	NotBefore ≤ thời điểm hiện tại ≤ NotOnOrAfter

Trích xuất profile

Sau khi validation thành công, plugin trích xuất thông tin user:

1. NameID: giá trị chính (thường là email)
2. Attributes: các claim bổ sung từ IdP (name, department, role...)
3. Áp dụng field mapping → tạo object local user
4. Tìm local user theo userBindField → liên kết hoặc tạo mới

Xử lý lỗi

Lỗi	Nguyên nhân	Giải pháp
Signature validation failed	Certificate không khớp	Tải lại certificate từ IdP
Issuer mismatch	idpIssuer cấu hình sai	Kiểm tra Entity ID trong IdP metadata
Audience mismatch	SP Entity ID khác tên authenticator	Đảm bảo Audience tại IdP = tên authenticator
Assertion expired	Clock skew giữa SP và IdP	Đồng bộ thời gian (NTP)