Uỷ quyền bằng tính năng uỷ quyền trên toàn miền

Mail Admin Quarantine API được thiết kế cho các quy trình tự động hoá phía máy chủ, chẳng hạn như quy trình bảo mật và tích hợp SIEM hoặc SOAR. Các quy trình tự động hoá này xác thực bằng một tài khoản dịch vụ Google Cloud sử dụng quyền uỷ quyền trên toàn miền để thay mặt một quản trị viên Google Workspace có đặc quyền của quản trị viên cần thiết.

Trang này giải thích những phạm vi OAuth 2.0 mà API yêu cầu, cũng như cách định cấu hình tài khoản dịch vụ và lấy mã truy cập.

Phạm vi OAuth 2.0

API Khu vực cách ly của quản trị viên sử dụng các phạm vi OAuth 2.0 sau:

Phạm vi Ý nghĩa
https://www.googleapis.com/auth/gmail.admin.quarantine Xem và quản lý thư bị cách ly. Cần thiết để phát hành hoặc từ chối thư, riêng lẻ hoặc theo lô.
https://www.googleapis.com/auth/gmail.admin.quarantine.readonly Xem thư bị cách ly. Đủ để liệt kê, tìm kiếm và nhận thư, liệt kê và nhận thư cách ly, cũng như nhận trạng thái của các thao tác hàng loạt.

Bảng sau đây cho biết phạm vi mà mỗi phương thức chấp nhận:

Phương thức gmail.admin.quarantine gmail.admin.quarantine.readonly
customers.quarantinedMessages.list ✓ ✓
customers.quarantinedMessages.search ✓ ✓
customers.quarantinedMessages.get ✓ ✓
customers.quarantines.list ✓ ✓
customers.quarantines.get ✓ ✓
customers.operations.get ✓ ✓
customers.quarantinedMessages.release ✓
customers.quarantinedMessages.deny ✓
customers.quarantinedMessages.batchRelease ✓
customers.quarantinedMessages.batchDeny ✓

Tuân thủ nguyên tắc về đặc quyền tối thiểu: yêu cầu phạm vi chỉ có thể đọc đối với những hoạt động tích hợp chỉ giám sát việc cách ly.

Nếu một yêu cầu sử dụng mã thông báo không bao gồm phạm vi được chấp nhận, thì API sẽ trả về lỗi 403 kèm theo lý do ACCESS_TOKEN_SCOPE_INSUFFICIENT.

Tạo một tài khoản dịch vụ

  1. Trong Google Cloud Console, hãy chuyển đến IAM & Admin > Service Accounts (IAM và Quản trị > Tài khoản dịch vụ) rồi chọn dự án trên đám mây của Google mà bạn đã bật API.
  2. Nhấp vào Tạo tài khoản dịch vụ, nhập tên (chẳng hạn như quarantine-api-service-account) rồi nhấp vào Tạo và tiếp tục. Bạn không cần cấp bất kỳ vai trò IAM nào cho tài khoản dịch vụ. Nhấp vào Xong.
  3. Mở tài khoản dịch vụ và trong thẻ Chi tiết, hãy sao chép Mã ứng dụng khách OAuth 2. Đây là một số gồm 21 chữ số, ví dụ: 109876543210987654321. Bạn cần có mã nhận dạng này trong phần tiếp theo.
  4. Trong thẻ Khoá, hãy nhấp vào Thêm khoá > Tạo khoá mới, chọn JSON rồi nhấp vào Tạo. Lưu trữ tệp khoá JSON đã tải xuống một cách an toàn.

Để biết thêm thông tin, hãy xem bài viết Tạo thông tin xác thực cho tài khoản dịch vụ.

Uỷ quyền trên toàn miền

Uỷ quyền cho tài khoản dịch vụ truy cập vào phạm vi API cách ly của quản trị viên trong tài khoản Google Workspace của bạn:

  1. Đăng nhập vào Bảng điều khiển dành cho quản trị viên của Google bằng tài khoản quản trị viên cấp cao.
  2. Chuyển đến phần Bảo mật > Quyền truy cập và kiểm soát dữ liệu > Chế độ kiểm soát API.
  3. Trong phần Uỷ quyền trên toàn miền, hãy nhấp vào Quản lý uỷ quyền trên toàn miền.
  4. Nhấp vào Thêm mới.
  5. Trong trường Mã ứng dụng khách, hãy nhập Mã ứng dụng khách OAuth 2.0 của tài khoản dịch vụ. Đừng nhập địa chỉ email của tài khoản dịch vụ.

  6. Trong trường Phạm vi OAuth, hãy nhập một trong các phạm vi sau:

    • Đối với quyền đọc và ghi: https://www.googleapis.com/auth/gmail.admin.quarantine
    • Đối với quyền chỉ có thể đọc: https://www.googleapis.com/auth/gmail.admin.quarantine.readonly

  7. Nhấp vào Uỷ quyền.

Để biết thông tin chi tiết, hãy xem bài viết Kiểm soát quyền truy cập API bằng tính năng uỷ quyền trên toàn miền.

Lấy mã truy cập

Để gọi API, tài khoản dịch vụ sẽ mạo danh quản trị viên bằng cách đặt thông tin xác nhận quyền sở hữu subject (sub) của yêu cầu mã thông báo thành địa chỉ email của quản trị viên. Quản trị viên phải có đặc quyền của quản trị viên cần thiết.

Ví dụ về Python sau đây sử dụng thư viện google-auth để lấy mã truy cập:

from google.oauth2 import service_account
import google.auth.transport.requests

SERVICE_ACCOUNT_FILE = 'service_account.json'
# An administrator with the Access Admin Quarantine privilege.
ADMIN_EMAIL = 'admin@example.com'
SCOPES = ['https://www.googleapis.com/auth/gmail.admin.quarantine']

credentials = service_account.Credentials.from_service_account_file(
    SERVICE_ACCOUNT_FILE,
    scopes=SCOPES,
    subject=ADMIN_EMAIL,
)
credentials.refresh(google.auth.transport.requests.Request())
access_token = credentials.token

Gửi mã thông báo trong tiêu đề Authorization của mọi yêu cầu:

Authorization: Bearer ACCESS_TOKEN

Mã truy cập sẽ hết hạn sau một giờ. Làm mới thông tin xác thực trước mỗi lô yêu cầu thay vì lưu mã thông báo vào bộ nhớ đệm trong thời gian dài.

Khắc phục sự cố uỷ quyền

Trạng thái HTTP Lý do Độ phân giải
401 UNAUTHENTICATED Thiếu tiêu đề Authorization hoặc mã thông báo không đúng định dạng hoặc đã hết hạn. Lấy mã truy cập mới và thêm mã đó làm mã thông báo truy cập.
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT Mã thông báo không bao gồm phạm vi mà phương thức chấp nhận. Yêu cầu phạm vi https://www.googleapis.com/auth/gmail.admin.quarantine cho các phương thức phát hành và từ chối, đồng thời đảm bảo phạm vi này được cho phép trong Bảng điều khiển dành cho quản trị viên.
403 PERMISSION_DENIED Quản trị viên được mạo danh không có đặc quyền quản trị khu vực cách ly hoặc không có quyền truy cập vào khu vực cách ly chứa thư. Cấp quyền Truy cập vào vùng cách ly quản trị hoặc Truy cập vào vùng cách ly bị hạn chế cho quản trị viên.
403 SERVICE_DISABLED hoặc 404 NOT_FOUND cho mọi phương thức API này chưa được bật trong dự án trên Cloud hoặc dự án này chưa được đăng ký tham gia Chương trình xem trước dành cho nhà phát triển. Bật API và xác nhận rằng bạn đã đăng ký tham gia Chương trình Bản dùng trước cho nhà phát triển của Google Workspace.

Các bước tiếp theo