1.Overview
Chương trình Sophos Central’s Public API giúp bạn dễ dàng tự động hóa các hoạt động giám sát, bảo mật và quản trị mạng của mình trong Sophos Central. Bạn có thể làm nhiều việc mà bạn thường làm trong Sophos Central Admin hoặc Sophos Central Partner.
Tất cả các API của sophos được cung cấp dưới dạng RESTful HTTP endpoints được public trên internet. Sophos sử dụng xác thực tiêu chuẩn, các yêu cầu và phản hồi JSON và các HTTP tiêu chuẩn. Tất cả giao tiếp đều qua HTTPS.
2. Hiểu về Partners, organizations và tenants.
Để sử dụng các API của Sophos một cách hiệu quả, bạn cần biết các thuật ngữ sau. Sophos sử dụng nó trong tất cả các tài liệu:
Partners: Partners là một tổ chức kinh doanh, thường là Distributor, Value Added Reseller (VAR) hoặc Managed Service Provider (MSP) hoạt động trong kênh bán hàng của Sophos. Một Partners quản lý nhiều “tenants” và có thể bán phần mềm và dịch vụ của Sophos cho nhiều “organizations”.
Organizations: Organizations là một tổ chức kinh doanh sử dụng phần mềm và dịch vụ của Sophos. Một tổ chức có một hoặc nhiều tenants trong Sophos Central.
Tenants: Tenants là một tập hợp các “tài nguyên” thuộc sở hữu của một tổ chức. Một tổ chức thường tạo ra những tenants để cô lập dữ liệu. Họ cũng có thể tạo tenants để dễ quản lý. Những người làm việc cho tổ chức, thiết bị mà họ sở hữu, chính sách bảo mật được cấu hình bởi quản trị viên và các sự kiện bảo mật được tạo, tất cả đều là ví dụ về tài nguyên thuộc về tenants.
Note:
+ Một số tenant có thể không thuộc một tổ chức.
+ Trong tài liệu và giao diện người dùng, Sophos sử dụng thuật ngữ “khách hàng-customer” cho tenants do MSP quản lý và “doanh nghiệp-enterprise” cho các tổ chức. Sophos cũng gọi những tenants trong một tổ chức là “sub-estates”.
Bạn có thể xem sơ đồ dưới đây để biết cách các thực thể này liên quan với nhau:
Quy tắc call API:
+ Partners có thể call Partners API cũng như Tenant APIs cho tenants mà họ quản lý.
+ Các Organizations có thể call Organizations API của tổ chức cũng như Tenant APIs cho những Tenant là một phần của tổ chức của họ.
+ Tenant API bị giới hạn đối với các Tenant APIs và không thể call Partner API hoặc Organization API.
3. Global vs. regional APIs
Sophos Central là một hệ thống lớn, phân tán, toàn cầu, nhiều tenant, được triển khai dưới dạng nhiều bộ dịch vụ tại nhiều trung tâm dữ liệu trên khắp thế giới.
Vì Sophos Central hỗ trợ một số lượng lớn tenant và ngày càng tăng, Sophos cũng phân phối tenant-base của mình trên nhiều “data regions”. Tất cả dữ liệu của một tenant nhất định nằm trong một vùng dữ liệu duy nhất, được chọn khi bạn đăng ký. Hiện tại, Sophos vận hành sáu vùng dữ liệu như vậy và đang bổ sung thêm.
Để truy cập dữ liệu của tenant bằng API, bạn cần biết máy chủ lưu trữ API cho vùng dữ liệu của tenant.
Có nhiều cách khác nhau để tìm thông tin này:
+ Với tư cách là partner, bạn có thể liệt kê những tenant mà bạn quản lý, gọi GET /partner/ v1/tenants. Phản hồi sẽ liệt kê vùng dữ liệu và máy chủ API cho từng tenants.
+ Với tư cách là organization, bạn có thể liệt kê những tenants thuộc về bạn, gọi GET /organization/v1/tenants. Phản hồi liệt kê vùng dữ liệu và máy chủ API cho từng tenants.
+ Với tư cách là tenants, bạn có thể gọi GET /whoami /v1 để tìm vùng dữ liệu của riêng bạn.
Các API được liệt kê ở trên đều là “global” và có sẵn tại base URL: https://api.central.sophos.com.
Tất cả các API khác là “regional” và có sẵn tại một trong các base URLs sau:
4. Cách tạo một API call.
Trước khi thực hiện bất kỳ lệnh gọi API nào, bạn phải tạo service principal và xác thực với Sophos Central. Các API của Sophos sử dụng OAuth2, một cơ chế xác thực phổ biến và an toàn được sử dụng với nhiều API công khai.
4.1 Tạo một service principal
Partners có thể tạo service principal thông qua Sophos Central Partner. Xem hướng dẫn: https://developer.sophos.com/getting-started
Organizations có thể tạo service principal thông qua Sophos Central Enterprise. Xem hướng dẫn: https://developer.sophos.com/getting-started-organization
Tenants có thể tạo service principal thông qua Sophos Central Admin. Xem hướng dẫn: https://developer.sophos.com/getting-started-tenant
4.2 Xác thực
Service principal phải xác thực với Sophos ID, Identity Provider (IDP) của Sophos, để có được authentication token có giới hạn về thời gian và phạm vi. Các token này tuân theo tiêu chuẩn JSON Web Token (JWT).
Để có được JWT token, hãy thực hiện yêu cầu POST tới Sophos ID với Client ID và Client Secret cho service principal.
Example:
curl -XPOST -H 'Content-Type:application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&client_id=<id>&client_secret=<secret>&scope=token' \
https://id.sophos.com/api/v2/oauth2/token4.3 Ủy quyền
Service principal phải có bộ quyền phù hợp để thực hiện lệnh gọi API. Mặc dù các API của Sophos đang ở dạng Preview, Service principal sẽ có quyền truy cập vào chức năng hạn chế, nhưng tất cả quyền truy cập đều ở cấp SuperAdmin.
5. Status Codes Response
Tiêu chuẩn HTTP cho phép trả về rất nhiều status codes khác nhau từ các lệnh gọi API. Bạn có thể tìm hiểu ý nghĩa của các status codes này với bảng tổng hợp sau:
6. Error response object
Hầu hết các lệnh gọi API trả về một đối tượng lỗi JSON để chỉ ra lỗi, cùng với một trong các status codes lỗi ở trên. Đối tượng lỗi này có cấu trúc như sau:
