مجاز کردن با واگذاری در سطح دامنه

Mail Admin Quarantine API برای خودکارسازی‌های سمت سرور مانند خطوط لوله امنیتی و ادغام‌های SIEM یا SOAR طراحی شده است. این خودکارسازی‌ها با حساب سرویس Google Cloud اصالت‌سنجی می‌شوند که از تفویض اختیار در سطح دامنه برای اقدام ازطرف سرپرست Google Workspace که دارای امتیاز سرپرست لازم است استفاده می‌کند.

این صفحه توضیح می‌دهد که API به کدام گستره‌های OAuth 2.0 نیاز دارد و چگونه می‌توان حساب سرویس را پیکربندی کرد و کد دسترسی دریافت کرد.

گستره‌های OAuth 2.0

«میانای برنامه‌سازی کاربردی قرنطینه سرپرست» از دامنه‌های OAuth 2.0 زیر استفاده می‌کند:

حوزه معنی
https://www.googleapis.com/auth/gmail.admin.quarantine مشاهده و مدیریت کردن پیام‌های قرنطینه‌شده. برای انتشار یا رد کردن پیام‌ها، به‌صورت تکی یا دسته‌ای، لازم است.
https://www.googleapis.com/auth/gmail.admin.quarantine.readonly مشاهده پیام‌های قرنطینه‌شده. برای فهرست کردن، جستجو کردن، و دریافت پیام‌ها، فهرست کردن و دریافت قرنطینه‌ها، و دریافت وضعیت عملیات دسته‌ای کافی است.

جدول زیر نشان می‌دهد هر روش کدام گستره را می‌پذیرد:

روش 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 ✓

از اصل حداقل امتیاز پیروی کنید: برای ادغام‌هایی که فقط قرنطینه را نظارت می‌کنند، حوزه فقط خواندنی را درخواست کنید.

اگر درخواستی از یک کد استفاده کند که شامل یک دامنه پذیرفته‌شده نباشد، API یک خطای 403 با دلیل ACCESS_TOKEN_SCOPE_INSUFFICIENT برمی‌گرداند.

ایجاد حساب سرویس

  1. در کنسول Google Cloud، به مدیریت هویت و دسترسی و سرپرست > حساب‌های سرویس بروید و پروژه Google Cloud را که در آن میانای برنامه‌سازی کاربردی را فعال کرده‌اید انتخاب کنید.
  2. روی ایجاد حساب سرویس کلیک کنید، نامی مثل quarantine-api-service-account وارد کنید، و روی ایجاد و ادامه کلیک کنید. لازم نیست هیچ نقش IAM به حساب سرویس اعطا کنید. روی تمام کلیک کنید.
  3. حساب سرویس را باز کنید و در برگه جزئیات، شناسه کارخواه OAuth 2 را کپی کنید. این شماره ۲۱ رقمی است، برای مثال 109876543210987654321. در بخش بعدی به این شناسه نیاز دارید.
  4. در برگه کلیدها، روی افزودن کلید > ایجاد کلید جدید کلیک کنید، JSON را انتخاب کنید، و روی ایجاد کلیک کنید. فایل کلید JSON بارگیری‌شده را به‌طور ایمن ذخیره کنید.

برای اطلاعات بیشتر، ایجاد اطلاعات کاربری برای حساب سرویس را ببینید.

مجاز کردن واگذاری در سطح دامنه

به حساب سرویس اجازه دهید به دامنه‌های Admin Quarantine API در حساب Google Workspace شما دسترسی داشته باشد:

  1. به‌عنوان اَبَرسرپرست به سیستم کنسول سرپرست Google وارد شوید.
  2. به امنیت > دسترسی و کنترل داده > کنترل‌های میانای برنامه‌سازی کاربردی بروید.
  3. در بخش واگذاری اختیارات در سراسر دامنه، روی مدیریت واگذاری اختیارات در سراسر دامنه کلیک کنید.
  4. روی افزودن جدید کلیک کنید.
  5. در فیلد شناسه کارخواه، شناسه کارخواه OAuth 2.0 حساب سرویس را وارد کنید. نشانی ایمیل حساب سرویس را وارد نکنید.

  6. در فیلد گستره‌های OAuth، یکی از گستره‌های زیر را وارد کنید:

    • برای دسترسی خواندن و نوشتن: https://www.googleapis.com/auth/gmail.admin.quarantine
    • برای دسترسی فقط خواندنی: https://www.googleapis.com/auth/gmail.admin.quarantine.readonly

  7. روی Authorize (صدور مجوز) کلیک کنید.

برای جزئیات، کنترل دسترسی به میانای برنامه‌سازی کاربردی با واگذاری سراسری دامنه را ببینید.

دریافت کد دسترسی

برای فراخوانی API، حساب سرویس با تنظیم کردن ادعای subject (sub) درخواست توکن روی نشانی ایمیل سرپرست، خود را به‌جای سرپرست جا می‌زند. سرپرست باید امتیاز سرپرست لازم را داشته باشد.

نمونه Python زیر از کتابخانه google-auth برای دریافت کد دسترسی استفاده می‌کند:

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

توکن را در سرایند Authorization هر درخواست ارسال کنید:

Authorization: Bearer ACCESS_TOKEN

کدهای دسترسی پس‌از یک ساعت منقضی می‌شوند. به‌جای ذخیره کردن موقت توکن‌ها برای مدت طولانی، اطلاعات کاربری را قبل‌از هر دسته درخواست بازآوری کنید.

عیب‌یابی خطاهای صدور مجوز

وضعیت HTTP استدلال وضوح
401 UNAUTHENTICATED سرایند Authorization وجود ندارد، یا قالب کد نادرست است یا منقضی شده است. کد دسترسی جدیدی دریافت کنید و آن را به‌عنوان رمزیاب دارنده اضافه کنید.
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT این توکن شامل حوزه‌ای نیست که روش می‌پذیرد. برای روش‌های انتشار و رد کردن، گستره https://www.googleapis.com/auth/gmail.admin.quarantine را درخواست کنید و مطمئن شوید گستره در «کنسول سرپرست» مجاز شده باشد.
403 PERMISSION_DENIED سرپرست جعل‌شده امتیاز قرنطینه سرپرست را ندارد یا به قرنطینه‌ای که پیام را نگه می‌دارد دسترسی ندارد. به سرپرست، دسترسی به قرنطینه سرپرست یا دسترسی به قرنطینه‌های محدودشده اعطا کنید.
‫403 SERVICE_DISABLED یا 404 NOT_FOUND در هر روش میانای برنامه‌سازی کاربردی در پروژه Cloud فعال نیست یا پروژه در «برنامه پیش‌نمایش توسعه‌دهندگان نرم‌افزار» ثبت‌نام نشده است. میانای برنامه‌سازی کاربردی را فعال کنید و ثبت‌نامتان را در Google Workspace Developer Preview Program تأیید کنید.

مراحل بعدی