Tham chiếu cấu hình SSO

Mọi thứ có thể cấu hình về đăng nhập một lần, gói gọn trong một trang. Các giá trị nằm trong những dòng sso_connections của global.db (vốn ở phạm vi toàn máy chủ theo thiết kế), được chỉnh sửa qua Cài đặt → Máy chủ → Đăng nhập một lần hoặc các thao tác RPC sso.*. Dòng đã lưu là nguồn chân lý duy nhất — không có đường dẫn biến môi trường CC_SAML_* / CC_OIDC_* nào (một kết nối có thể đến từ hai nơi chính là kết nối mà màn hình cài đặt có thể phản đối).

Các trường của kết nối

Trường	Áp dụng cho	Mặc định	Ý nghĩa
enabled	cả hai	tắt	các lần đăng nhập có thể dùng kết nối này
idpMetadataXml	SAML	—	XML EntityDescriptor của IdP (bắt buộc để bật)
spEntityId	SAML	<origin>/saml	entity ID của chúng ta, được ghim khi origin thay đổi
emailAttribute	SAML	email	thuộc tính chứa email; NameID có dạng email là phương án dự phòng
displayNameAttribute	SAML	displayName	thuộc tính tên hiển thị
groupsAttribute	SAML	groups	thuộc tính tên nhóm
clockSkewSeconds	SAML	90	mức cho phép lệch đồng hồ khi xác thực thời hạn hiệu lực
allowIdpInitiated	SAML	tắt	chấp nhận các Response không được yêu cầu (không có InResponseTo)
wantResponseSigned	SAML	tắt	yêu cầu chữ ký ở gốc Response (chữ ký khẳng định luôn bắt buộc)
issuer	OIDC	—	URL gốc của issuer (bắt buộc để bật)
clientId	OIDC	—	id client công khai (bắt buộc để bật)
clientSecret	OIDC	—	chỉ dành cho client confidential; được lưu trong tệp secrets 0600, không bao giờ trong cơ sở dữ liệu — chỉ ghi qua RPC (sso.getConfig báo cáo clientSecretPresent)
groupsClaim	OIDC	groups	claim chứa tên nhóm
defaultRole	cả hai	member	vai trò khi không có nhóm nào được ánh xạ — không bao giờ là owner
groupRoleMap	cả hai	{}	nhóm → vai trò; các ánh xạ tới chủ sở hữu bị từ chối khi lưu
autoMember	cả hai	bật	tự động thêm người dùng vào mọi không gian làm việc ở lần đăng nhập đầu tiên
allowJit	cả hai	bật	cấp phát người dùng chưa biết khi đăng nhập

Cấu hình tiến trình

Các kết nối SSO không được nạp sẵn từ môi trường. Một cờ tiến trình còn lại nói về bước chuyển tiếp qua trình duyệt, chứ không phải dòng kết nối:

Biến / cờ	Ý nghĩa
--web-client-url / CC_SERVER_WEB_CLIENT_URL	origin mà các callback SSO chuyển hướng trình duyệt tới (thông tin xác thực đi kèm trong phần fragment của URL). Để trống thì bước chuyển tiếp vẫn cùng origin.

Bản thân URL issuer phải là https (http chỉ được chấp nhận cho các issuer loopback localhost, 127.0.0.1 và ::1).

Các endpoint HTTP

Endpoint	Xác thực	Mục đích
GET /saml/login?relay=…	không (chuyển hướng)	bắt đầu đăng nhập do SP khởi tạo; relay=desktop chuyển tiếp sang ứng dụng, relay=web-popup gửi postMessage tới thẻ kết nối đang chờ (thẻ này khai báo client_origin của nó, chỉ được tôn trọng khi danh sách origin tin cậy cho phép)
POST /saml/acs	không (IdP POST)	bộ tiếp nhận khẳng định — xác minh, cấp phát, tạo mới
GET /saml/metadata	không	EntityDescriptor SP của chúng ta
GET /oidc/login?relay=… / GET /oidc/callback	không	vòng khứ hồi OIDC; relay=desktop chuyển tiếp sang ứng dụng, relay=web-popup tới thẻ kết nối đang chờ (cùng quy ước client_origin)
GET /auth/providers	không, CORS *	phép dò của màn hình kết nối: các kết nối SSO được cung cấp (id/kind/label) + pairingEnabled
/scim/v2/Users…	Bearer (token SCIM)	Users: tạo/đọc/liệt kê+lọc/PUT/PATCH/DELETE
/scim/v2/Groups	Bearer	chỉ đọc; việc đẩy nhóm trả về 501 có chủ đích
/scim/v2/ServiceProviderConfig	Bearer	tài liệu mô tả năng lực

Các thao tác RPC

Mọi thao tác sso.* đều thuộc phạm vi máy chủ và chỉ dành cho chủ sở hữu máy chủ (người vận hành bản cài đặt, ServerAuthority.serverOwner). Sở hữu một không gian làm việc là chưa đủ; chỉ riêng việc ghép nối không bao giờ cấp được chúng.

Thao tác	Mục đích
sso.getConfig	kết nối đã lưu cho một loại
sso.saveConfig	xác thực, lưu trữ và áp dụng trực tiếp
sso.status	các cờ đã bật/đã cấu hình, sự hiện diện của token SCIM, origin chuẩn
sso.testConnection	kiểm thử một kết nối mà không cần vòng khứ hồi qua trình duyệt (SAML: phân tích metadata + dựng AuthnRequest; OIDC: khám phá issuer), có thể dùng các giá trị chưa lưu trên màn hình
sso.spMetadata	phát ra EntityDescriptor SP cho một origin
sso.setPairingEnabled	cho phép/cấm ghép nối thủ công (mã mời, khóa ghép nối); việc từ chối tắt nó khi chưa có kết nối SSO nào hoạt động giúp phòng ngừa tình trạng khóa tài khoản
sso.sessionPolicy	đọc tuổi thọ tối đa của thông tin xác thực thiết bị và thời gian chờ nhàn rỗi của bản cài đặt (phút; 0 = không đặt)
sso.setSessionPolicy	đặt các giới hạn đó; được thực thi ở bước kiểm tra thiết bị, không được công bố cho máy khách
sso.scimRegenerateToken	tạo và trả về bearer token SCIM (một lần)

Mã lỗi xác thực

Các lỗi của cc_saml_verify_response mang một mã ổn định:

Mã	Ý nghĩa
signature	chữ ký bị thiếu/không đáng tin/bị sửa đổi, hoặc thuật toán/phép biến đổi bị cấm
expired	nằm ngoài NotBefore/NotOnOrAfter (vượt quá độ lệch)
audience	hạn chế đối tượng không nêu tên chúng ta
destination	đích của response không phải ACS của chúng ta
request_match	InResponseTo không khớp với một yêu cầu đang chờ, hoặc không được yêu cầu trong khi bị cấm
issuer	issuer không phải IdP đã cấu hình
recipient	bên nhận xác nhận chủ thể không phải ACS của chúng ta
malformed	lỗi ở mức XML/schema
status	trạng thái do IdP báo cáo không phải Success
invalid / internal	mọi trường hợp khác / lỗi ở đường nối

Các bề mặt cơ sở dữ liệu

• sso_connections (global.db) — một dòng cho mỗi loại, XUYÊN KHÔNG GIAN LÀM VIỆC THEO THIẾT KẾ.
• users.sso_subject + users.sso_issuer — việc ghim chủ thể của nhà cung cấp, duy nhất theo (issuer, subject) nhờ một chỉ mục bộ phận.
• users.deactivated_at — dấu thời gian vô hiệu hóa của SCIM.
• Bearer token của SCIM và client secret của OIDC nằm trong tệp secrets 0600, không bao giờ trong cơ sở dữ liệu.