SSO - Đăng nhập một lần

Tích hợp đăng nhập một lần (Single Sign-On) với OIDC, SAML 2.0, Google Workspace, Microsoft 365 hoặc LDAP/Active Directory. Hỗ trợ JIT provisioning (tự tạo tài khoản khi đăng nhập lần đầu) và bắt buộc SSO cho từng nhóm vai trò.

Quyền truy cập: Chỉ admin hoặc người được cấp quyền SSO_* (SSO_CONFIG_VIEW, SSO_CONFIG_MANAGE, SSO_AUDIT_VIEW). Điều hướng: Cài đặt > Đăng nhập SSO. Trang SSOSettings có 3 tab: SSO Providers / LDAP / Active Directory / Nhật ký SSO.

Thay đổi từ 8.12: Tab "Đăng nhập SSO" đã được tách thành mục riêng và chuyển từ tab đầu xuống tab cuối trong "Cài đặt". Thứ tự mới: Email → Bảo mật hai lớp → Tính năng → Tên miền → Kết nối API → Đăng nhập SSO.
Tab LUÔN HIỂN THỊ với admin ở mọi gói dịch vụ. Tenant gói non-Enterprise khi mở tab sẽ thấy banner "Tính năng này yêu cầu nâng cấp gói dịch vụ" kèm CTA mở modal nâng cấp gói. Trước phiên bản 8.12, tab này bị ẩn hoàn toàn với tenant không có quyền dùng SSO - admin không biết tính năng tồn tại để cân nhắc nâng cấp.

Tổng quan

Từ phiên bản 8.11, Noova hỗ trợ đầy đủ SSO chuẩn enterprise:

4 loại nhà cung cấp: OIDC (custom Enterprise IdP), SAML 2.0 (Azure AD legacy / ADFS / Okta), Google Workspace, Microsoft 365
2 chế độ provisioning: JIT (tự tạo user khi login lần đầu) hoặc PRE_PROVISIONED (yêu cầu HR tạo trước)
Bắt buộc SSO theo vai trò: có thể ép buộc 1 hoặc nhiều vai trò chỉ được đăng nhập qua SSO (không cho password)
Nhật ký audit đầy đủ: ghi nhận mọi sự kiện đăng nhập, thay đổi cấu hình, kiểm tra kết nối
Tự tạo hồ sơ Employee: tuỳ chọn - bật để tự tạo bản ghi Employee khi user mới đăng nhập qua SSO
SAML SP Metadata XML: mỗi provider SAML có URL /sso/metadata/<providerId>.xml để IdP admin cấu hình trust

Tab 1: SSO Providers

Chính sách chung

Khối đầu tiên trong tab "SSO Providers" cấu hình chính sách áp dụng toàn hệ thống:

Trường	Mô tả	Mặc định
Cho phép đăng nhập bằng email/mật khẩu	Bật/tắt toàn bộ password login. Tắt sẽ ép tất cả user qua SSO/LDAP	Bật
Cho phép đăng nhập bằng LDAP	Bật/tắt LDAP auth (cấu hình chi tiết ở tab LDAP)	Tắt
Chế độ provisioning mặc định	`JIT` (tự tạo user khi login) hoặc `PRE_PROVISIONED` (yêu cầu tạo trước)	JIT
Role mặc định cho user mới	Vai trò gán cho user JIT-provisioned. Chỉ cho các vai trò cơ bản: `employee`, `user`, `candidate`, `viewer`, `guest`. Không cho `admin`/`owner`	employee
Roles bắt buộc phải đăng nhập qua SSO	Danh sách vai trò chỉ được đăng nhập qua SSO. User trong các vai trò này KHÔNG được login bằng password	Trống

Nhấp CẬP NHẬT để lưu chính sách. Nút chỉ kích hoạt khi form đã thay đổi (isPolicyDirty).

Bảo mật: Khi đặt enforceSSOForRoles = ['admin'], mọi admin chỉ login được qua SSO. Đảm bảo có ít nhất 1 admin còn lại có thể login qua SSO trước khi enforce, nếu không sẽ tự khoá mình ra ngoài hệ thống.

Danh sách nhà cung cấp SSO

Bảng hiển thị:

Cột	Mô tả
Mã	`providerId` - định danh ngắn (vd: `azure-ad`, `okta-prod`)
Loại	OIDC / SAML / SOCIAL_GOOGLE / SOCIAL_MICROSOFT
Tên hiển thị	Tên đầy đủ
Trạng thái	Badge `Bật` / `Tắt`
Thứ tự	Số sắp xếp trên trang login
Hành động	Nút Sửa / Xoá

Nhấp THÊM PROVIDER mở modal form (xem dưới).

Thêm / Sửa SSO Provider

Form FormSSOProvider có các nhóm trường:

Thông tin cơ bản

Trường	Bắt buộc	Mô tả
Loại nhà cung cấp	Có	OIDC / SAML 2.0 / Google Workspace / Microsoft 365 (không sửa được khi đã tạo)
Mã định danh	Có	`providerId` - chỉ chữ thường + dấu gạch ngang, max 64 ký tự (vd: `azure-ad`, `okta-prod`). Không sửa được khi đã tạo
Tên hiển thị	Có	Tên đầy đủ hiển thị admin và bên ngoài
Nhãn nút đăng nhập	Có	Text trên nút login (vd: "Đăng nhập Azure AD")
Logo URL	Không	HTTPS hoặc `/img/...` - icon hiển thị bên cạnh nút
Thứ tự hiển thị	Không	Số sắp xếp các nút SSO trên trang login

Cấu hình OIDC (nếu loại = OIDC/Google/Microsoft)

Trường	Mô tả
Discovery URL	URL `.well-known/openid-configuration` của IdP
Client ID	(bắt buộc)
Client Secret	(bắt buộc) - lưu mã hoá
Scope	Mặc định `openid profile email`, có thể thêm scope khác
Fetch userinfo endpoint	Bật để gọi userinfo sau khi đổi token (lấy thêm claim)

Cấu hình SAML 2.0 (nếu loại = SAML)

Trường	Mô tả
IdP Entry Point URL	(bắt buộc) URL SSO của IdP
SP Entity ID (Issuer)	(bắt buộc) Mã định danh SP (Noova)
IdP Signing Certificate (PEM)	(bắt buộc) - chứng chỉ ký của IdP
SP Private Key	(tuỳ chọn) - cho signed AuthnRequest
Yêu cầu IdP ký assertion	Khuyến nghị BẬT

SAML SP Metadata: Sau khi tạo provider SAML, URL metadata công khai cho IdP admin: https://<customer-domain>/sso/metadata/<providerId>.xml. Gửi link này cho phía IdP để cấu hình trust.

Cấp tài khoản (Provisioning)

Trường	Mô tả
Chế độ provisioning	`Dùng chính sách chung` / `JIT` / `PRE_PROVISIONED`
Role mặc định cho user mới	Áp dụng cho JIT. Trống = dùng role từ chính sách chung. KHÔNG được chọn `admin`/`owner`/`super-admin`
Tự tạo hồ sơ nhân sự khi user đăng nhập lần đầu qua provider này	Idempotent - bỏ qua nếu user đã có hồ sơ Employee

Kích hoạt

Switch "Kích hoạt provider này" - chỉ provider enabled=true mới hiển thị trên trang login công khai.

Hành động

Nút	Mô tả
Tạo mới / Cập nhật	Lưu cấu hình
Hủy	Bỏ qua thay đổi
Kiểm tra kết nối (chỉ khi edit)	Test kết nối thực tế đến IdP - trả về SUCCESS/FAILURE kèm message

URL callback và metadata

Endpoint	Mục đích	Ai dùng
`GET /sso/callback/oidc/<providerId>?code=&state=`	Callback OIDC	IdP redirect sau khi user authenticate
`POST /sso/callback/saml/<providerId>`	Callback SAML (form `SAMLResponse` + `RelayState`)	IdP POST sau khi user authenticate
`GET /sso/metadata/<providerId>.xml`	SAML SP Metadata	IdP admin - copy URL này gửi cho phía IdP

Sau callback thành công:

Tạo Meteor login token, set vào localStorage qua HTML token-injection page
Trigger cross-app sync (manage / employee / classroom đều nhận auth)
Redirect về returnTo URL (mặc định: /)

Tab 2: LDAP / Active Directory

Tab này nhúng trang LDAP Settings hiện có. Xem chi tiết cấu hình tại LDAP / Active Directory.

Lưu ý: Để LDAP login hoạt động, phải bật cả 2 chỗ: (1) Tab "SSO Providers" → chính sách chung → Cho phép đăng nhập bằng LDAP; (2) Tab LDAP → Bật LDAP + Enable LDAP Authentication.

Tab 3: Nhật ký SSO

Trang PageSSOAuditLog hiển thị mọi sự kiện SSO được ghi lại để phục vụ audit bảo mật.

Bộ lọc

Lọc theo loại sự kiện: dropdown với 8 loại event
Mỗi trang: chọn số bản ghi hiển thị (default 50)

Bảng dữ liệu

Cột	Mô tả
Timestamp	Thời điểm UTC (hiển thị theo timezone tenant)
Sự kiện	LOGIN_INITIATE / LOGIN_SUCCESS / LOGIN_FAILED / PROVIDER_CONFIG_CREATED / PROVIDER_CONFIG_CHANGED / PROVIDER_CONFIG_DELETED / POLICY_CHANGED / CONNECTION_TEST
Kết quả	Badge `SUCCESS` (xanh) / `FAILURE` (đỏ)
Provider	providerId + loại
Email	Email user (nếu có)
Mã lỗi	Mã lỗi (nếu kết quả là FAILURE)
IP / User Agent	Truy vết nguồn yêu cầu

Subscription giới hạn 500 bản ghi gần nhất; pagination trên client.

Các sự kiện audit

Event	Khi nào ghi
`LOGIN_INITIATE`	User nhấn nút SSO, redirect đến IdP
`LOGIN_SUCCESS`	Callback xử lý thành công, token cấp
`LOGIN_FAILED`	Callback lỗi (signature sai, state hết hạn, JIT từ chối...)
`PROVIDER_CONFIG_CREATED`	Admin tạo provider mới
`PROVIDER_CONFIG_CHANGED`	Admin sửa provider
`PROVIDER_CONFIG_DELETED`	Admin xoá provider
`POLICY_CHANGED`	Admin cập nhật chính sách chung
`CONNECTION_TEST`	Admin nhấn "Kiểm tra kết nối"

Trên trang đăng nhập (UX user)

Khi có ≥1 provider SSO enabled=true, trang đăng nhập sẽ hiển thị:

Form email/mật khẩu thường (chỉ khi allowPasswordLogin=true và role không bị enforce SSO)
Dải nút SSO theo order tăng dần, mỗi nút có buttonLabel + logoUrl

Nhấp nút → redirect đến IdP → user authenticate → IdP redirect về Noova callback → token cấp → login.

Nếu user nằm trong enforceSSOForRoles: hiển thị thông báo "Tài khoản của bạn chỉ được đăng nhập qua [tên provider SSO]" và ẩn form password.

Khi user đăng nhập qua SSO mà chưa có tài khoản trên Noova và provisioningMode=JIT:

Lấy thông tin từ claim/assertion IdP: email, full name, username
Tìm user theo email + provider link
Nếu chưa tồn tại:
- Tạo Meteor.users với email + emailVerified=true
- Gán role mặc định (per-provider defaultRole hoặc fallback policyForm.defaultNewUserRole)
- Nếu provider có autoCreateEmployee=true: insert Employees với fullName, email
- Link provider: {providerId, externalSubjectId, linkedAt} vào Meteor.users.services.sso
Cấp Meteor login token + redirect về returnTo

Nếu provisioningMode=PRE_PROVISIONED và user chưa tồn tại: từ chối login với error code JIT_REQUIRES_PRE_PROVISIONING.

Bảo mật

State CSRF protection: mỗi initiate sinh state token ngắn hạn (15 phút), lưu trong SSOAuthState collection. Callback bắt buộc match state.
URL validation: discovery URL, entry point, returnTo phải pass url-validators.js (HTTPS, không localhost trừ DEV)
Excluded roles cho JIT: không bao giờ cho phép tự tạo user với role admin, owner, super-admin, SUPER_ADMIN, OWNER
Client Secret: lưu mã hoá ở rest, không trả về API (frontend chỉ thấy placeholder dấu sao)
Audit log: mọi sự kiện ghi với UTC timestamp + IP + UA + errorCode

Lưu ý

Từ 8.12, tab SSO Settings đứng riêng tại Cài đặt > Đăng nhập SSO (tab cuối). Lộ trình tương lai sẽ cho phép truy cập trực tiếp /manage/sso-settings.
Tab luôn hiển thị với admin - nếu gói dịch vụ chưa hỗ trợ SSO/LDAP, admin sẽ thấy banner "Tính năng này yêu cầu nâng cấp gói dịch vụ" + CTA mở upgrade modal thay vì bị ẩn tab như trước.
Module SSO + LDAP + Audit log được kiểm soát bằng feature toggle. Bật/tắt ở Cài đặt > Tính năng, tìm mục "Đăng nhập SSO (OIDC / SAML, Enterprise)" (mô tả: tích hợp Azure AD / Okta / ADFS / Google Workspace, yêu cầu gói Enterprise). Xem thêm Quản lý dịch vụ.
Tech detail (admin hệ thống): Feature flag nội bộ đã đổi tên eweb.allowSSO → eweb.allowCustomSSO. Field allowSSO cũ đã bị xoá khỏi eweb-schema.js - script kiểm tra cấu hình cũ cần cập nhật theo tên mới.
Đăng nhập bằng SSO cũng cấp Meteor login token chuẩn nên hoạt động xuyên app (manage / employee / classroom share session qua nginx).

Xem thêm

LDAP / Active Directory - Cấu hình chi tiết LDAP
Vai trò và phân quyền - Cấp quyền SSO_* cho admin con
Quản lý tài khoản - Trạng thái tài khoản (active, JIT-provisioned, locked)
Quản lý dịch vụ - Bật/tắt tính năng SSO theo gói

SSO - Đăng nhập một lần ​

Tổng quan ​

Tab 1: SSO Providers ​

Chính sách chung ​

Danh sách nhà cung cấp SSO ​

Thêm / Sửa SSO Provider ​

Thông tin cơ bản ​

Cấu hình OIDC (nếu loại = OIDC/Google/Microsoft) ​

Cấu hình SAML 2.0 (nếu loại = SAML) ​

Cấp tài khoản (Provisioning) ​

Kích hoạt ​

Hành động ​

URL callback và metadata ​

Tab 2: LDAP / Active Directory ​

Tab 3: Nhật ký SSO ​

Bộ lọc ​

Bảng dữ liệu ​

Các sự kiện audit ​

Trên trang đăng nhập (UX user) ​

JIT Provisioning (tự tạo user khi login lần đầu) ​

Bảo mật ​

Lưu ý ​

Xem thêm ​