Với Endpoint API sẽ cho phép quản lý chính sách cho một tenant tại một thời điểm. Nếu bạn là khách hàng của Sophos, bạn có thể sử dụng tenant API credentials của mình để gọi API. Partners có thể sử dụng API credentials của riêng họ để quản lý các chính sách dành cho tenant đã bật Partner assistance. Khách hàng doanh nghiệp có thể sử dụng API credential của riêng họ để quản lý các chính sách dành cho tenants (sub-estates) đã cho phép quản lý Enterprise Admin.

Bài viết hôm nay sẽ hướng dẫn các bạn cách quản lý và lấy thông các chính sách Endpoint Protection, Server Protection và Device Encryption bằng Endpoint API.

2. Hướng dẫn.

Trước khi đi vào hướng dẫn bạn cần có các thông tin về tenant (Sophos Central) của mình để có thể thực hiện gọi các API, bạn có thể tham khảo link bài viết sau: https://www.thegioifirewall.com/sophos-central-apis-huong-dan-cau-hinh-api-credentials-mangement-tren-sophos-central/

2.1 Get List Policy trên Tenant.

Bên dưới là dòng lệnh dùng để lấy thông tin về policy đã cấu hình cho endpoint có trên Sophos Central.

Curl.exe -XGET -H “Authorization: Bearer <jwt>” -H “X-Tenant-ID: <tenant-id>” <data-region>/<path>

Bạn thực hiện chỉnh sửa câu lệnh như sau:

<jwt>: copy và paste access_token.

<tenant-id>: copy và paste tenant id

<data-region>: điền link https://…

<path>: điền /endpoint/v1/policies

Sau khi đã chỉnh sửa, mở CMD trên endpoint, copy và paste dòng lệnh. Nhấn Enter. Thông tin xuất ra sẽ hiển thị như hình dưới.

Các policy được lấy ra này sẽ bao gồm các policy trong Endpoint Protection, Server Protection và Device Encryption

Để dễ dàng trong việc kiểm tra kết quả, bạn copy từ dòng {“items”:…cho đến cuối. Paste vô Visual Studio Code.

Trong giao diện Visual Studio Code, click chuột phải, chọn Fomat Document. Để chỉnh sửa thông tin từ dạng text ra dạng dòng lệnh sẽ dễ dàng cho việc kiểm tra.

Sau khi đã chuyển đổi xong. Thông tin sẽ được hiển thị như hình dưới.

Bạn có thể kiểm tra cấu hình của các policy. Ví dụ: web-control

ID: Đây là policy ID cho web-control. Bạn nên lưu lại policy ID này của các policy để có thể sử dụng cho các lệnh API sau mà không cần lấy lại.

Name: “block web”: Tên policy được tạo trong web control

Bạn kéo xuống phần “Endpoint.web-control.tag.settings”:

+ “tag”: các trang web được gắn cho policy

+ “action”: Block: Các trang web ở trên sẽ bị block khi user truy cập.

+ “appliesTo”: user: Policy đang được apply cho 1 user.

+ “createdAt”: Thời gian tạo policy.

2.2 Get single policy

Để gọi API lấy thông tin về 1 policy cụ thể mà không phải toàn bộ policy. Bạn chỉnh sửa lệnh API sau:

Curl.exe -XGET -H “Authorization: Bearer <jwt>” -H “X-Tenant-ID: <tenant-id>” <data-region>/<path>

<jwt>: paste dãy access_token

<tenant-id>: Paste tenant –id

<data-region>: Paste link https://…

<path>: Điền “endpoint/v1/policies/<policy ID>

Ví dụ: Policy-ID của Peripheral-control:

“id”: “30c7d8ec-d300-4402-b145-10e4f6e38d27”.

Copy lệnh API đã chỉnh sửa, paste lên CMD của endpoint.

Bạn copy kết quả paste vào Visual Studio Code, chỉnh sửa định dạng text dang định dạng code, bạn sẽ có kết quả lệnh API như bên dưới.

Bạn có thể kiểm tra một số setting như:

Cấu hình “removable storage” với setting là “ReadOnly“.

endpoint.peripheral-control.actions.removable-storage”: {

            “value”: “readOnly”

Các Peripheral-ID được set Allow để sử dụng.

Policy này được apply cho 1 endpoint.

2.3 Get Setting Policy.

Để gọi API lấy thông tin về setting của 1 policy cụ thể mà không phải toàn bộ policy. Bạn chỉnh sửa lệnh API sau:

Curl.exe -XGET -H “Authorization: Bearer <jwt>” -H “X-Tenant-ID: <tenant-id>” <data-region>/<path>

<jwt>: paste dãy access_token

<tenant-id>: Paste tenant –id

<data-region>: Paste link https://…

<path>: Điền “endpoint/v1/policies/<policy ID>/settings

Ví dụ: Bạn chỉ muốn xem settings của policy “block web“.

Policy-id“: “87e9f5d9-52a5-45ee-b51a-a55810b995b7“,

            “name”: “block web”,

            “type”: “web-control”.

Kết quả sẽ chỉ xuất ra các setting của policy id “block web“.

2.4 Get Setting Key.

Setting Key: Thể hiện 1 trong các setting có trong 1 policy được cấu hình.

Để gọi API lấy thông tin về 1 setting cụ thể của 1 policy nào đó mà không phải toàn bộ policy. Bạn chỉnh sửa lệnh API sau:

Curl.exe -XGET -H “Authorization: Bearer <jwt>” -H “X-Tenant-ID: <tenant-id>” <data-region>/<path>

<jwt>: paste dãy access_token

<tenant-id>: Paste tenant –id

<data-region>: Paste link https://…

<path>: Điền “endpoint/v1/policies/<policy ID>/settings/<SettingKey>.

Ví dụ: Bạn chỉ muốn xem 1 settings của policy “block web” trong web-control.

Ex settingkey: endpoint.web-control.tags.settings.

Kết quả.

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/token

4.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: