Cách cấu hình ánh xạ nhóm SAML với Microsoft Entra ID

Ánh xạ nhóm SAML gán quyền truy cập nhóm Apidog từ các nhóm có trong xác nhận SAML của người dùng. Nó giúp giảm bớt công việc quản lý thành viên nhóm thủ công trong khi vẫn giữ nhà cung cấp danh tính làm nguồn cho tư cách thành viên nhóm.

Hướng dẫn này sử dụng Microsoft Entra ID. Bạn sẽ thêm một yêu cầu (claim) `groups`, ánh xạ một nhóm Entra tới một nhóm Apidog và xác minh các quyền dự án ban đầu được gán khi đăng nhập.

Trước khi bắt đầu

Bạn cần:

• Một tổ chức Apidog Enterprise đã được cấu hình SAML SSO;
• Quyền truy cập Chủ sở hữu Tổ chức (Organization Owner) hoặc Quản trị viên Tổ chức (Organization Admin) trong Apidog;
• Quyền quản trị đối với ứng dụng doanh nghiệp Microsoft Entra được sử dụng cho Apidog;
• Ít nhất một nhóm Entra và một người dùng thử nghiệm được gán vào nhóm đó.

Nếu SAML chưa được cấu hình, hãy hoàn thành Cấu hình Microsoft Entra ID trước.

Ánh xạ nhóm SAML kiểm soát quyền truy cập vào các nhóm và dự án Apidog. Nó không cấp quyền truy cập vào các API sản xuất hoặc thay thế ủy quyền thời gian chạy.

Cách gán quyền truy cập dự án ban đầu

Khi một nhóm khớp, Apidog sẽ thêm người dùng vào nhóm đã ánh xạ và cấp quyền truy cập dự án ban đầu từ vai trò nhóm đã chọn.

Apidog tạo các thành viên dự án còn thiếu hoặc cập nhật các thành viên dự án chưa có vai trò. Một vai trò dự án được gán thủ công hiện có sẽ không bị ghi đè trong các lần đăng nhập SAML sau này.

Bước 1: Thêm yêu cầu `groups` trong Microsoft Entra ID

1. Đăng nhập vào trung tâm quản trị Microsoft Entra.
2. Đi tới **Enterprise applications** và mở ứng dụng được sử dụng cho Apidog SSO.
3. Chọn **Single sign-on**, sau đó mở **Attributes & Claims**.
4. Chọn **Add a group claim**.
5. Chọn **All groups**.
6. Bật **Customize the name of the group claim** và nhập `groups` làm tên yêu cầu (claim name).
7. Lưu yêu cầu.

Cấu hình yêu cầu nhóm để Apidog nhận ID đối tượng nhóm Entra trong thuộc tính `groups`.

Apidog sử dụng ID đối tượng nhóm trong yêu cầu này. Nó không truy xuất thông tin khác về các nhóm từ Microsoft Entra ID.

Bước 2: Sao chép tên nhóm Entra và ID đối tượng

1. Trong Microsoft Entra ID, mở **Groups**.
2. Chọn nhóm sẽ nhận quyền truy cập trong Apidog.
3. Sao chép **Name** và **Object ID** của nó.

Sử dụng ID đối tượng hiển thị trên trang nhóm Entra. Không sử dụng ID ứng dụng, ID đối tượng thuê hoặc tên hiển thị thay cho ID đối tượng.

Giữ trang này mở trong khi bạn cấu hình ánh xạ trong Apidog.

Bước 3: Ánh xạ nhóm tới một nhóm Apidog

1. Mở tổ chức trong Apidog.
2. Đi tới cài đặt **SAML Group** của tổ chức.
3. Thêm một ánh xạ nhóm.
4. Nhập tên nhóm Entra và dán ID đối tượng của nó.
5. Chọn nhóm hoặc các nhóm Apidog mà nhóm này nên truy cập.
6. Chọn vai trò nhóm cần thiết cho mỗi nhóm được ánh xạ.
7. Lưu ánh xạ.

Ánh xạ ID đối tượng nhóm Entra tới các nhóm Apidog và vai trò nhóm cần thiết.

Không có trình chọn vai trò dự án riêng biệt trong ánh xạ nhóm SAML. Vai trò dự án ban đầu đến từ vai trò nhóm được hiển thị trong bảng trên. Điều chỉnh vai trò dự án của người dùng sau này từ cài đặt thành viên dự án khi cần quyền truy cập khác.

Bước 4: Kiểm tra ánh xạ

Sử dụng tài khoản thử nghiệm thay vì tài khoản quản trị viên.

1. Xác nhận rằng người dùng thử nghiệm thuộc nhóm Entra đã ánh xạ.
2. Đăng xuất khỏi Apidog.
3. Đăng nhập qua điểm truy cập SSO của tổ chức.
4. Mở nhóm đã ánh xạ và xác nhận rằng nó có sẵn.
5. Kiểm tra vai trò nhóm của người dùng.
6. 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ó một vai trò dự án được gán thủ công, hãy xác nhận rằng vai trò đó vẫn không thay đổi sau một lần đăng nhập SSO khác.

Xác minh việc xóa thành viên

Việc xóa nhóm cũng nên được kiểm tra trước khi triển khai.

1. Xóa người dùng thử nghiệm khỏi nhóm Entra đã ánh xạ.
2. Cho phép thay đổi nhà cung cấp danh tính hoàn tất.
3. Yêu cầu người dùng đăng nhập lại qua SSO.
4. Kiểm tra tư cách thành viên nhóm tương ứng và tư cách thành viên dự án.

Khi một người dùng không còn thuộc một nhóm đã ánh xạ, Apidog có thể xóa người dùng đó khỏi nhóm tương ứng trong quá trình đồng bộ hóa SAML. Nếu tư cách thành viên nhóm bị xóa, tư cách thành viên dự án trong nhóm đó cũng sẽ bị xóa.

Không sử dụng tài khoản sản xuất cho thử nghiệm xóa đầu tiên. Ghi lại kết quả quan sát được cho cấu hình danh tính và quy trình ngừng cấp quyền của bạn.

Khắc phục sự cố

Các hạn chế quan trọng

• Apidog không tạo hoặc xóa các nhóm nhà cung cấp danh tính thông qua SCIM.
• Ánh xạ nhóm SAML không cung cấp cài đặt vai trò riêng biệt cho từng dự án.
• Các vai trò dự án đã gán hiện có không bị đặt lại trong các lần đăng nhập SSO sau này.
• Nếu một số ánh xạ có thể áp dụng cho cùng một người dùng và nhóm, hãy kiểm tra kết quả trước khi triển khai thay vì giả định một quy tắc ưu tiên.
• Các vai trò không gian làm việc không ủy quyền các cuộc gọi đến các API đã triển khai.

Các hướng dẫn quản trị API liên quan:

Các hướng dẫn này bao gồm các biện pháp kiểm soát bổ sung để quản lý không gian làm việc API của doanh nghiệp:

• Khung quản trị API — kết nối quyền sở hữu, kiểm soát, bằng chứng và các quyết định vòng đời.
• Ánh xạ nhóm SAML với Microsoft Entra ID — gán quyền truy cập nhóm từ các nhóm nhà cung cấp danh tính.
• Trình quét bí mật (Secret Scanner) — xem xét các thông tin xác thực có thể bị lộ trong các 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 suốt 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 các nhóm do thành viên tạo trong khi vẫn giữ quyền giám sát quyền sở hữu.
• Tích hợp GitHub Enterprise Cloud — kết nối các kho lưu trữ GHE.com được hỗ trợ cho quy trình làm việc OpenAPI.

Tài liệu chính thức liên quan:

• Ánh xạ nhóm tới các nhóm
• Cấu hình Microsoft Entra ID
• Giới thiệu về cấp phép SCIM
• Vai trò và quyền của tổ chức