Ánh xạ nhóm SAML từ Microsoft Entra ID sang nhóm Apidog
Ánh xạ nhóm SAML tự động gán quyền truy cập nhóm Apidog theo các nhóm có trong xác nhận SAML của người dùng, giúp nhà cung cấp danh tính vẫn là nguồn quản lý thành viên nhóm.
Hãy dùng thử Apidog ngay hôm nay
Hướng dẫn này dùng Microsoft Entra ID để thêm claim groups, ánh xạ nhóm Entra sang nhóm Apidog và kiểm tra quyền dự án được cấp khi người dùng đăng nhập.
Trước khi bắt đầu
Bạn cần:
- Tổ chức Apidog Enterprise đã cấu hình SAML SSO;
- Quyền Organization Owner hoặc Organization Admin trong Apidog;
- Quyền quản trị ứng dụng doanh nghiệp Microsoft Entra dùng cho Apidog;
- Ít nhất một nhóm Entra và một người dùng thử nghiệm thuộc nhóm đó.
Nếu chưa cấu hình SAML, hãy hoàn tất Cấu hình Microsoft Entra ID.
Ánh xạ nhóm SAML chỉ kiểm soát quyền vào nhóm và dự án Apidog. Nó không cấp quyền gọi API sản xuất hoặc thay thế ủy quyền thời gian chạy.
Quyền dự án được cấp ban đầu
Khi một nhóm khớp, Apidog thêm người dùng vào nhóm đã ánh xạ và cấp quyền dự án ban đầu theo vai trò nhóm:
| Vai trò nhóm được ánh xạ | Vai trò dự án ban đầu |
|---|---|
| Quản trị viên nhóm (Team Admin) | Người duy trì dự án (Project Maintainer) |
| Thành viên nhóm (Team Member) | Chỉ đọc dự án (Project Readonly) |
| Khách nhóm (Team Guest) | Chỉ đọc dự án (Project Readonly) |
Apidog tạo thành viên dự án còn thiếu hoặc cập nhật thành viên chưa có vai trò. Vai trò dự án được gán thủ công sẽ không bị ghi đè trong các lần đăng nhập SAML sau.
Bước 1: Thêm claim groups trong Microsoft Entra ID
- Đăng nhập trung tâm quản trị Microsoft Entra.
- Vào Enterprise applications và mở ứng dụng dùng cho Apidog SSO.
- Chọn Single sign-on → Attributes & Claims.
- Chọn Add a group claim.
- Chọn All groups.
- Bật Customize the name of the group claim, rồi đặt tên claim là
groups. - Lưu cấu hình.
Định cấu hình claim để Apidog nhận ID đối tượng nhóm Entra trong thuộc tính groups.
Apidog dùng ID đối tượng nhóm trong claim này; nó không truy xuất thêm thông tin nhóm từ Microsoft Entra ID.
Bước 2: Lấy tên nhóm và Object ID
- Trong Microsoft Entra ID, mở Groups.
- Chọn nhóm cần cấp quyền vào Apidog.
- Sao chép Name và Object ID.
Dùng Object ID trên trang nhóm Entra. Không dùng Application ID, Tenant Object ID hoặc tên hiển thị.
Giữ trang này mở để dùng ID khi tạo ánh xạ trong Apidog.
Bước 3: Ánh xạ nhóm Entra sang nhóm Apidog
- Mở tổ chức trong Apidog.
- Vào phần cài đặt SAML Group.
- Thêm một ánh xạ nhóm.
- Nhập tên nhóm Entra và dán Object ID.
- Chọn nhóm Apidog mà nhóm Entra được phép truy cập.
- Chọn vai trò nhóm phù hợp cho từng nhóm Apidog.
- Lưu ánh xạ.
Ánh xạ Object ID của nhóm Entra tới nhóm Apidog và vai trò nhóm cần thiết.
Ánh xạ nhóm SAML không có bộ chọn vai trò dự án riêng. Vai trò dự án ban đầu được suy ra từ vai trò nhóm trong bảng trên. Khi cần quyền khác, hãy điều chỉnh vai trò của người dùng trong cài đặt thành viên dự án.
Bước 4: Kiểm tra ánh xạ
Dùng tài khoản thử nghiệm, không dùng tài khoản quản trị viên:
- Xác nhận người dùng thử nghiệm thuộc nhóm Entra đã ánh xạ.
- Đăng xuất khỏi Apidog.
- Đăng nhập qua điểm truy cập SSO của tổ chức.
- Mở nhóm Apidog đã ánh xạ và xác nhận người dùng có mặt.
- Kiểm tra vai trò nhóm.
- Mở các dự án của nhóm và xác nhận vai trò dự án ban đầu.
Nếu người dùng đã có vai trò dự án được gán thủ công, hãy đăng nhập SSO thêm một lần để xác nhận vai trò đó không đổi.
Xác minh việc xóa thành viên
Kiểm tra quy trình thu hồi quyền trước khi triển khai:
- Xóa người dùng thử nghiệm khỏi nhóm Entra đã ánh xạ.
- Chờ thay đổi được đồng bộ tại nhà cung cấp danh tính.
- Yêu cầu người dùng đăng nhập lại qua SSO.
- Kiểm tra tư cách thành viên nhóm và dự án tương ứng trong Apidog.
Khi người dùng không còn thuộc nhóm Entra đã ánh xạ, Apidog có thể xóa họ khỏi nhóm Apidog tương ứng trong quá trình đồng bộ SAML. Nếu thành viên nhóm bị xóa, tư cách thành viên dự án thuộc nhóm đó cũng bị xóa.
Không dùng tài khoản sản xuất cho lần thử xóa đầu tiên. Hãy ghi lại kết quả cho quy trình quản lý danh tính và ngừng cấp quyền.
Khắc phục sự cố
| Vấn đề | Cần kiểm tra |
|---|---|
| Người dùng đăng nhập nhưng không được thêm vào nhóm | Claim phải có tên chính xác là groups; xác nhận phải chứa đúng Object ID; Object ID trong Apidog không được có khoảng trắng thừa. |
| Xác nhận không có giá trị nhóm | Xác nhận người dùng thuộc nhóm và ứng dụng doanh nghiệp Entra đang gửi claim nhóm. Với người dùng có nhiều nhóm, xem hướng dẫn Microsoft về quá tải claim nhóm. |
| Người dùng có vai trò dự án sai | Kiểm tra vai trò nhóm đã ánh xạ. Vai trò dự án đã gán thủ công không bị SAML ghi đè. |
| Thay đổi nhóm không được phản ánh | Xác nhận thay đổi đã có trong Entra, sau đó bắt đầu một phiên đăng nhập SSO mới để Apidog đồng bộ xác nhận hiện tại. |
| Người dùng vẫn ở trong tổ chức | Ánh xạ nhóm SAML chỉ quản lý quyền vào các nhóm đã ánh xạ. Thành viên tổ chức cũng có thể được quản lý qua lời mời, SSO hoặc SCIM. |
Các hạn chế quan trọng
- Apidog không tạo hoặc xóa nhóm của nhà cung cấp danh tính qua SCIM.
- Ánh xạ nhóm SAML không cung cấp vai trò riêng cho từng dự án.
- Vai trò dự án đã được gán sẽ không bị đặt lại ở các lần đăng nhập SSO sau.
- Nếu nhiều ánh xạ cùng áp dụng cho một người dùng và nhóm, hãy kiểm tra kết quả thực tế trước khi triển khai.
- Vai trò không gian làm việc không ủy quyền các cuộc gọi tới API đã triển khai.
Hướng dẫn quản trị API liên quan
- Khung quản trị API — kết nối quyền sở hữu, kiểm soát, bằng chứng và quyết định vòng đời.
- Ánh xạ nhóm SAML với Microsoft Entra ID — gán quyền nhóm từ nhóm nhà cung cấp danh tính.
- Trình quét bí mật (Secret Scanner) — kiểm tra thông tin xác thực có thể bị lộ trong tài sản Apidog được hỗ trợ.
- Nhật ký kiểm tra (Audit Logs) — điều tra và xuất hoạt động quản trị tổ chức.
- Cấp phép SCIM (SCIM Provisioning) — quản lý người dùng tổ chức trong toàn bộ vòng đời danh tính.
- Chính sách doanh nghiệp (Enterprise Policies) — cấu hình thông tin xác thực, thành viên, phiên SSO và kiểm soát lời mời.
- Các nhóm API tự phục vụ được quản lý — cho phép thành viên tạo nhóm nhưng vẫn duy trì giám sát quyền sở hữu.
- Tích hợp GitHub Enterprise Cloud — kết nối kho lưu trữ GHE.com được hỗ trợ với quy trình OpenAPI.
Top comments (0)