Cấp phát người dùng từ Microsoft Entra ID bằng SCIM
SCIM 2.0 cho phép Microsoft Entra ID tạo, cập nhật, khóa và gỡ người trong tổ chức Tara của bạn, và đặt role theo nhóm Entra. SCIM không đăng nhập thay ai: mọi người vẫn đăng nhập bằng SSO của tổ chức (OIDC), nên hãy cài SSO trước (các bước OIDC với Entra có ở Nhà cung cấp SAML qua OIDC).
SCIM chỉ có ở gói Enterprise. Ở Free và Team, owner không tạo được token SCIM; nếu tổ chức mất tính năng này, mọi lệnh SCIM nhận 403 kèm câu nêu rõ gói (IdP không hiểu mã 402 Payment Required nên Tara dùng 403 ở đây).
Bạn phải là owner của tổ chức. Chỉ owner tạo được token SCIM và ánh xạ nhóm sang role.
Trong Tara
- Mở Settings › SSO, tìm mục SCIM provisioning. Tạo một token và đặt tên. Sao chép token (bắt đầu bằng
tara_scim_); token chỉ hiện một lần. - Sao chép base URL:
https://<máy chủ Tara>/scim/v2/orgs/<slug tổ chức>. - Nên làm: ánh xạ tên nhóm Entra sang role (xem Nhóm và role).
Trên terminal:
ph org scim-token create entra --out scim-token.txt
ph org scim-roles set '{"Engineering":"member","Platform":"admin","Stakeholders":"viewer"}'Token có hạn 365 ngày theo mặc định (tối đa 730), chỉ thuộc tổ chức này và chỉ gọi được /scim/v2/orgs/<slug tổ chức>/…. Mỗi tổ chức có tối đa 10 token còn hiệu lực, nên khi xoay vòng bạn tạo token thứ hai trước rồi mới thu hồi token cũ.
Trong Microsoft Entra ID
Tên các mục dưới đây là tên Entra admin center thường hiện; giữa các phiên bản có thể lệch đôi chút.
Trong Microsoft Entra admin center, mở Enterprise applications và tạo một ứng dụng riêng (non-gallery). Bạn dùng lại enterprise application đã tạo cho SSO cũng được; tạo ứng dụng riêng cho provisioning cũng được.
Mở Provisioning của ứng dụng và đặt Provisioning Mode là Automatic.
Ở Admin Credentials, nhập Tenant URL: base URL từ Tara. Nhập Secret Token: token SCIM.
Chọn Test Connection. Entra gọi endpoint của Tara; thành công nghĩa là URL và token đúng. Lưu lại.
Mở Mappings. Ở Provision Microsoft Entra ID Users, giữ các thuộc tính sau và bỏ phần còn lại:
Thuộc tính Entra ID Thuộc tính Tara (SCIM) userPrincipalNameuserNamemailemails[type eq "work"].valueSwitch([IsSoftDeleted], , "False", "True", "True", "False")activedisplayNamedisplayNamegivenNamename.givenNamesurnamename.familyNameobjectIdexternalIdBiểu thức của
activelà biểu thức Entra dùng mặc định trong các mapping SCIM; nếu mapping của bạn đã có dòngactivethì giữ nguyên.Ở Provision Microsoft Entra ID Groups, giữ mapping nhóm.
displayNamecủa nhóm là tên nhóm bạn ánh xạ sang role.Ở Settings, chọn Scope: thường chọn Sync only assigned users and groups. Rồi gán người và nhóm vào ứng dụng ở Users and groups.
Đặt Provisioning Status là On và lưu (nút có thể ghi là Start provisioning).
Email công việc phải là email của người đó ở công ty: Tara gắn người theo email này. Nếu một người không có giá trị mail, Tara lấy userName làm email, khi đó userPrincipalName phải là địa chỉ email thật.
Tara chỉ đọc các thuộc tính này của người dùng: userName, externalId, name (tên, họ, tên đầy đủ), displayName, email công việc trong emails và active. Thuộc tính khác Entra gửi được nhận rồi bỏ qua. Entra gửi active dạng chuỗi "False" hoặc "True" và viết thao tác là Replace, Add, Remove; Tara nhận cả hai.
Entra chạy một chu kỳ đồng bộ khoảng 40 phút một lần, nên thay đổi không tới ngay. Muốn thử một người, dùng Provision on demand của Entra.
Chuyện gì xảy ra
- Một người được gán vào ứng dụng. Entra tạo họ trong Tara. Nếu đã có người có tài khoản Tara với đúng email đã xác minh đó, họ được gắn ngay và thành thành viên. Nếu chưa, Tara giữ chỗ chờ theo email.
- Lần đăng nhập đầu. Khi người đó đăng nhập bằng SSO của tổ chức và email từ Entra khớp, Tara gắn tài khoản của họ rồi cho họ vào tổ chức với role theo nhóm.
- Entra vô hiệu hóa hoặc gỡ gán một người. Tara gỡ họ khỏi tổ chức và các project, họ không tốn seat, và đăng nhập SSO hay tự vào theo tên miền không đưa họ vào lại được. Nếu họ quay lại phạm vi đồng bộ, tư cách thành viên được khôi phục.
- Entra xóa một người. Tara gỡ họ khỏi tổ chức. Tài khoản Tara của họ không bị xóa.
- Owner không bao giờ bị đụng đến. SCIM không tạo, không đổi, không gỡ owner.
Nhóm và role
scimGroupRoles ánh xạ tên nhóm sang admin, member hoặc viewer (không bao giờ owner). Tên nhóm không phân biệt hoa thường.
- Người thuộc nhiều nhóm có ánh xạ nhận role cao nhất.
- Chưa đặt ánh xạ nào: mọi người được cấp phát đều là member.
- Đã đặt ánh xạ nhưng người đó không thuộc nhóm nào có ánh xạ: họ là viewer (miễn phí, không tốn seat).
- Người bạn thêm bằng tay hoặc bằng lời mời giữ nguyên role bạn đã cho. SCIM chỉ đổi role của thành viên vào bằng cách khác.
- Bạn đổi ánh xạ thì Tara cập nhật role của mọi người đã được gắn.
- Entra phải cấp phát người dùng trước rồi mới thêm họ vào nhóm. Tara từ chối thành viên nhóm mà nó chưa biết.
Seat và giới hạn
Admin và member tốn seat; viewer thì không. Hết seat theo gói, Entra nhận 409 với Seat limit reached trong phần chi tiết lỗi và hiện trong provisioning logs. Người đã được cấp phát vẫn giữ quyền. Hãy cho người mới role viewer qua một nhóm ánh xạ sang viewer, hoặc nâng gói (Thanh toán và nâng gói).
Kiểm tra kết quả
Mở Audit log trong Tara và tìm các hành động:
| Hành động | Ý nghĩa |
|---|---|
scim.user.create | Entra tạo một người |
scim.user.link | Đã gắn với tài khoản Tara (verified_email hoặc oidc_login) |
scim.user.role | Thêm tư cách thành viên hoặc đổi role |
scim.user.suspend, scim.user.reactivate | Entra vô hiệu hóa hoặc khôi phục |
scim.user.delete | Entra xóa người |
scim.group.create, scim.group.update, scim.group.delete | Thay đổi nhóm |
scim.group.roles | Owner lưu ánh xạ nhóm sang role |
scim_token.create, scim_token.revoke | Owner tạo hoặc thu hồi token |
Khi có lỗi
| Bạn thấy | Nguyên nhân |
|---|---|
401 | Secret token sai, hết hạn hoặc đã thu hồi. |
403 | Token thuộc tổ chức khác (kiểm tra slug trong Tenant URL), hoặc dùng credential không phải token SCIM. |
404 | Sai Tenant URL. Nó phải kết thúc bằng slug tổ chức, không có /Users. |
409 kèm uniqueness | Người khác trong tổ chức đã có userName, email hoặc externalId đó. |
409 kèm Seat limit reached | Hết seat cho role này. Xem phần trên. |
400 kèm invalidValue | Một người không có email công việc dùng được, hoặc thành viên nhóm chưa được cấp phát. |
400 kèm invalidFilter | Tara không hỗ trợ filter đó. Tara hỗ trợ eq trên userName, externalId, id, active và email công việc cho người dùng, và trên displayName, externalId, id cho nhóm. |
scim_suspended lúc đăng nhập | Người đó đang bị vô hiệu hóa trong Entra. |
Giới hạn
- Không có bulk, sort, ETag và thao tác mật khẩu.
- Filter chỉ có toán tử
eq. - Thuộc tính enterprise extension không được lưu.
Endpoint của Tara tự mô tả ở /scim/v2/orgs/<slug tổ chức>/ServiceProviderConfig.
Dùng Okta? Xem Cấp phát người dùng từ Okta bằng SCIM.