SSO và SCIM
Thứ tự thiết lập đăng nhập bằng tài khoản công ty (IdP) và đồng bộ người dùng tự động.
Khi kết nối IdP của công ty (Okta, Microsoft Entra ID, Google Workspace, v.v.) với Keural, nhân viên đăng nhập bằng tài khoản công ty và tự động tham gia tổ chức ở lần đăng nhập đầu tiên.
Đặc tả dành cho người phụ trách IdP và nhà phát triển, xem Đặc tả SSO·SCIM.
Chuẩn bị
| Mục | Lý do |
|---|---|
| Tài khoản chủ sở hữu tổ chức trên Keural | Chỉ chủ sở hữu mới thay đổi được cài đặt SSO. |
| Quyền quản trị trên IdP | Tạo một ứng dụng Keural trên IdP. |
| Quyền quản lý DNS của tên miền công ty | Xác minh quyền sở hữu tên miền bằng bản ghi TXT. |
Phương thức được hỗ trợ
| Phương thức | Công dụng |
|---|---|
| OpenID Connect (OIDC) | Đăng nhập bằng tài khoản công ty |
| SAML 2.0 | Đăng nhập bằng tài khoản công ty. Yêu cầu xác thực dùng Redirect, phản hồi nhận qua HTTP-POST. |
| SCIM 2.0 | Phản ánh tự động việc thêm và vô hiệu hóa người dùng từ IdP vào tài khoản Keural |
Hãy chọn OIDC hoặc SAML. Nếu IdP hỗ trợ cả hai, nên chọn OIDC vì cấu hình đơn giản hơn.
Thứ tự thiết lập
- Xác minh tên miền công ty
- Tạo ứng dụng trên IdP
- Nhập giá trị vào Keural và lưu
- Bật SSO và thử đăng nhập
- Kết nối SCIM (tùy chọn)
Mọi thiết lập thực hiện trong Quản lý tổ chức → Cài đặt SSO.
1. Xác minh tên miền công ty
Trước hết, bạn phải chứng minh quyền sở hữu tên miền email sẽ dùng cho SSO. Tên miền chưa xác minh không thể lưu ở bước 3.
Nhập tên miền công ty (ví dụ acme.com) vào Tên miền tổ chức, rồi nhấn Thêm tên miền.
Ở dòng của tên miền đó trong danh sách, nhấn Xác minh. Cửa sổ Xác minh tên miền hiển thị Giá trị bản ghi TXT (keural-verify=…). Hãy sao chép giá trị này.
Trong trang quản lý DNS, thêm một bản ghi TXT cho tên miền đó và dán giá trị đã sao chép. Host (tên) là chính tên miền đó (thường là @).
Quay lại Keural và nhấn Xác nhận xác minh. Khi dòng hiển thị Đã xác minh là xong. Thay đổi DNS có thể mất vài chục phút mới có hiệu lực. Nếu thất bại, hãy đợi một lát rồi nhấn lại.
Nếu công ty có nhiều tên miền, hãy thêm và xác minh từng tên miền. Không thể dùng tên miền email công cộng như gmail.com.
2. Tạo ứng dụng trên IdP
Ở đầu Cài đặt SSO, chọn OpenID Connect (OIDC) hoặc SAML 2.0 trong Giao thức. Màn hình sẽ hiển thị các giá trị Keural cần đăng ký trên IdP. Nhập các giá trị này vào ứng dụng IdP, rồi sao chép các giá trị IdP cấp và lưu lại.
| Chiều | Mục | Chi tiết |
|---|---|---|
| Keural → IdP | URI callback | Dán nguyên văn vào URI chuyển hướng của ứng dụng IdP. |
| IdP → Keural | Issuer URL | Địa chỉ phát hành (issuer) của IdP. |
| IdP → Keural | Client ID · Client Secret | Giá trị nhận được khi tạo ứng dụng IdP. |
Đăng nhập chỉ hoàn tất khi IdP gửi email của người dùng.
| IdP | Nơi tạo | Ô nhập URI callback | Issuer URL |
|---|---|---|---|
| Okta | Applications → Create App Integration → OIDC · Web Application | Sign-in redirect URIs | https://<tên miền Okta> |
| Microsoft Entra ID | App registrations → New registration | Redirect URI (Web) | https://login.microsoftonline.com/<ID tenant>/v2.0 |
| Google Workspace | Google Cloud Console → API và dịch vụ → Thông tin xác thực → OAuth client ID (ứng dụng web) | URI chuyển hướng được phép | https://accounts.google.com |
- Microsoft Entra ID: Client Secret là Value của một bí mật tạo trong Certificates & secrets. Trong Token configuration, thêm claim tùy chọn
emailvào ID token. - Okta: trong Assignments của ứng dụng, chỉ định người dùng hoặc nhóm sẽ dùng Keural.
3. Nhập giá trị vào Keural và lưu
- Nhập các giá trị IdP đã nhận ở bước 2.
- Trong Tên miền email, nhập các tên miền đã xác minh ở bước 1, cách nhau bằng dấu phẩy. Khi ai đó đăng nhập bằng email thuộc các tên miền này, họ được chuyển đến trang đăng nhập của công ty.
- Quyết định có bật Tự động tạo người dùng khi đăng nhập lần đầu (JIT) hay không. Nếu bật, nhân viên chưa có tài khoản Keural sẽ được tạo tài khoản khi đăng nhập SSO lần đầu. Nếu tắt, chỉ những người đã có tài khoản mới đăng nhập được.
- Nhấn Lưu.
Với OIDC, nếu IdP không cung cấp địa chỉ chuẩn (discovery), hãy nhập endpoint thủ công trong Hiển thị cài đặt nâng cao. Với hầu hết IdP, hãy để trống.
4. Bật SSO và thử đăng nhập
- Bật Kích hoạt SSO và nhấn Lưu.
- Nhấn Thử đăng nhập. Trang đăng nhập của công ty sẽ mở trong cửa sổ mới.
- Đăng nhập bằng tài khoản công ty rồi quay lại Keural. Nếu bạn quay về được Keural, kết nối đã hoàn tất.
Thử đăng nhập chỉ hoạt động khi SSO đang bật. Nếu có vấn đề, hãy tắt Kích hoạt SSO và lưu. Trong lúc đó, nhân viên thuộc tên miền này đăng nhập bằng liên kết qua email.
Nhân viên đăng nhập
- Nhập email công ty trên màn hình đăng nhập Keural để chuyển đến trang đăng nhập của công ty. Sau khi đăng nhập ở đó, bạn quay lại Keural.
- Trên ứng dụng máy tính, đăng nhập bằng liên kết gửi qua email thay vì trang của công ty.
- Nhân viên đăng nhập SSO lần đầu sẽ tham gia tổ chức với vai trò thành viên. Vai trò quản trị viên được gán trong Quản lý tổ chức.
Trong các trường hợp sau, đăng nhập vẫn thành công nhưng người đó không được tự động thêm vào tổ chức:
- Tất cả ghế tổ chức đã mua đều đã được sử dụng
- Tài khoản đã thuộc về một tổ chức khác
5. Kết nối SCIM (tùy chọn)
Khi kết nối SCIM, người dùng bạn thêm hoặc vô hiệu hóa trên IdP sẽ được phản ánh ngay vào tài khoản Keural. Hãy thiết lập sau khi đã hoàn tất kết nối SSO.
Trong Cấp phát SCIM, bật Kích hoạt cấp phát SCIM.
Nhấn Cấp token và sao chép token. Token chỉ hiển thị một lần tại thời điểm này.
Nhập URL cơ sở SCIM (URL tenant) và token vào cấu hình cấp phát của IdP. Phương thức xác thực là token Bearer.
| IdP | Nơi nhập |
|---|---|
| Okta | Application → Provisioning → SCIM connector base URL; Authentication Mode chọn HTTP Header |
| Microsoft Entra ID | Enterprise application → Provisioning → Automatic → Tenant URL · Secret Token |
Thao tác trên IdP được phản ánh trên Keural như sau.
| Trên IdP | Trên Keural |
|---|---|
| Gán người dùng | Tạo tài khoản và thêm vào tổ chức. Tên người dùng là email. |
| Vô hiệu hóa người dùng hoặc hủy gán | Tạm khóa tài khoản và chặn đăng nhập. Dữ liệu không bị xóa. |
| Kích hoạt lại | Bỏ tạm khóa. |
| Thêm vào hoặc gỡ khỏi nhóm Keural Admins | Nâng lên quản trị viên hoặc hạ xuống thành viên. Chủ sở hữu không thay đổi. |
Nếu mất token, nhấn Cấp lại token. Token cũ sẽ mất hiệu lực ngay, vì vậy hãy nhập token mới vào IdP.
Xử lý sự cố
| Triệu chứng | Cách xử lý |
|---|---|
| Tên miền email không được lưu | Đã hoàn tất xác minh tên miền ở bước 1 chưa, và tên miền có phải là tên miền email công cộng không. |
| Xác minh tên miền thất bại | Đã nhập đủ giá trị TXT từ keural-verify= chưa. Đợi DNS cập nhật rồi nhấn lại. |
| Nhấn Thử đăng nhập nhưng không mở trang đăng nhập công ty | Đã bật Kích hoạt SSO và lưu chưa. |
| Đăng nhập công ty xong lại quay về trang đăng nhập Keural | Với OIDC, kiểm tra URI callback, Issuer URL, Client Secret và claim email. Với SAML, kiểm tra EntityID của SP, URL ACS, chứng chỉ và thuộc tính email. |
| Đăng nhập bị từ chối vì chưa có tài khoản | Tự động tạo người dùng khi đăng nhập lần đầu (JIT) đang tắt. Hãy bật hoặc mời nhân viên đó trước. |
| Đăng nhập được nhưng không thấy không gian làm việc của tổ chức | Kiểm tra còn ghế trống không và tài khoản không thuộc tổ chức khác. |
| Mở ứng dụng từ cổng IdP bị lỗi (SAML) | Hãy bắt đầu từ trang đăng nhập Keural bằng email công ty. |
| Kiểm tra kết nối SCIM thất bại | Nhập lại Base URL và token. Nếu đã cấp lại token, hãy thay bằng token mới. |